<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision$ -->

<sect1 xml:id="language.oop5.basic" xmlns="http://docbook.org/ns/docbook">

<title>The Basics</title>

<sect2 xml:id="language.oop5.basic.class">

<title>class</title>

<para>

Basic class definitions begin with the

keyword <literal>class</literal>, followed by a class name,

followed by a pair of curly braces which enclose the definitions

of the properties and methods belonging to the class.

</para>

<para>

The class name can be any valid label, provided it is not a

PHP <link linkend="reserved">reserved word</link>.

As of PHP 8.4.0, using a single underscore <literal>_</literal> as a

class name is deprecated.

A valid class name starts with a letter or underscore,

followed by any number of letters, numbers, or underscores.

As a regular expression, it would be expressed thus:

<code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>.

</para>

<para>

A class may contain its

own <link linkend="language.oop5.constants">constants</link>, <link linkend="language.oop5.properties">variables</link>

(called "properties"), and functions (called "methods").

</para>

<example>

<title>Simple Class definition</title>

<programlisting role="php">

<![CDATA[

<?php

class SimpleClass

{

// property declaration

public $var = 'a default value';

// method declaration

public function displayVar() {

echo $this->var;

}

}

?>

]]>

</programlisting>

</example>

<para>

The pseudo-variable <varname>$this</varname> is available when a

method is called from within an object context.

<varname>$this</varname> is the value of the calling object.

</para>

<warning>

<para>

Calling a non-static method statically throws an

<classname>Error</classname>.

Prior to PHP 8.0.0, this would generate a deprecation notice,

and <varname>$this</varname> would be undefined.

</para>

<example xml:id="language.oop5.basic.class.this">

<title>Some examples of the <varname>$this</varname> pseudo-variable</title>

<programlisting role="php">

<![CDATA[

<?php

class A

{

function foo()

{

if (isset($this)) {

echo '$this is defined (';

echo get_class($this);

echo ")\n";

} else {

echo "\$this is not defined.\n";

}

}

}

class B

{

function bar()

{

A::foo();

}

}

$a = new A();

$a->foo();

A::foo();

$b = new B();

$b->bar();

B::bar();

?>

]]>

</programlisting>

&example.outputs.7;

<screen>

<![CDATA[

$this is defined (A)

Deprecated: Non-static method A::foo() should not be called statically in %s on line 27

$this is not defined.

Deprecated: Non-static method A::foo() should not be called statically in %s on line 20

$this is not defined.

Deprecated: Non-static method B::bar() should not be called statically in %s on line 32

Deprecated: Non-static method A::foo() should not be called statically in %s on line 20

$this is not defined.

]]>

</screen>

&example.outputs.8;

<screen>

<![CDATA[

$this is defined (A)

Fatal error: Uncaught Error: Non-static method A::foo() cannot be called statically in %s :27

Stack trace:

#0 {main}

thrown in %s on line 27

]]>

</screen>

</example>

</warning>

<sect3 xml:id="language.oop5.basic.class.readonly">

<title>Readonly classes</title>

<para>

As of PHP 8.2.0, a class can be marked with the

<modifier>readonly</modifier> modifier.

Marking a class as <modifier>readonly</modifier> will add the

<link linkend="language.oop5.properties.readonly-properties"><modifier>readonly</modifier> modifier</link>

to every declared property, and prevent the creation of

<link linkend="language.oop5.properties.dynamic-properties">dynamic properties</link>.

Moreover, it is impossible to add support for them by using the

<classname>AllowDynamicProperties</classname> attribute. Attempting to do so

will trigger a compile-time error.

</para>

<informalexample>

<programlisting role="php">

<![CDATA[

<?php

#[\AllowDynamicProperties]

readonly class Foo {

}

// Fatal error: Cannot apply #[AllowDynamicProperties] to readonly class Foo

?>

]]>

</programlisting>

</informalexample>

<para>

As neither untyped nor static properties can be marked with the

<literal>readonly</literal> modifier, readonly classes cannot declare

them either:

</para>

<informalexample>

<programlisting role="php">

<![CDATA[

<?php

readonly class Foo

{

public $bar;

}

// Fatal error: Readonly property Foo::$bar must have type

?>

]]>

</programlisting>

<programlisting role="php">

<![CDATA[

<?php

readonly class Foo

{

public static int $bar;

}

// Fatal error: Readonly class Foo cannot declare static properties

?>

]]>

</programlisting>

</informalexample>

<para>

A <modifier>readonly</modifier> class can be

<link linkend="language.oop5.basic.extends">extended</link>

if, and only if, the child class is also a

<modifier>readonly</modifier> class.

</para>

</sect3>

</sect2>

<sect2 xml:id="language.oop5.basic.new">

<title>new</title>

<para>

To create an instance of a class, the <literal>new</literal> keyword must

be used. An object will always be created unless the object has a

<link linkend="language.oop5.decon">constructor</link> defined that throws an

<link linkend="language.exceptions">exception</link> on error. Classes

should be defined before instantiation (and in some cases this is a

requirement).

</para>

<para>

If a variable containing a <type>string</type> with the name of a class is used with

<literal>new</literal>, a new instance of that class will be created. If

the class is in a namespace, its fully qualified name must be used when

doing this.

</para>

<note>

<para>

If there are no arguments to be passed to the class's constructor,

parentheses after the class name may be omitted.

</para>

</note>

<example>

<title>Creating an instance</title>

<programlisting role="php">

<![CDATA[

<?php

class SimpleClass {

}

$instance = new SimpleClass();

var_dump($instance);

// This can also be done with a variable:

$className = 'SimpleClass';

$instance = new $className(); // new SimpleClass()

var_dump($instance);

?>

]]>

</programlisting>

</example>

<para>

As of PHP 8.0.0, using <literal>new</literal> with arbitrary expressions

is supported. This allows more complex instantiation if the expression

produces a <type>string</type>. The expressions must be wrapped in parentheses.

</para>

<example>

<title>Creating an instance using an arbitrary expression</title>

<para>

In the given example we show multiple examples of valid arbitrary expressions that produce a class name.

This shows a call to a function, string concatenation, and the <constant>::class</constant> constant.

</para>

<programlisting role="php">

<![CDATA[

<?php

class ClassA extends \stdClass {}

class ClassB extends \stdClass {}

class ClassC extends ClassB {}

class ClassD extends ClassA {}

function getSomeClass(): string

{

return 'ClassA';

}

var_dump(new (getSomeClass()));

var_dump(new ('Class' . 'B'));

var_dump(new ('Class' . 'C'));

var_dump(new (ClassD::class));

?>

]]>

</programlisting>

&example.outputs.8;

<screen>

<![CDATA[

object(ClassA)#1 (0) {

}

object(ClassB)#1 (0) {

}

object(ClassC)#1 (0) {

}

object(ClassD)#1 (0) {

}

]]>

</screen>

</example>

<para>

In the class context, it is possible to create a new object by

<literal>new self</literal> and <literal>new parent</literal>.

</para>

<para>

When assigning an already created instance of a class to a new variable, the new variable

will access the same instance as the object that was assigned. This

behaviour is the same when passing instances to a function. A copy

of an already created object can be made by

<link linkend="language.oop5.cloning">cloning</link> it.

</para>

<example>

<title>Object Assignment</title>

<programlisting role="php">

<![CDATA[

<?php

class SimpleClass {

public string $var;

}

$instance = new SimpleClass();

$assigned = $instance;

$reference =& $instance;

$instance->var = '$assigned will have this value';

$instance = null; // $instance and $reference become null

var_dump($instance);

var_dump($reference);

var_dump($assigned);

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

NULL

NULL

object(SimpleClass)#1 (1) {

["var"]=>

string(30) "$assigned will have this value"

}

]]>

</screen>

</example>

<para>

It's possible to create instances of an object in a couple of ways:

</para>

<example>

<title>Creating new objects</title>

<programlisting role="php">

<![CDATA[

<?php

class Test

{

public static function getNew()

{

return new static();

}

}

class Child extends Test {}

$obj1 = new Test(); // By the class name

$obj2 = new $obj1(); // Through the variable containing an object

var_dump($obj1 !== $obj2);

$obj3 = Test::getNew(); // By the class method

var_dump($obj3 instanceof Test);

$obj4 = Child::getNew(); // Through a child class method

var_dump($obj4 instanceof Child);

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

bool(true)

bool(true)

bool(true)

]]>

</screen>

</example>

<para>

It is possible to access a member of a newly created object

in a single expression:

</para>

<example>

<title>Access member of newly created object</title>

<programlisting role="php">

<![CDATA[

<?php

echo (new DateTime())->format('Y'), PHP_EOL;

// surrounding parentheses are optional as of PHP 8.4.0

echo new DateTime()->format('Y'), PHP_EOL;

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

2025

2025

]]>

</screen>

</example>

<note>

<simpara>

Prior to PHP 7.1, the arguments are not evaluated if there is no constructor

