mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00
Improve type declaration docs.
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@337367 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Adam Harvey
parent
4df160596c
commit
01851927f9
2 changed files with 219 additions and 256 deletions
|
|
@ -9,7 +9,7 @@
|
|||
|
||||
<para>
|
||||
Scalar
|
||||
<link linkend="functions.arguments.type-declarations">type declarations</link>
|
||||
<link linkend="functions.arguments.type-declaration">type declarations</link>
|
||||
come in two flavours: coercive (default) and strict. The following types
|
||||
for parameters can now be enforced (either coercively or strictly): strings
|
||||
(<type>string</type>), integers (<literal>int</literal>), floating-point
|
||||
|
|
@ -51,7 +51,7 @@ int(9)
|
|||
<para>
|
||||
Full documentation and examples of scalar type declarations can be found in
|
||||
the
|
||||
<link linkend="functions.arguments.type-declarations">type declaration</link>
|
||||
<link linkend="functions.arguments.type-declaration">type declaration</link>
|
||||
reference.
|
||||
</para>
|
||||
</sect2>
|
||||
|
|
|
|||
|
|
@ -373,83 +373,84 @@ Making a bowl of acidophilus raspberry.
|
|||
exception.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Valid types include:
|
||||
</para>
|
||||
|
||||
<informaltable>
|
||||
<tgroup cols="3">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Type</entry>
|
||||
<entry>Description</entry>
|
||||
<entry>Minimum PHP version</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>Class/interface name</entry>
|
||||
<entry>
|
||||
The parameter must be an &instanceof; the given class or interface
|
||||
name.
|
||||
</entry>
|
||||
<entry>PHP 5.0.0</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><type>array</type></entry>
|
||||
<entry>
|
||||
The parameter must be an <type>array</type>.
|
||||
</entry>
|
||||
<entry>PHP 5.1.0</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><type>callable</type></entry>
|
||||
<entry>
|
||||
The parameter must be a valid <type>callable</type>.
|
||||
</entry>
|
||||
<entry>PHP 5.4.0</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><type>bool</type></entry>
|
||||
<entry>
|
||||
The parameter must be a <type>boolean</type> value.
|
||||
</entry>
|
||||
<entry>PHP 7.0.0</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><type>float</type></entry>
|
||||
<entry>
|
||||
The parameter must be a <type>float</type>ing point number.
|
||||
</entry>
|
||||
<entry>PHP 7.0.0</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><type>int</type></entry>
|
||||
<entry>
|
||||
The parameter must be an <type>integer</type>.
|
||||
</entry>
|
||||
<entry>PHP 7.0.0</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><type>string</type></entry>
|
||||
<entry>
|
||||
The parameter must be a <type>string</type>.
|
||||
</entry>
|
||||
<entry>PHP 7.0.0</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
||||
<para>
|
||||
To specify a type declaration, the type name should be added before the
|
||||
parameter name. The declaration can be made to accept &null; values if
|
||||
the default value of the parameter is set to &null;.
|
||||
</para>
|
||||
|
||||
<example>
|
||||
<title>Basic class type declaration</title>
|
||||
<programlisting role="php">
|
||||
<sect3 xml:id="functions.arguments.type-declaration.types">
|
||||
<title>Valid types</title>
|
||||
<informaltable>
|
||||
<tgroup cols="3">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Type</entry>
|
||||
<entry>Description</entry>
|
||||
<entry>Minimum PHP version</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>Class/interface name</entry>
|
||||
<entry>
|
||||
The parameter must be an &instanceof; the given class or interface
|
||||
name.
|
||||
</entry>
|
||||
<entry>PHP 5.0.0</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><type>array</type></entry>
|
||||
<entry>
|
||||
The parameter must be an <type>array</type>.
|
||||
</entry>
|
||||
<entry>PHP 5.1.0</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><type>callable</type></entry>
|
||||
<entry>
|
||||
The parameter must be a valid <type>callable</type>.
|
||||
</entry>
|
||||
<entry>PHP 5.4.0</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><type>bool</type></entry>
|
||||
<entry>
|
||||
The parameter must be a <type>boolean</type> value.
|
||||
</entry>
|
||||
<entry>PHP 7.0.0</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><type>float</type></entry>
|
||||
<entry>
|
||||
The parameter must be a <type>float</type>ing point number.
|
||||
</entry>
|
||||
<entry>PHP 7.0.0</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><type>int</type></entry>
|
||||
<entry>
|
||||
The parameter must be an <type>integer</type>.
|
||||
</entry>
|
||||
<entry>PHP 7.0.0</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><type>string</type></entry>
|
||||
<entry>
|
||||
The parameter must be a <type>string</type>.
|
||||
</entry>
|
||||
<entry>PHP 7.0.0</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
</sect3>
|
||||
|
||||
<sect3 xml:id="functions.arguments.type-declaration.examples">
|
||||
&reftitle.examples;
|
||||
<example>
|
||||
<title>Basic class type declaration</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
class C {}
|
||||
|
|
@ -467,9 +468,9 @@ f(new D);
|
|||
f(new E);
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
C
|
||||
D
|
||||
|
|
@ -480,12 +481,12 @@ Stack trace:
|
|||
#1 {main}
|
||||
thrown in - on line 8
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</screen>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Basic interface type declaration</title>
|
||||
<programlisting role="php">
|
||||
<example>
|
||||
<title>Basic interface type declaration</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
interface I { public function f(); }
|
||||
|
|
@ -502,9 +503,9 @@ f(new C);
|
|||
f(new E);
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
C
|
||||
|
||||
|
|
@ -514,12 +515,12 @@ Stack trace:
|
|||
#1 {main}
|
||||
thrown in - on line 8
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</screen>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Nullable type declaration</title>
|
||||
<programlisting role="php">
|
||||
<example>
|
||||
<title>Nullable type declaration</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
class C {}
|
||||
|
|
@ -532,16 +533,17 @@ f(new C);
|
|||
f(null);
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
object(C)#1 (0) {
|
||||
}
|
||||
NULL
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</screen>
|
||||
</example>
|
||||
</sect3>
|
||||
|
||||
<sect3 xml:id="functions.arguments.type-declaration.strict">
|
||||
<title>Strict typing</title>
|
||||
|
|
@ -566,6 +568,32 @@ NULL
|
|||
<literal>strict_types</literal> declaration:
|
||||
</para>
|
||||
|
||||
<caution>
|
||||
<para>
|
||||
Enabling strict mode will also affect
|
||||
<link linkend="functions.returning-values.type-declaration">return type declarations</link>.
|
||||
</para>
|
||||
</caution>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
Strict typing applies to function calls made from
|
||||
<emphasis>within</emphasis> the file with strict typing enabled, not to
|
||||
the functions declared within that file. If a file without strict
|
||||
typing enabled makes a call to a function that was defined in a file
|
||||
with strict typing, the caller's preference (weak typing) will be
|
||||
respected, and the value will be coerced.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
Strict typing is only defined for scalar type declarations, and as
|
||||
such, requires PHP 7.0.0 or later, as scalar type declarations were
|
||||
added in that version.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<example>
|
||||
<title>Strict typing</title>
|
||||
<programlisting role="php">
|
||||
|
|
@ -649,25 +677,6 @@ Error: Argument 1 passed to sum() must be of the type integer, float given, call
|
|||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
Strict typing applies to function calls made from
|
||||
<emphasis>within</emphasis> the file with strict typing enabled, not to
|
||||
the functions declared within that file. If a file without strict
|
||||
typing enabled makes a call to a function that was defined in a file
|
||||
with strict typing, the caller's preference (weak typing) will be
|
||||
respected, and the value will be coerced.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
Strict typing is only defined for scalar type declarations, and as
|
||||
such, requires PHP 7.0.0 or later, as scalar type declarations were
|
||||
added in that version.
|
||||
</para>
|
||||
</note>
|
||||
</sect3>
|
||||
</sect2>
|
||||
<sect2 xml:id="functions.variable-arg-list">
|
||||
|
|
@ -855,30 +864,14 @@ echo sum(1, 2, 3, 4);
|
|||
the line from which it was called. See <function>return</function>
|
||||
for more information.
|
||||
</para>
|
||||
<para>
|
||||
<informaltable>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>&Version;</entry>
|
||||
<entry>&Description;</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>7.0.0</entry>
|
||||
<entry>Added Return Type Declarations</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
If the <function>return</function> is omitted the value &null; will be
|
||||
returned.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<sect2>
|
||||
<title>Use of return</title>
|
||||
<para>
|
||||
|
|
@ -945,145 +938,115 @@ $newref =& returns_reference();
|
|||
linkend="language.references">References Explained</link>.
|
||||
</simpara>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>Return Type Declarations</title>
|
||||
<para>
|
||||
PHP 7 Introduces Return type declaration where function can be forced to return
|
||||
type that is defined. This is done by setting
|
||||
<link linkend="control-structures.declare">declare(strict_types=1)</link>, if declare strict_type directive
|
||||
is set to 0 or not set functions are weakly type checked. The directive will have affect on all functions
|
||||
delcared in the file and not functions either included by this file or files that includes this file, are
|
||||
affected. The place where the function is called from is irrelavent.
|
||||
Declarable types are Classes, Interfaces, Array, Int, Float, String and Bool.
|
||||
</para>
|
||||
<para>
|
||||
<example>
|
||||
<title>Affect of strict_types directive </title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
declare(strict_types=1); // file1.php
|
||||
|
||||
// file 1 - strictly type checked
|
||||
// file 2 - weakly type checked
|
||||
<sect2 xml:id="functions.returning-values.type-declaration">
|
||||
<title>Return type declarations</title>
|
||||
|
||||
include "file2.php";
|
||||
<para>
|
||||
PHP 7 adds support for return type declarations. Similarly to
|
||||
<link linkend="functions.arguments.type-declaration">argument type declarations</link>,
|
||||
return type declarations specify the type of the value that will be
|
||||
returned from a function. The same
|
||||
<link linkend="functions.arguments.type-declaration.types">types</link>
|
||||
are available for return type declarations as are available for argument
|
||||
type declarations.
|
||||
</para>
|
||||
|
||||
var_dump(a()); // works correctly
|
||||
var_dump(b()); // fatal TypeError
|
||||
<para>
|
||||
<link linkend="functions.arguments.type-declaration.strict">Strict typing</link>
|
||||
also has an effect on return type declarations. In the default weak mode,
|
||||
returned values will be coerced to the correct type if they are not
|
||||
already of that type. In strong mode, the returned value must be of the
|
||||
correct type, otherwise a <classname>TypeError</classname> will be thrown.
|
||||
</para>
|
||||
|
||||
|
||||
function b() : int{
|
||||
return "1";
|
||||
}
|
||||
?>
|
||||
|
||||
|
||||
<?php
|
||||
// file2.php
|
||||
function a(): int{
|
||||
return "1";
|
||||
}
|
||||
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
<example>
|
||||
<title>More Return types</title>
|
||||
<para>
|
||||
The function signature must match of the parent, if the parent has not been declared the
|
||||
return type the child can declare a type.
|
||||
</para>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
declare(strict_types=1);
|
||||
|
||||
interface Numbers{
|
||||
abstract public function one() : int ;
|
||||
abstract public function two(); // no return type defined
|
||||
}
|
||||
|
||||
class NumClass implements Numbers
|
||||
{
|
||||
public function one() : int { // return type same as abstract
|
||||
return 0;
|
||||
}
|
||||
|
||||
public function two() { // return type defined due lack of return type
|
||||
return 2; // in parent abstract function
|
||||
}
|
||||
}
|
||||
|
||||
class display extends NumClass
|
||||
{
|
||||
public function one() : int // return type same as parent
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
|
||||
public function two() : int // return type same as parent
|
||||
{
|
||||
return 2;
|
||||
}
|
||||
}
|
||||
|
||||
$dis = new display();
|
||||
var_dump($dis->one());
|
||||
var_dump($dis->two());
|
||||
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
<example>
|
||||
<title>Return a class</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
declare(strict_types=1);
|
||||
|
||||
interface A {
|
||||
static function make();
|
||||
}
|
||||
class B implements A {
|
||||
static function make(): B { //valid
|
||||
return new B();
|
||||
}
|
||||
}
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
<note>
|
||||
<para>
|
||||
<example>
|
||||
<title>TypeError</title>
|
||||
<para>Incorrect return type will result in a TypeError</para>
|
||||
When overriding a parent method, the child's method must match any return
|
||||
type declaration on the parent. If the parent doesn't define a return
|
||||
type, then the child method may do so.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<sect3 xml:id="functions.returning-values.type-declaration.examples">
|
||||
&reftitle.examples;
|
||||
|
||||
<example>
|
||||
<title>Basic return type declaration</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
function sum($a, $b): float {
|
||||
return $a + $b;
|
||||
}
|
||||
|
||||
// Note that a float will be returned.
|
||||
var_dump(sum(1, 2));
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
float(3)
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Strict mode in action</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
declare(strict_types=1);
|
||||
|
||||
function show(): int{
|
||||
return "1";
|
||||
function sum($a, $b): int {
|
||||
return $a + $b;
|
||||
}
|
||||
|
||||
try {
|
||||
show();
|
||||
} catch (TypeError $e) {
|
||||
var_dump($e->getMessage()); // string(121) "Return value of show() must be of the type integer,
|
||||
// string returned in %s on line 5"
|
||||
}
|
||||
var_dump(sum(1, 2));
|
||||
var_dump(sum(1, 2.5));
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
int(3)
|
||||
|
||||
Fatal error: Uncaught TypeError: Return value of sum() must be of the type integer, float returned in - on line 5 in -:5
|
||||
Stack trace:
|
||||
#0 -(9): sum(1, 2.5)
|
||||
#1 {main}
|
||||
thrown in - on line 5
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Returning an object</title>
|
||||
<programlisting role="php">
|
||||
<![CDATA[
|
||||
<?php
|
||||
class C {}
|
||||
|
||||
function getC(): C {
|
||||
return new C;
|
||||
}
|
||||
|
||||
var_dump(getC());
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
&example.outputs;
|
||||
<screen>
|
||||
<![CDATA[
|
||||
object(C)#1 (0) {
|
||||
}
|
||||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</sect3>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue