Split type declarations into their dedicated page

Remove obsolete OOP5 TypeHinting page
Document union types

Closes GH-174

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@351365 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
George Peter Banyard 2020-11-12 18:39:19 +00:00
parent 03cde96680
commit a9a6224ca9
10 changed files with 63 additions and 632 deletions

View file

@ -9,7 +9,7 @@
<para>
Scalar
<link linkend="functions.arguments.type-declaration">type declarations</link>
<link linkend="language.types.declarations">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
@ -44,7 +44,7 @@ int(9)
top of the file. This means that the strictness of typing for scalars is
configured on a per-file basis. This directive not only affects the type
declarations of parameters, but also a function's return type (see
<link linkend="functions.returning-values.type-declaration">return type declarations</link>,
<link linkend="language.types.declarations">return type declarations</link>,
built-in PHP functions, and functions from loaded
extensions.
</para>
@ -52,7 +52,7 @@ int(9)
<para>
Full documentation and examples of scalar type declarations can be found in
the
<link linkend="functions.arguments.type-declaration">type declaration</link>
<link linkend="language.types.declarations">type declaration</link>
reference.
</para>
</sect2>
@ -62,12 +62,12 @@ int(9)
<para>
PHP 7 adds support for
<link linkend="functions.returning-values.type-declaration">return type declarations</link>.
<link linkend="language.types.declarations">return type declarations</link>.
Similarly to
<link linkend="functions.arguments.type-declaration">argument type declarations</link>,
<link linkend="language.types.declarations">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>
<link linkend="language.types.declarations">types</link>
are available for return type declarations as are available for argument
type declarations.
</para>
@ -103,7 +103,7 @@ Array
<para>
Full documentation and examples of return type declarations can be found in
the
<link linkend="functions.returning-values.type-declaration">return type declarations</link>.
<link linkend="language.types.declarations">return type declarations</link>.
reference.
</para>
</sect2>

View file

@ -491,6 +491,10 @@ currently not documented; only its argument list is available.
<!ENTITY example.outputs.73 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 7.3:</para>'>
<!ENTITY example.outputs.8 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8:</para>'>
<!ENTITY example.outputs.80 '<para xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 8.0:</para>'>
<!ENTITY example.outputs.32bit '<para xmlns="http://docbook.org/ns/docbook">Output of the above example on 32 bit machines:</para>'>
<!ENTITY example.outputs.64bit '<para xmlns="http://docbook.org/ns/docbook">Output of the above example on 64 bit machines:</para>'>

View file

@ -32,7 +32,7 @@ declare (directive)
<link linkend="control-structures.declare.encoding">encoding</link>
directive) and the <literal>strict_types</literal> directive (See for more
information the
<link linkend="functions.arguments.type-declaration.strict">strict</link>
<link linkend="language.types.declarations.strict">strict</link>
section on the Function arguments page)
</para>

View file

@ -51,6 +51,12 @@
</simpara>
</note>
</para>
<para>
As of PHP 7.1.0, return statements without an argument trigger <constant>E_COMPILE_ERROR</constant>,
unless the return type is <type>void</type>, in which case return statements
with an argument trigger that error.
</para>
</sect1>
<!-- Keep this comment at the end of the file

View file

