<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
 <sect1 xml:id="language.oop5.properties" xmlns="http://docbook.org/ns/docbook">
  <title>Properties</title>

  <para>
   Class member variables are called <emphasis>properties</emphasis>.
   They may be referred to using other terms such as <emphasis>fields</emphasis>,
   but for the purposes of this reference <emphasis>properties</emphasis>
   will be used. They are defined by using at least one modifier (such as
   <xref linkend="language.oop5.visibility"/>,
   <xref linkend="language.oop5.static"/>,
   or, as of PHP 8.1.0, <link linkend="language.oop5.properties.readonly-properties">readonly</link>),
   optionally (except for <code>readonly</code> properties), as of PHP 7.4,
   followed by a type declaration, followed by a normal variable declaration.
   This declaration may include an initialization, but this initialization
   must be a <link linkend="language.constants">constant</link> value.
  </para>
  <note>
   <para>
    An obsolete way of declaring class properties, is by using the
    <literal>var</literal> keyword instead of a modifier.
   </para>
  </note>
  <note>
   <simpara>
    A property declared without a <xref linkend="language.oop5.visibility"/>
    modifier will be declared as <literal>public</literal>.
   </simpara>
  </note>
  <para>
   Within class methods non-static properties may be accessed by using 
   <literal>-&gt;</literal> (Object Operator): <varname>$this-&gt;property</varname> 
   (where <literal>property</literal> is the name of the property). 
   Static properties are accessed by using the <literal>::</literal> (Double Colon):
   <varname>self::$property</varname>. See <xref linkend="language.oop5.static" />
   for more information on the difference between static and non-static properties.
  </para>
  <para>
   The pseudo-variable <varname>$this</varname> is available inside
   any class method when that method is called from within an object context.
   <varname>$this</varname> is the value of the calling object.
  </para>

  <para>
   <example>
    <title>Property declarations</title>
    <programlisting role="php">
<![CDATA[
<?php
class SimpleClass
{
   public $var1 = 'hello ' . 'world';
   public $var2 = <<<EOD
hello world
EOD;
   public $var3 = 1+2;
   // invalid property declarations:
   public $var4 = self::myStaticMethod();
   public $var5 = $myVar;

   // valid property declarations:
   public $var6 = myConstant;
   public $var7 = [true, false];

   public $var8 = <<<'EOD'
hello world
EOD;

   // Without visibility modifier:
   static $var9;
   readonly int $var10;
}
?>
]]>
    </programlisting>   
   </example>
  </para>

  <note>
   <para>
    There are various functions to handle classes and objects.
    See the <link linkend="ref.classobj">Class/Object Functions</link>
    reference.
   </para>
  </note>

  <sect2 xml:id="language.oop5.properties.typed-properties">
   <title>Type declarations</title>
   <para>
    As of PHP 7.4.0, property definitions can include
    <xref linkend="language.types.declarations" />,
    with the exception of <type>callable</type>.
    <example>
     <title>Example of typed properties</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>
    Typed properties must be initialized before accessing, otherwise an
    <classname>Error</classname> is thrown.
    <example>
     <title>Accessing properties</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 properties</title>
   <para>
    As of PHP 8.1.0, a property can be declared with the <literal>readonly</literal> modifier,
    which prevents modification of the property after initialization.  Prior to PHP 8.4.0
    a <literal>readonly</literal> property is implicitly private-set, and may only be written to
    from the same class.  As of PHP 8.4.0, <literal>readonly</literal> properties are implicitly
    <link linkend="language.oop5.visibility-members-aviz"><literal>protected(set)</literal></link>,
    so may be set from child classes.  That may be overridden
    explicitly if desired.
    <example>
     <title>Example of readonly properties</title>
     <programlisting role="php">
<![CDATA[
<?php

class Test {
   public readonly string $prop;

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

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

// Illegal reassignment. It does not matter that the assigned value is the same.
$test->prop = "foobar";
// Error: Cannot modify readonly property Test::$prop
?>
]]>
     </programlisting>
    </example>
    <note>
     <para>
      The readonly modifier can only be applied to <link linkend="language.oop5.properties.typed-properties">typed properties</link>.
      A readonly property without type constraints can be created using the <xref linkend="language.types.mixed"/> type.
     </para>
    </note>
    <note>
     <para>
      Readonly static properties are not supported.
     </para>
    </note>
   </para>
   <para>
    A readonly property can only be initialized once, and only from the scope where it has been declared. Any other assignment or modification of the property will result in an <classname>Error</classname> exception.
    <example>
     <title>Illegal initialization of readonly properties</title>
     <programlisting role="php">
<![CDATA[
<?php
class Test1 {
    public readonly string $prop;
}

$test1 = new Test1;
// Illegal initialization outside of private scope.
$test1->prop = "foobar";
// Error: Cannot initialize readonly property Test1::$prop from global scope
?>
]]>
     </programlisting>
    </example>
   </para>
   <note>
    <para>
     Specifying an explicit default value on readonly properties is not allowed, because a readonly property with a default value is essentially the same as a constant, and thus not particularly useful.
     <informalexample>
      <programlisting role="php">
<![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 properties cannot be <function>unset</function> once they are initialized. However, it is possible to unset a readonly property prior to initialization, from the scope where the property has been declared.
    </para>
   </note>
   <para>
    Modifications are not necessarily plain assignments, all of the following will also result in an <classname>Error</classname> exception:
    <informalexample>
     <programlisting role="php">
<![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>
    However, readonly properties do not preclude interior mutability. Objects (or resources) stored in readonly properties may still be modified internally:
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php

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

$test = new Test(new stdClass);
// Legal interior mutation.
$test->obj->foo = 1;
// Illegal reassignment.
$test->obj = new stdClass;
?>
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    As of PHP 8.3.0, readonly properties can be reinitialized when cloning an object
    using the <link linkend="object.clone">__clone()</link> method.
    <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>Dynamic properties</title>
   <para>
    If trying to assign to a non-existent property on an &object;,
    PHP will automatically create a corresponding property.
    This dynamically created property will <emphasis>only</emphasis> be
    available on this class instance.
   </para>

   <warning>
    <simpara>
     Dynamic properties are deprecated as of PHP 8.2.0.
     It is recommended to declare the property instead.
     To handle arbitrary property names, the class should implement the magic
     methods <link linkend="object.get">__get()</link> and
     <link linkend="object.set">__set()</link>.
     At last resort the class can be marked with the
     <code>#[\AllowDynamicProperties]</code> attribute.
    </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
-->