function defined.

</simpara>

</note>

</sect2>

<sect2 xml:id="language.oop5.basic.properties-methods">

<title>Properties and methods</title>

<para>

Class properties and methods live in separate "namespaces", so it is

possible to have a property and a method with the same name. Referring to

both a property and a method has the same notation, and whether a property

will be accessed or a method will be called, solely depends on the context,

i.e. whether the usage is a variable access or a function call.

</para>

<example>

<title>Property access vs. method call</title>

<programlisting role="php">

<![CDATA[

<?php

class Foo

{

public $bar = 'property';

public function bar() {

return 'method';

}

}

$obj = new Foo();

echo $obj->bar, PHP_EOL, $obj->bar(), PHP_EOL;

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

property

method

]]>

</screen>

</example>

<para>

That means that calling an <link linkend="functions.anonymous">anonymous

function</link> which has been assigned to a property is not directly

possible. Instead the property has to be assigned to a variable first, for

instance. It is possible to call such a property directly

by enclosing it in parentheses.

</para>

<example>

<title>Calling an anonymous function stored in a property</title>

<programlisting role="php">

<![CDATA[

<?php

class Foo

{

public $bar;

public function __construct() {

$this->bar = function() {

return 42;

};

}

}

$obj = new Foo();

echo ($obj->bar)(), PHP_EOL;

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

42

]]>

</screen>

</example>

</sect2>

<sect2 xml:id="language.oop5.basic.extends">

<!-- TODO Example about class constant redefinition -->

<!-- TODO Split into it's own page? -->

<title>extends</title>

<para>

A class can inherit the constants, methods, and properties of another class by

using the keyword <literal>extends</literal> in the class

declaration. It is not possible to extend multiple classes; a

class can only inherit from one base class.

</para>

<para>

The inherited constants, methods, and properties can be overridden by

redeclaring them with the same name defined in the parent

class. However, if the parent class has defined a method or constant

as <link linkend="language.oop5.final">final</link>,

they may not be overridden. It is possible to access the overridden

methods or static properties by referencing them

with <link linkend="language.oop5.paamayim-nekudotayim">parent::</link>.

</para>

<note>

<simpara>

As of PHP 8.1.0, constants may be declared as final.

</simpara>

</note>

<example>

<title>Simple Class Inheritance</title>

<programlisting role="php">

<![CDATA[

<?php

class SimpleClass

{

function displayVar()

{

echo "Parent class\n";

}

}

class ExtendClass extends SimpleClass

{

// Redefine the parent method

function displayVar()

{

echo "Extending class\n";

parent::displayVar();

}

}

$extended = new ExtendClass();

$extended->displayVar();

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Extending class

a default value

]]>

</screen>

</example>

<sect3 xml:id="language.oop.lsp">

<title>Signature compatibility rules</title>

<para>

When overriding a method, its signature must be compatible with the parent

method. Otherwise, a fatal error is emitted, or, prior to PHP 8.0.0, an

<constant>E_WARNING</constant> level error is generated.

A signature is compatible if it respects the

<link linkend="language.oop5.variance">variance</link> rules, makes a

mandatory parameter optional, adds only optional new parameters and

doesn't restrict but only relaxes the visibility.

This is known as the Liskov Substitution Principle, or LSP for short.

The <link linkend="language.oop5.decon.constructor">constructor</link>,

and <literal>private</literal> methods are exempt from these signature

compatibility rules, and thus won't emit a fatal error in case of a

signature mismatch.

</para>

<example>

<title>Compatible child methods</title>

<programlisting role="php">

<![CDATA[

<?php

class Base

{

public function foo(int $a) {

echo "Valid\n";

}

}

class Extend1 extends Base

{

function foo(int $a = 5)

{

parent::foo($a);

}

}

class Extend2 extends Base

{

function foo(int $a, $b = 5)

{

parent::foo($a);

}

}

$extended1 = new Extend1();

$extended1->foo();

$extended2 = new Extend2();

$extended2->foo(1);

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Valid

Valid

]]>

</screen>

</example>

<para>

The following examples demonstrate that a child method which removes a parameter, or makes an optional

parameter mandatory, is not compatible with the parent method.

</para>

<example>

<title>Fatal error when a child method removes a parameter</title>

<programlisting role="php">

<![CDATA[

<?php

class Base

{

public function foo(int $a = 5) {

echo "Valid\n";

}

}

class Extend extends Base

{

function foo()

{

parent::foo(1);

}

}

]]>

</programlisting>