@ -356,409 +356,6 @@ Making a bowl of acidophilus raspberry.
</note>
</sect2>
<sect2 xml:id="functions.arguments.type-declaration">
<title>Type declarations</title>
<note>
<para>
Type declarations were also known as type hints in previous versions of PHP.
</para>
</note>
<para>
Type declarations allow functions to require that parameters are of a certain type at call time.
If the given value is of the incorrect type,
then a <classname>TypeError</classname> will be thrown.
</para>
<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>
<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></entry>
</row>
<row>
<entry><literal>self</literal></entry>
<entry>
The parameter must be an &instanceof; the same class as the one the
method is defined on. This can only be used on class and instance
methods.
</entry>
<entry></entry>
</row>
<row>
<entry><type>array</type></entry>
<entry>
The parameter must be an <type>array</type>.
</entry>
<entry></entry>
</row>
<row>
<entry><type>callable</type></entry>
<entry>
The parameter must be a valid <type>callable</type>.
</entry>
<entry></entry>
</row>
<row>
<entry><type>bool</type></entry>
<entry>
The parameter must be a <type>bool</type> value.
</entry>
<entry></entry>
</row>
<row>
<entry><type>float</type></entry>
<entry>
The parameter must be a <type>float</type>ing point number.
</entry>
<entry></entry>
</row>
<row>
<entry><type>int</type></entry>
<entry>
The parameter must be an <type>int</type>.
</entry>
<entry></entry>
</row>
<row>
<entry><type>string</type></entry>
<entry>
The parameter must be a <type>string</type>.
</entry>
<entry></entry>
</row>
<row>
<entry><literal>iterable</literal></entry>
<entry>
The parameter must be either an <type>array</type> or an &instanceof; <classname>Traversable</classname>.
</entry>
<entry>PHP 7.1.0</entry>
</row>
<row>
<entry><literal>object</literal></entry>
<entry>
The parameter must be an <type>object</type>.
</entry>
<entry>PHP 7.2.0</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<warning>
<para>
Aliases for the above scalar types are not supported. Instead, they are
treated as class or interface names. For example, using
<literal>boolean</literal> as a parameter or return type will require
an argument or return value that is an &instanceof; the class or
interface <literal>boolean</literal>, rather than of type
<type>bool</type>:
</para>
<para>
<example>
<programlisting role="php">
<![CDATA[
<?php
function test(boolean $param) {}
test(true);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Fatal error: Uncaught TypeError: Argument 1 passed to test() must be an instance of boolean, boolean given, called in - on line 1 and defined in -:1
]]>
</screen>
</example>
</para>
</warning>
</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 {}
class D extends C {}
// This doesn't extend C.
class E {}
function f(C $c) {
echo get_class($c)."\n";
}
f(new C);
f(new D);
f(new E);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
C
D
Fatal error: Uncaught TypeError: Argument 1 passed to f() must be an instance of C, instance of E given, called in - on line 14 and defined in -:8
Stack trace:
#0 -(14): f(Object(E))
#1 {main}
thrown in - on line 8
]]>
</screen>
</example>
<example>
<title>Basic interface type declaration</title>
<programlisting role="php">
<![CDATA[
<?php
interface I { public function f(); }
class C implements I { public function f() {} }
// This doesn't implement I.
class E {}
function f(I $i) {
echo get_class($i)."\n";
}
f(new C);
f(new E);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
C
Fatal error: Uncaught TypeError: Argument 1 passed to f() must implement interface I, instance of E given, called in - on line 13 and defined in -:8
Stack trace:
#0 -(13): f(Object(E))
#1 {main}
thrown in - on line 8
]]>
</screen>
</example>
<example>
<title>Typed pass-by-reference Parameters</title>
<simpara>
Declared types of reference parameters are checked on function entry, but
not when the function returns, so after the function had returned, the
argument's type may have changed.
</simpara>
<programlisting role="php">
<![CDATA[
<?php
function array_baz(array &$param)
{
$param = 1;
}
$var = [];
array_baz($var);
var_dump($var);
array_baz($var);
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
int(1)
Fatal error: Uncaught TypeError: Argument 1 passed to array_baz() must be of the type array, int given, called in %s on line %d
]]>
</screen>
</example>
<example>
<title>Nullable type declaration</title>
<programlisting role="php">
<![CDATA[
<?php
class C {}
function f(C $c = null) {
var_dump($c);
}
f(new C);
f(null);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
object(C)#1 (0) {
}
NULL
]]>
</screen>
</example>
</sect3>
<sect3 xml:id="functions.arguments.type-declaration.strict">
<title>Strict typing</title>
<para>
By default, PHP will coerce values of the wrong type into the expected
scalar type if possible. For example, a function that is given an
<type>int</type> for a parameter that expects a <type>string</type>
will get a variable of type <type>string</type>.
</para>
<para>
It is possible to enable strict mode on a per-file basis. In strict
mode, only a variable of exact type of the type declaration will be
accepted, or a <classname>TypeError</classname> will be thrown. The
only exception to this rule is that an <type>int</type> may be given
to a function expecting a <type>float</type>. Function calls from within
internal functions will not be affected by the <literal>strict_types</literal>
declaration.
</para>
<para>
To enable strict mode, the &declare; statement is used with the
<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.
</para>
</note>
<example>
<title>Strict typing</title>
<programlisting role="php">
<![CDATA[
<?php
declare(strict_types=1);
function sum(int $a, int $b) {
return $a + $b;
}
var_dump(sum(1, 2));
var_dump(sum(1.5, 2.5));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
int(3)
Fatal error: Uncaught TypeError: Argument 1 passed to sum() must be of the type integer, float given, called in - on line 9 and defined in -:4
Stack trace:
#0 -(9): sum(1.5, 2.5)
#1 {main}
thrown in - on line 4
]]>
</screen>
</example>
<example>
<title>Weak typing</title>
<programlisting role="php">
<![CDATA[
<?php
function sum(int $a, int $b) {
return $a + $b;
}
var_dump(sum(1, 2));
// These will be coerced to integers: note the output below!
var_dump(sum(1.5, 2.5));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
int(3)
int(3)
]]>
</screen>
</example>
<example>
<title>Catching <classname>TypeError</classname></title>
<programlisting role="php">
<![CDATA[
<?php
declare(strict_types=1);
function sum(int $a, int $b) {
return $a + $b;
}
try {
var_dump(sum(1, 2));
var_dump(sum(1.5, 2.5));
} catch (TypeError $e) {
echo 'Error: '.$e->getMessage();
}
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
int(3)
Error: Argument 1 passed to sum() must be of the type integer, float given, called in - on line 10
]]>
</screen>
</example>
</sect3>
</sect2>
<sect2 xml:id="functions.variable-arg-list">
<title>Variable-length argument lists</title>
@ -851,7 +448,7 @@ echo add(...$a);
<para>
It is also possible to add a
<link linkend="language.oop5.typehinting">type declaration</link> before the
<link linkend="language.types.declarations">type declaration</link> before the
<literal>...</literal> token. If this is present, then all arguments
captured by <literal>...</literal> must be objects of the hinted class.
@ -957,10 +554,10 @@ echo sum(1, 2, 3, 4);
<sect2>
<title>Use of return</title>
<para>
<example>
<title>Use of <function>return</function></title>
<programlisting role="php">
<para>
<example>
<title>Use of <function>return</function></title>
<programlisting role="php">
<![CDATA[
<?php
function square($num)
@ -970,18 +567,18 @@ function square($num)
echo square(4); // outputs '16'.
?>
]]>
</programlisting>
</example>
</para>
<para>
A function can not return multiple values, but similar results can be
obtained by returning an array.
</para>
<para>
<example>
<title>Returning an array to get multiple values</title>
<programlisting role="php">
</programlisting>
</example>
</para>
<para>
A function can not return multiple values, but similar results can be
obtained by returning an array.
</para>
<para>
<example>
<title>Returning an array to get multiple values</title>
<programlisting role="php">
<![CDATA[
<?php
function small_numbers()
@ -991,18 +588,18 @@ function small_numbers()
list ($zero, $one, $two) = small_numbers();
?>
]]>
</programlisting>
</example>
</para>
<para>
To return a reference from a function, use the reference operator &amp; in
both the function declaration and when assigning the returned value to a
variable:
</para>
<para>
<example>
<title>Returning a reference from a function</title>
<programlisting role="php">
</programlisting>
</example>
</para>
<para>
To return a reference from a function, use the reference operator &amp; in
both the function declaration and when assigning the returned value to a
variable:
</para>
<para>
<example>
<title>Returning a reference from a function</title>
<programlisting role="php">
<![CDATA[
<?php
function &returns_reference()
@ -1013,159 +610,16 @@ function &returns_reference()
$newref =& returns_reference();
?>
]]>
</programlisting>
</example>
</para>
<simpara>
For more information on references, please check out <link
linkend="language.references">References Explained</link>.
</simpara>
</sect2>
<sect2 xml:id="functions.returning-values.type-declaration">
<title>Return type declarations</title>
<para>
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>
<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. If this type conversion is not allowed
(e.g. when returning an &array; from a function with return type &integer;),
a <classname>TypeError</classname> will be thrown.
In strict mode, the returned value must be of the
correct type, otherwise a <classname>TypeError</classname> will be thrown.
</para>
<para>
As of PHP 7.1.0, return statements without an argument trigger <constant>E_COMPILE_ERROR</constant>,
unless the return type is <type>void</type>, in which case return statements
with an argument trigger that error.
</para>
<para>
As of PHP 7.1.0, return values can be marked as nullable by prefixing the
type name with a question mark (<literal>?</literal>). This signifies that
the function returns either the specified type or &null;.
</para>
<note>
<!-- TODO Link to covariance section -->
<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.
</programlisting>
</example>
</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 sum($a, $b): int {
return $a + $b;
}
var_dump(sum(1, 2));
var_dump(sum(1, 2.5));
?>
]]>
</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>
<example>
<title>Nullable return type declaration (as of PHP 7.1.0)</title>
<programlisting role="php">
<![CDATA[
<?php
function get_item(): ?string {
if (isset($_GET['item'])) {
return $_GET['item'];
} else {
return null;
}
}
?>
]]>
</programlisting>
</example>
</sect3>
<simpara>
For more information on references, please check out <link
linkend="language.references">References Explained</link>.
</simpara>
</sect2>
</sect1>
<sect1 xml:id="functions.variable-functions">
<title>Variable functions</title>

View file

@ -8,13 +8,12 @@
<para>
PHP includes a complete object model.
Some of its features are:
<link linkend="language.oop5.visibility">visibility</link>,
<link linkend="language.oop5.abstract">abstract</link> and
<link linkend="language.oop5.final">final</link> classes and methods,
additional <link linkend="language.oop5.magic">magic methods</link>,
<link linkend="language.oop5.interfaces">interfaces</link>,
<link linkend="language.oop5.cloning">cloning</link> and
<link linkend="language.oop5.typehinting">type declaration</link>.
<link linkend="language.oop5.visibility">visibility</link>,
<link linkend="language.oop5.abstract">abstract</link> and
<link linkend="language.oop5.final">final</link> classes and methods,
additional <link linkend="language.oop5.magic">magic methods</link>,
<link linkend="language.oop5.interfaces">interfaces</link>, and
<link linkend="language.oop5.cloning">cloning</link>.
</para>
<para>
PHP treats objects in the same way as references or handles, meaning that
@ -44,7 +43,6 @@
&language.oop5.final;
&language.oop5.cloning;
&language.oop5.object-comparison;
&language.oop5.typehinting;
&language.oop5.late-static-bindings;
&language.oop5.references;
&language.oop5.serialization;

View file

@ -219,7 +219,7 @@ class b implements a
An interface, together with type-hinting, provides a good way to make sure
that a particular object contains particular methods. See
<link linkend="language.operators.type">instanceof</link> operator and
<link linkend="language.oop5.typehinting">type hinting</link>.
<link linkend="language.types.declarations">type declarations</link>.
</para>
</sect2>

View file

@ -1,32 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<sect1 xml:id="language.oop5.typehinting" xmlns="http://docbook.org/ns/docbook">
<title>Type Hinting</title>
<para>
This documentation has moved to the
<link linkend="functions.arguments.type-declaration">function reference</link>.
</para>
</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
-->

View file

@ -196,6 +196,7 @@ if (is_string($a_bool)) {
&language.types.resource;
&language.types.null;
&language.types.callable;
&language.types.declarations;
&language.types.pseudo-types;
&language.types.type-juggling;

View file

@ -57,7 +57,7 @@
to trigger <link linkend="ini.include-path">include path</link>
search.
This is not possible if <link
linkend="functions.arguments.type-declaration.strict">strict typing</link>
linkend="language.types.declarations.strict">strict typing</link>
is enabled, since <constant>FILE_USE_INCLUDE_PATH</constant> is an
<type>int</type>. Use &true; instead.
</para>