mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-18 18:08:54 +00:00
4528db2d91
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@351963 c90b9560-bf6c-de11-be94-00142212c4b1
565 lines
14 KiB
XML
565 lines
14 KiB
XML
<?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>. 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 a reference to the calling
|
|
object (usually the object to which the method belongs, but
|
|
possibly another object, if the method is called
|
|
<link linkend="language.oop5.static">statically</link> from the context
|
|
of a secondary object).
|
|
As of PHP 7.0.0 calling a non-static method statically from an incompatible
|
|
context results in $this being undefined inside the method. Calling a
|
|
non-static method statically from an incompatible context has been
|
|
deprecated as of PHP 5.6.0. As of PHP 7.0.0 calling a non-static method
|
|
statically has been generally deprecated (even if called from a compatible
|
|
context). Before PHP 5.6.0 such calls already triggered a strict notice.
|
|
</para>
|
|
<para>
|
|
<example xml:id="language.oop5.basic.class.this">
|
|
<title>Some examples of the <varname>$this</varname> pseudo-variable</title>
|
|
<simpara>
|
|
We're assuming that error_reporting is disabled for this example;
|
|
otherwise the following code would trigger deprecated and strict notices,
|
|
respectively, depending on the PHP version.
|
|
</simpara>
|
|
<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.5;
|
|
<screen>
|
|
<![CDATA[
|
|
$this is defined (A)
|
|
$this is not defined.
|
|
$this is defined (B)
|
|
$this is not defined.
|
|
]]>
|
|
</screen>
|
|
&example.outputs.7;
|
|
<screen>
|
|
<![CDATA[
|
|
$this is defined (A)
|
|
$this is not defined.
|
|
$this is not defined.
|
|
$this is not defined.
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
</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 <type>string</type> containing 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>
|
|
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>
|
|
PHP 5.3.0 introduced a couple of new ways to create instances of an
|
|
object:
|
|
</para>
|
|
<example>
|
|
<title>Creating new objects</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
class Test
|
|
{
|
|
static public function getNew()
|
|
{
|
|
return new static;
|
|
}
|
|
}
|
|
|
|
class Child extends Test
|
|
{}
|
|
|
|
$obj1 = new Test();
|
|
$obj2 = new $obj1;
|
|
var_dump($obj1 !== $obj2);
|
|
|
|
$obj3 = Test::getNew();
|
|
var_dump($obj3 instanceof Test);
|
|
|
|
$obj4 = Child::getNew();
|
|
var_dump($obj4 instanceof Child);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
bool(true)
|
|
bool(true)
|
|
bool(true)
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
|
|
<para>
|
|
PHP 5.4.0 introduced the possibility 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');
|
|
?>
|
|
]]>
|
|
</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. As of PHP 7.0.0 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();
|
|
|
|
// as of PHP 5.3.0:
|
|
$func = $obj->bar;
|
|
echo $func(), PHP_EOL;
|
|
|
|
// alternatively, as of PHP 7.0.0:
|
|
echo ($obj->bar)(), PHP_EOL;
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
42
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="language.oop5.basic.extends">
|
|
<title>extends</title>
|
|
<para>
|
|
A class can inherit the 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 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
|
|
as <link linkend="language.oop5.final">final</link>, that method
|
|
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>
|
|
<para>
|
|
When overriding methods, the parameter signature should remain the same or
|
|
PHP will generate an <constant>E_STRICT</constant> level error. This does
|
|
not apply to the constructor, which allows overriding with different
|
|
parameters.
|
|
</para>
|
|
<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>
|
|
</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. You can get a string containing the fully qualified name
|
|
of the <literal>ClassName</literal> class by using
|
|
<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, the <literal>::class</literal> constant 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
|
|
-->
|