constants.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 5a945dfef09a9595c83855cdb858ffa4a96af305 Maintainer: sammywg Status: ready -->
<!-- Reviewed: yes -->
<!-- Rev-Revision: 5a945dfef09a9595c83855cdb858ffa4a96af305 Reviewer: samesch -->
 <chapter xml:id="language.constants" xmlns="http://docbook.org/ns/docbook">
  <title>Konstanten</title>

  <simpara>
   Eine Konstante ist ein Bezeichner (Name) für einen einfachen Wert. Wie der
   Name bereits nahelegt, kann der Wert einer Konstanten zur Laufzeit des
   Skripts nicht verändert werden (außer bei
   <link linkend="language.constants.magic">Magischen Konstanten</link>, die
   nicht wirklich Konstanten sind). Konstanten unterscheiden standardmäßig
   zwischen Groß- und Kleinschreibung. Nach gängiger Konvention werden
   Konstanten immer in Großbuchstaben geschrieben.
  </simpara>

  <note>
   <para>
    Vor PHP 8.0.0 konnten Konstanten, die mit der Funktion
    <function>define</function> definiert wurden, ohne Berücksichtigung der
    Groß- und Kleinschreibung verwendet werden.
   </para>
  </note>

  <para>
   Der Name einer Konstanten folgt den gleichen Regeln wie alle anderen
   Bezeichner in PHP. Ein gültiger Name beginnt mit einem Buchstaben oder
   einem Unterstrich, gefolgt von beliebig vielen Buchstaben, Ziffern oder
   Unterstrichen. Als regulärer Ausdruck könnte das so beschrieben werden:
   <code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>
  </para>
  <para>
   Es ist möglich, Konstanten mit reservierten oder gar ungültigen Namen
   mittels <function>define</function> zu definieren, deren Wert nur mit der
   Funktion <function>constant</function> gelesen werden kann. Allerdings wird
   dies nicht empfohlen.
  </para>
  &tip.userlandnaming;
  <para>
<!-- TODO Move into syntax section? -->
   <example>
    <title>Gültige und ungültige Namen für Konstanten</title>
    <programlisting role="php">
