<?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
$instance = new SimpleClass();

// This can also be done with a variable:
$className = 'SimpleClass';
$instance = new $className(); // new SimpleClass()
?>
]]>
    </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

$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');
// surrounding parentheses are optional as of PHP 8.4.0
echo new DateTime()->format('Y');
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
2016
]]>
    </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 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">
<![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
-->