properties.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: c1f37a6c270aadbbb3da56a3973ffd62197adf2b Maintainer: simp Status: ready -->
<!-- Reviewed: no -->
 <sect1 xml:id="language.oop5.properties" xmlns="http://docbook.org/ns/docbook">
  <title>Eigenschaften</title>

  <para>
   Variablen in einer Klasse werden <emphasis>Eigenschaften</emphasis> genannt.
   Andere Begriffe wie <emphasis>Felder</emphasis> werden ebenfalls verwendet,
   um sich auf dasselbe Konzept zu beziehen, aber innerhalb dieser Referenz
   wird der Begriff <emphasis>Eigenschaften</emphasis> verwendet. Diese werden
   definiert, indem mindestens ein Modifikator (wie
   <xref linkend="language.oop5.visibility"/>,
   <xref linkend="language.oop5.static"/> oder, seit PHP 8.1.0,
   <link linkend="language.oop5.properties.readonly-properties">readonly</link>)
   verwendet wird, seit PHP 7.4 optional (außer für
   <code>readonly</code>-Eigenschaften) gefolgt von einer Typdeklaration,
   gefolgt von einer regulären Variablendeklaration. Die Deklaration darf eine
   Initialisierung des Variablenwertes beinhalten, der zu setzende Wert muss
   dabei allerdings ein <link linkend="language.constants">konstanter</link>
   Wert sein.
  </para>
  <note>
   <para>
    Eine veraltete Art, Klasseneigenschaften zu deklarieren, ist die
    Verwendung des Schlüsselwors <literal>var</literal> anstelle eines
    Modifikators.
   </para>
  </note>
  <note>
   <simpara>
    Eine Eigenschaft, die ohne Modifikator für
    <xref linkend="language.oop5.visibility"/> deklariert wird, wird
    als <literal>public</literal> deklariert.
   </simpara>
  </note>
  <para>
   Innerhalb der Methoden einer Klasse kann auf nicht-statische Eigenschaften
   zugegriffen werden, indem man (den Objektoperator) <literal>-&gt;</literal>
   verwendet: <varname>$this-&gt;property</varname> (wobei
   <literal>property</literal> der Name der Eigenschaft ist). Zugriff auf
   statische Eigenschaften erhält man, indem man (den Doppel-Doppelpunkt)
   <literal>::</literal> verwendet: <varname>self::$property</varname>. Siehe
   auch <xref linkend="language.oop5.static" /> für mehr Informationen zu
   diesem Thema.
  </para>
  <para>
   Die Pseudo-Variable <varname>$this</varname> ist innerhalb jeder
   Klassenmethode verfügbar, wenn diese Methode im Kontext eines Objektes
   aufgerufen wird. <varname>$this</varname> ist der Wert des aufrufenden
   Objekts.
  </para>

  <para>
   <example>
    <title>Deklaration von Eigenschaften</title>
    <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
class SimpleClass
{
   public $var1 = 'Hallo ' . 'Welt';
   public $var2 = <<<EOD
Hallo Welt
EOD;
   public $var3 = 1+2;
   // Ungültige Deklarationen von Eigenschaften:
   public $var4 = self::myStaticMethod();
   public $var5 = $myVar;

   // Gültige Deklarationen von Eigenschaften:
   public $var6 = myConstant;
   public $var7 = [true, false];

   public $var8 = <<<'EOD'
Hallo Welt
EOD;

   // Ohne Modifikator für Sichtbarkeit (Zugriffsrechte):
   static $var9;
   readonly int $var10;
}
?>
]]>
    </programlisting>
   </example>
  </para>

  <note>
   <para>
    Es gibt verschiedene Funktionen für den Umgang mit Klassen und Objekten.
    Siehe hierzu
    <link linkend="ref.classobj">Klassen- und Objekt-Funktionen</link>.
   </para>
  </note>

  <sect2 xml:id="language.oop5.properties.typed-properties">
   <title>Deklaration von Typen</title>
   <para>
    Von PHP 7.4.0 an können Eigenschaftsdefinitionen
    <xref linkend="language.types.declarations" /> enthalten, mit Ausnahme des
    Typs <type>callable</type>.
    <example>
     <title>Beispiel von typisierten Eigenschaften</title>
     <programlisting role="php">