<![CDATA[
<?php

// Gültige Namen für Konstanten
define("FOO",     "irgendwas");
define("FOO2",    "etwas anderes");
define("FOO_BAR", "irgendwas ganz anderes");

// Ungültige Namen für Konstanten
define("2FOO",    "irgendwas");

// Folgendes ist korrekt, sollte aber vermieden werden:
// PHP könnte eines Tages eine magische Konstante unterstützen,
// die Ihr Skript nicht mehr wie gewünscht funktionieren lässt
define("__FOO__", "irgendwas");

?>
]]>
    </programlisting>
   </example>
  </para>
  <note>
   <simpara>
    Für unsere Zwecke ist hier ein Buchstabe a-z, A-Z und die ASCII-Zeichen
    von 128 bis 255 (0x80-0xff).
   </simpara>
  </note>

  <simpara>
   Wie bei &link.superglobals; ist der Geltungsbereich einer Konstanten
   global. Unabhängig vom Geltungsbereich kann in einem Skript überall auf
   eine Konstante zugegriffen werden. Für mehr Information zum Geltungsbereich
   lesen Sie bitte den Abschnitt über den
   <link linkend="language.variables.scope">Geltungsbereich von Variablen</link>.
  </simpara>

  <note>
   <simpara>
    Seit PHP 7.1.0 können Klassenkonstanten eine Sichtbarkeit von protected
    oder private deklarieren, wodurch sie nur im hierarchischen Bereich der
    Klasse zur Verfügung stehen, in der sie definiert sind.
   </simpara>
  </note>

  <sect1 xml:id="language.constants.syntax">
   <title>Syntax</title>
   <simpara>
    Konstanten können mit dem Schlüsselwort <literal>const</literal> oder mit
    der Funktion <function>define</function> definiert werden. Während
    <function>define</function> es ermöglicht, eine Konstante auf einen
    beliebigen Wert zu definieren, hat das Schlüsselwort
    <literal>const</literal> Einschränkungen, die im nächsten Absatz
    beschrieben werden. Einmal definiert, kann eine Konstante weder verändert
    noch gelöscht werden.
   </simpara>
   <simpara>
    Wenn das Schlüsselwort <literal>const</literal> verwendet wird, werden nur
    skalare Ausdrücke (<type>bool</type>, <type>int</type>, <type>float</type>
    und <type>string</type>) und konstante <type>Array</type>s, die nur
    skalare Ausdrücke enthalten, akzeptiert. Es ist möglich, Konstanten vom
    Typ <type>resource</type> zu definieren, dies sollte allerdings vermieden
    werden, da es zu unerwarteten Ergebnissen führen kann.
   </simpara>
   <simpara>
    Auf den Wert einer Konstanten wird einfach durch die Angabe ihres Namens
    zugegriffen. Im Gegensatz zu Variablen wird einer Konstanten
    <emphasis>kein</emphasis> <literal>$</literal> vorangestellt. Ebenso kann
    die Funktion <function>constant</function> verwendet werden, um den Wert
    einer Konstanten auszulesen, wenn der Name der Konstanten dynamisch
    ermittelt wird. Mit der Funktion
    <function>get_defined_constants</function> erhält man eine Liste aller
    definierten Konstanten.
   </simpara>

   <note>
    <simpara>
     Konstanten und (globale) Variablen befinden sich in unterschiedlichen
     Namensräumen. Das hat zum Beispiel zur Folge, dass &true; und
     <varname>$TRUE</varname> etwas völlig Verschiedenes sind.
    </simpara>
   </note>

   <simpara>
    Falls eine undefinierte Konstante verwendet wird, wird ein
    <classname>Error</classname> ausgelöst. Vor PHP 8.0.0 wurden undefinierte
    Konstanten als einfaches <type>&string;</type>-Wort (d. h. CONSTANT vs
    "CONSTANT") interpretiert. Dieses Rückfallverhalten ist von PHP 7.2.0 an
    missbilligt, und ein Fehler der Stufe <constant>E_WARNING</constant> wird
    ausgelöst, wenn es dazu kommt. Vor PHP 7.2.0 wurde stattdessen ein Fehler
    der Stufe
    <link linkend="ref.errorfunc">E_NOTICE</link><constant>E_NOTICE</constant>
    ausgelöst. Siehe auch den Abschnitt im Handbuch, der erklärt, warum
    <link linkend="language.types.array.foo-bar">$foo[bar]</link> falsch ist
    (es sei denn, <literal>bar</literal> ist eine Konstante). Dies gilt nicht
    für
    <link linkend="language.namespaces.rules">(vollständig) qualifizierte Konstanten</link>,
    die immer einen <classname>Error</classname> auslösen, wenn sie
    undefiniert sind.
   </simpara>

   <note>
    <simpara>
     Um zu prüfen, ob eine Konstante gesetzt ist, kann die Funktion
     <function>defined</function> verwendet werden.
    </simpara>
   </note>

   <para>
    Dies sind die Unterschiede zwischen Konstanten und Variablen:
    <itemizedlist>
     <listitem>
      <simpara>
       Konstanten haben kein Dollarzeichen (<literal>$</literal>) vorangestellt;
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Konstanten können überall definiert werden und auf Ihren Wert kann ohne
       Rücksicht auf die Regeln des Geltungsbereichs von Variablen zugegriffen
       werden;
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Sobald Konstanten definiert sind, können sie nicht neu definiert oder
       gelöscht werden; und
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Konstanten können nur als skalare Werte oder Arrays ausgewertet werden.
      </simpara>
     </listitem>
    </itemizedlist>
   </para>

   <para>
    <example>
     <title>Definition von Konstanten</title>
     <programlisting role="php">