&example.outputs.8.similar;

<screen>

<![CDATA[

Fatal error: Declaration of Extend::foo() must be compatible with Base::foo(int $a = 5) in /in/evtlq on line 13

]]>

</screen>

</example>

<example>

<title>Fatal error when a child method makes an optional parameter mandatory</title>

<programlisting role="php">

<![CDATA[

<?php

class Base

{

public function foo(int $a = 5) {

echo "Valid\n";

}

}

class Extend extends Base

{

function foo(int $a)

{

parent::foo($a);

}

}

]]>

</programlisting>

&example.outputs.8.similar;

<screen>

<![CDATA[

Fatal error: Declaration of Extend::foo(int $a) must be compatible with Base::foo(int $a = 5) in /in/qJXVC on line 13

]]>

</screen>

</example>

<warning>

<para>

Renaming a method's parameter in a child class is not a signature

incompatibility. However, this is discouraged as it will result in a

runtime <classname>Error</classname> if

<link linkend="functions.named-arguments">named arguments</link>

are used.

</para>

<example>

<title>Error when using named arguments and parameters were renamed in a child class</title>

<programlisting role="php">

<![CDATA[

<?php

class A {

public function test($foo, $bar) {}

}

class B extends A {

public function test($a, $b) {}

}

$obj = new B;

// Pass parameters according to A::test() contract

$obj->test(foo: "foo", bar: "bar"); // ERROR!

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

Fatal error: Uncaught Error: Unknown named parameter $foo in /in/XaaeN:14

Stack trace:

#0 {main}

thrown in /in/XaaeN on line 14

]]>

</screen>

</example>

</warning>

</sect3>

</sect2>

<sect2 xml:id="language.oop5.basic.class.class">

<title>::class</title>

<para>

The <literal>class</literal> keyword is also used for class

name resolution.

To obtain the fully qualified name of a class <literal>ClassName</literal>

use <literal>ClassName::class</literal>. This is particularly useful with

<link linkend="language.namespaces">namespaced</link> classes.

</para>

<para>

<example xml:id="language.oop5.basic.class.class.name">

<title>Class name resolution</title>

<programlisting role="php">

<![CDATA[

<?php

namespace NS {

class ClassName {

}

echo ClassName::class;

}

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

NS\ClassName

]]>

</screen>

</example>

</para>

<note>

<para>The class name resolution using <literal>::class</literal> is a

compile time transformation. That means at the time the class name string

is created no autoloading has happened yet. As a consequence, class names

are expanded even if the class does not exist. No error is issued in

that case.

</para>

<example xml:id="language.oop5.basic.class.class.fail">

<title>Missing class name resolution</title>

<programlisting role="php">

<![CDATA[

<?php

print Does\Not\Exist::class;

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Does\Not\Exist

]]>

</screen>

</example>

</note>

<para>

As of PHP 8.0.0, <literal>::class</literal> may also be used on

objects. This resolution happens at runtime, not compile time. Its effect is

the same as calling <function>get_class</function> on the object.

</para>

<example xml:id="language.oop5.basic.class.class.object">

<title>Object name resolution</title>

<programlisting role="php">

<![CDATA[

<?php

namespace NS {

class ClassName {

}

$c = new ClassName();

print $c::class;

}

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

NS\ClassName

]]>

</screen>

</example>

</sect2>

<sect2 xml:id="language.oop5.basic.nullsafe">

<title>Nullsafe methods and properties</title>

<para>

As of PHP 8.0.0, properties and methods may also be accessed with the

"nullsafe" operator instead: <literal>?-></literal>. The nullsafe operator

works the same as property or method access as above, except that if the

object being dereferenced is &null; then &null;

will be returned rather than an exception thrown. If the dereference is part of a

chain, the rest of the chain is skipped.

</para>

<para>

The effect is similar to wrapping each access in an <function>is_null</function>

check first, but more compact.

</para>

<para>

<example>

<title>Nullsafe Operator</title>

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

<![CDATA[

<?php

// As of PHP 8.0.0, this line:

$result = $repository?->getUser(5)?->name;

// Is equivalent to the following code block:

if (is_null($repository)) {

$result = null;

} else {

$user = $repository->getUser(5);

if (is_null($user)) {

$result = null;

} else {

$result = $user->name;

}

}

?>

]]>

</programlisting>

</example>

</para>

<note>

<para>

The nullsafe operator is best used when null is considered a valid and expected

possible value for a property or method return. For indicating an error,

a thrown exception is preferable.

</para>

</note>

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

-->