<![CDATA[
<?php

class User
{
    public int $id;
    public ?string $name;

    public function __construct(int $id, ?string $name)
    {
        $this->id = $id;
        $this->name = $name;
    }
}

$user = new User(1234, null);

var_dump($user->id);
var_dump($user->name);

?>
]]>
     </programlisting>
     &example.outputs;
     <screen>
<![CDATA[
int(1234)
NULL
]]>
     </screen>
    </example>
   </para>

   <para>
    Typisierte Eigenschaften müssen vor dem Zugriff initialisiert werden,
    sonst wird ein <classname>Error</classname> ausgelöst.
    <example>
     <title>Auf Eigenschaften zugreifen</title>
     <programlisting role="php">
<![CDATA[
<?php

class Shape
{
    public int $numberOfSides;
    public string $name;

    public function setNumberOfSides(int $numberOfSides): void
    {
        $this->numberOfSides = $numberOfSides;
    }

    public function setName(string $name): void
    {
        $this->name = $name;
    }

    public function getNumberOfSides(): int
    {
        return $this->numberOfSides;
    }

    public function getName(): string
    {
        return $this->name;
    }
}

$triangle = new Shape();
$triangle->setName("triangle");
$triangle->setNumberofSides(3);
var_dump($triangle->getName());
var_dump($triangle->getNumberOfSides());

$circle = new Shape();
$circle->setName("circle");
var_dump($circle->getName());
var_dump($circle->getNumberOfSides());
?>
]]>
     </programlisting>
     &example.outputs;
     <screen>
<![CDATA[
string(8) "triangle"
int(3)
string(6) "circle"

Fatal error: Uncaught Error: Typed property Shape::$numberOfSides must not be accessed before initialization
]]>
     </screen>
    </example>
   </para>
  </sect2>

  <sect2 xml:id="language.oop5.properties.readonly-properties">
   <title>Readonly- (nur lesbare) Eigenschaften</title>
   <para>
    Seit PHP 8.1.0 ist es möglich, eine Eigenschaft mit
    <literal>readonly</literal> zu deklarieren. Dadurch wird verhindert, dass
    die Eigenschaft nach der Initialisierung geändert wird. Vor PHP 8.4.0 ist
    eine <literal>readonly</literal>-Eigenschaft implizit auf privat gesetzt
    und kann nur von derselben Klasse geschrieben werden. Ab PHP 8.4.0 sind
    <literal>readonly</literal>-Eigenschaften implizit
    <link linkend="language.oop5.visibility-members-aviz"><literal>protected(set)</literal></link>,
    können also von Kindklassen aus definiert werden. Dies kann, falls
    gewünscht, explizit überschrieben werden.
    <example>
     <title>Beispiel für Readonly-Eigenschaften</title>
     <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php

class Test {
   public readonly string $prop;

   public function __construct(string $prop) {
       // Korrekte Initialisierung.
       $this->prop = $prop;
   }
}

$test = new Test("foobar");
// Korrekt ausgelesen.
var_dump($test->prop); // string(6) "foobar"

// Unzulässige Neuzuweisung. Es spielt keine Rolle, dass der
// zugewiesene Wert derselbe ist.
$test->prop = "foobar";
// Error: Cannot modify readonly property Test::$prop
?>
]]>
     </programlisting>
    </example>
    <note>
     <para>
      Der Modifikator readonly kann nur auf
      <link linkend="language.oop5.properties.typed-properties">typisierte Eigenschaften</link>
      angewendet werden. Wenn eine Eigenschaft ohne Typbeschränkung readonly
      sein soll, kann der Typ <xref linkend="language.types.mixed"/> verwendet
      werden.
     </para>
    </note>
    <note>
     <para>
      Statische Readonly-Eigenschaften werden nicht unterstützt.
     </para>
    </note>
   </para>
   <para>
    Eine Readonly-Eigenschaft kann nur einmal initialisiert werden, und zwar
    nur aus dem Bereich, in dem sie deklariert wurde. Jede andere Zuweisung
    oder Änderung der Eigenschaft führt zu einer
    <classname>Error</classname>-Exception.
    <example>
     <title>Unzulässige Initialisierung von Readonly-Eigenschaften</title>
     <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