<![CDATA[
<?php
define("KONSTANTE", "Hallo Welt.");
echo KONSTANTE;     // Ausgabe: "Hallo Welt."
echo Konstante;     // Gibt einen Fehler aus: Undefined Constant "Konstante"
                    // Vor PHP 8.0.0 wird "Konstante" ausgegeben und eine
                    // Warnung angezeigt.
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>Definition von Konstanten unter Verwendung des Schlüsselworts <literal>const</literal></title>
     <programlisting role="php">
<![CDATA[
<?php
// Einfacher skalarer Wert
const KONSTANTE = 'Hallo Welt';

echo KONSTANTE;

// Skalarer Ausdruck
const ANDERE_KONSTANTE = KONSTANTE . '; Ade Welt';
echo ANDERE_KONSTANTE;

const ANIMALS = array('Hund', 'Katze', 'Maus');
echo ANIMALS[1]; // gibt "Katze" aus

// Array-Konstante
define('ANIMALS', array(
    'Hund',
    'Katze',
    'Maus'
));
echo ANIMALS[1]; // gibt "Katze" aus
?>
]]>
     </programlisting>
    </example>
   </para>

   <note>
    <para>
     Im Gegensatz zu Konstanten, welche mit <function>define</function>
     erstellt werden, müssen über <literal>const</literal> definierte
     Konstanten auf der höchsten Ebene erstellt werden, weil sie bei der
     Kompilierung definiert werden. Das heißt, dass sie nicht innerhalb von
     Funktionen, Schleifen, <literal>if</literal>-Anweisungen oder
     <literal>try</literal>/<literal>catch</literal>-Blöcken definiert werden
     können.
    </para>
   </note>

   <sect2 role="seealso">
    &reftitle.seealso;
    <para>
     <simplelist>
      <member><link linkend="language.oop5.constants">Klassenkonstanten</link></member>
     </simplelist>
    </para>
   </sect2>
  </sect1>

  <sect1 xml:id="language.constants.predefined">
   <title>Vordefinierte Konstanten</title>

   <simpara>
    PHP stellt jedem Skript zur Laufzeit eine Vielzahl von
    <link linkend="reserved.constants">vordefinierten Konstanten</link> zur
    Verfügung. Viele dieser Konstanten werden jedoch von verschiedenen
    Erweiterungen definiert, die nur zur Verfügung stehen, wenn diese
    Erweiterungen selbst zur Verfügung stehen, d. h. entweder über dynamisches
    Laden zur Laufzeit oder Einkompilieren.
   </simpara>
  </sect1>

  <sect1 xml:id="language.constants.magic">
   <title>Magische Konstanten</title>
   <para>
    Es gibt neun magische Konstanten, die, abhängig davon, wo sie eingesetzt
    werden, einen unterschiedlichen Wert haben. Zum Beispiel hängt der Wert
    der Konstanten <constant>__LINE__</constant> davon ab, in welcher Zeile
    des Skripts diese Konstante verwendet wird. Alle diese "magischen"
    Konstanten werden während der Kompilierzeit aufgelöst, im Gegensatz zu
    regulären Konstanten, die während der Laufzeit aufgelöst werden. Diese
    besonderen Konstanten sind unabhängig von Groß-/Kleinschreibung und sind
    folgende:
   </para>
   <para>
    <table>
     <title>PHP's magische Konstanten</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>&Name;</entry>
        <entry>&Description;</entry>
       </row>
      </thead>
      <tbody>
       <row xml:id="constant.line">
        <entry><constant>__LINE__</constant></entry>
        <entry>
         Die aktuelle Zeilennummer einer Datei.
        </entry>
       </row>
       <row xml:id="constant.file">
        <entry><constant>__FILE__</constant></entry>
        <entry>
         Der vollständige Pfad- und Dateiname einer Datei mit aufgelösten
         Symlinks. Wird diese Konstante innerhalb einer nachgeladenen Datei
         verwendet, wird der Name dieser eingebundenen Datei zurückgegeben.
        </entry>
       </row>
       <row xml:id="constant.dir">
        <entry><constant>__DIR__</constant></entry>
        <entry>
         Der Name des Verzeichnisses, in dem sich die Datei befindet. Wird die
         Konstante innerhalb eines Includes verwendet, wird das Verzeichnis
         der eingebundenen Datei zurückgegeben. Dies entspricht dem Verhalten
         von <literal>dirname(__FILE__)</literal>. Der Verzeichnisname hat
         keinen beendenden Schrägstrich, sofern es sich nicht um das
         Rootverzeichnis handelt.
        </entry>
       </row>
       <row xml:id="constant.function">
        <entry><constant>__FUNCTION__</constant></entry>
        <entry>
         Der Name der Funktion, oder <literal>{closure}</literal> für anonyme
         Funktionen.
        </entry>
       </row>
       <row xml:id="constant.class">
        <entry><constant>__CLASS__</constant></entry>
        <entry>
         Der Name einer Klasse. Der Klassenname enthält den Namen des
         Namensraums, in dem sie deklariert wurde (z. B.
         <literal>Foo\Bar</literal>). Bei Verwendung in einer Trait-Methode,
         ist __CLASS__ der Name der Klasse, in der der Trait verwendet wird.
        </entry>
       </row>
       <row xml:id="constant.trait">
        <entry><constant>__TRAIT__</constant></entry>
        <entry>
         Der Name eines Traits. Dieser enthält auch den Namensraum, in welchem
         der Trait definiert wurde (z. B. <literal>Foo\Bar</literal>).
        </entry>
       </row>
       <row xml:id="constant.method">
        <entry><constant>__METHOD__</constant></entry>
        <entry>
         Der Name der Klassenmethode.
        </entry>
       </row>
       <row xml:id="constant.namespace">
        <entry><constant>__NAMESPACE__</constant></entry>
        <entry>
         Der Name des aktuellen Namensraums.
        </entry>
       </row>
       <row xml:id="constant.coloncolonclass">
        <entry><constant><replaceable>ClassName</replaceable>::class</constant></entry>
        <entry>
         Der vollständig qualifizierte Klassenname.
        </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>

   <sect2 role="seealso">
    &reftitle.seealso;
    <para>
     <simplelist>
      <member><link linkend="language.oop5.basic.class.class">::class</link></member>
      <member><function>get_class</function></member>
      <member><function>get_object_vars</function></member>
      <member><function>file_exists</function></member>
      <member><function>function_exists</function></member>
     </simplelist>
    </para>
   </sect2>

  </sect1>
 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->