<?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" annotations="non-interactive">

<![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" annotations="non-interactive">

<![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" annotations="non-interactive">

<![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" 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 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" 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>

However, readonly properties do not preclude interior mutability. Objects (or resources) stored in readonly properties may still be modified internally:

<informalexample>

<programlisting role="php" annotations="non-interactive">

<![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

-->