class Test1 {
    public readonly string $prop;
}

$test1 = new Test1;
// Unzulässige Initialisierung außerhalb des privaten Bereichs.
$test1->prop = "foobar";
// Error: Cannot initialize readonly property Test1::$prop from global scope
?>
]]>
     </programlisting>
    </example>
   </para>
   <note>
    <para>
     Die Angabe eines festen Standardwerts für Readonly-Eigenschaften ist
     nicht zulässig, da eine Readonly-Eigenschaft mit einem Standardwert im
     Wesentlichen dasselbe ist wie eine Konstante und daher nicht besonders
     nützlich.
     <informalexample>
      <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php

class Test {
    // Fatal error: Readonly property Test::$prop cannot have default value
    public readonly int $prop = 42;
}
?>
]]>
      </programlisting>
     </informalexample>
    </para>
   </note>
   <note>
    <para>
     Readonly-Eigenschaften können nach der Initialisierung nicht mit
     <function>unset</function> zurückgesetzt werden. Es ist jedoch möglich,
     eine Readonly-Eigenschaft vor der Initialisierung aus dem Bereich, in dem
     sie deklariert wurde, zurückzusetzen.
    </para>
   </note>
   <para>
    Änderungen sind nicht notwendigerweise einfache Zuweisungen; alle
    folgenden führen ebenfalls zu einer <classname>Error</classname>-Exception:
    <informalexample>
     <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php

class Test {
    public function __construct(
        public readonly int $i = 0,
        public readonly array $ary = [],
    ) {}
}

$test = new Test;
$test->i += 1;
$test->i++;
++$test->i;
$test->ary[] = 1;
$test->ary[0][] = 1;
$ref =& $test->i;
$test->i =& $ref;
byRef($test->i);
foreach ($test as &$prop);
?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    Readonly-Eigenschaften schließen jedoch nicht die interne Veränderbarkeit
    aus. Objekte (oder Ressourcen), die in Readonly-Eigenschaften gespeichert
    sind, können intern immer noch verändert werden:
    <informalexample>
     <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php

class Test {
    public function __construct(public readonly object $obj) {}
}

$test = new Test(new stdClass);
// Zulässige interne Änderung.
$test->obj->foo = 1;
// Unzulässige Neuzuweisung.
$test->obj = new stdClass;
?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    Seit PHP 8.3.0 können Eigenschaften, die nur gelesen werden können, beim
    Klonen eines Objekts mit der Methode
    <link linkend="object.clone">__clone()</link> neu initialisiert werden.
    <example>
     <title>Readonly properties and cloning</title>
     <programlisting role="php">
<![CDATA[
<?php
class Test1 {
    public readonly ?string $prop;

    public function __clone() {
        $this->prop = null;
    }

    public function setProp(string $prop): void {
        $this->prop = $prop;
    }
}

$test1 = new Test1;
$test1->setProp('foobar');

$test2 = clone $test1;
var_dump($test2->prop); // NULL
?>
]]>
     </programlisting>
    </example>
   </para>
  </sect2>

  <sect2 xml:id="language.oop5.properties.dynamic-properties">
   <title>Dynamische Eigenschaften</title>
   <para>
    Wenn man versucht, einem &object; eine nicht existierende Eigenschaft
    zuzuweisen, erstellt PHP automatisch eine entsprechende Eigenschaft. Diese
    dynamisch erstellte Eigenschaft steht <emphasis>nur</emphasis> dieser
    Klasseninstanz zur Verfügung.
   </para>

   <warning>
    <simpara>
     Dynamische Eigenschaften sind seit PHP 8.2.0 veraltet. Es wird empfohlen,
     die Eigenschaft stattdessen zu deklarieren. Um mit beliebigen
     Eigenschaftsnamen zu arbeiten, sollte die Klasse die magischen Methoden
     <link linkend="object.get">__get()</link> und
     <link linkend="object.set">__set()</link> implementieren. Als letzte
     Möglichkeit kann die Klasse mit dem Attribut
     <code>#[\AllowDynamicProperties]</code> markiert werden.
    </simpara>
   </warning>
  </sect2>

 </sect1>
<!-- 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
-->