Contributions are ready for review

From:	phpdoc at lists dot php dot net	Date:	Mon, 17 Aug 2015 12:00:04 +0000
Subject:	Contributions are ready for review
Groups:	php.doc
Request:	Send a blank email to phpdoc+get-969385850@lists.php.net to get a copy of this message

Hello PHP EN Documentation team, There are contributions within the online editor queue for this language. Please review, then commit or delete these patches. Patches for review : ----------------------- Modified: en/internals2/opcodes/cast.xml By: Gennady Kovshenin on 2015-03-15 18:46:59 =================================================================== --- en/internals2/opcodes/cast.xml +++ en/internals2/opcodes/cast.xml @@ -8,7 +8,7 @@ <![CDATA[ <?php /* - * casts value1 as type value2 (?? Not certain about arguments ??) + * casts value1 as type value2 (type in extended_value) * opcode number: 21 */ echo (int)1; @@ -39,7 +39,7 @@ <row> <entry></entry><entry>1</entry> <entry>ECHO</entry><entry></entry> - <entry></entry><entry></entry> + <entry></entry><entry>1</entry> <entry>~0</entry> </row> <row> => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=60577 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=60577 ------------------------------------------------------------------ Modified: en/language/predefined/closure/call.xml By: mail@akirakoyasu.net on 2015-06-23 07:03:03 =================================================================== --- en/language/predefined/closure/call.xml +++ en/language/predefined/closure/call.xml @@ -1,41 +1,38 @@ <?xml version="1.0" encoding="utf-8"?> - + <refentry xml:id="closure.call" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <refnamediv> <refname>Closure::call</refname> - <refpurpose>Binds and calls the closure</refpurpose> + <refpurpose>Calls the closure with the given parameters and returns the result, with $this bound to the given object $to</refpurpose> </refnamediv> <refsect1 role="description"> &reftitle.description; <methodsynopsis> - <modifier>public</modifier> <type>mixed</type><methodname>Closure::call</methodname> - <methodparam><type>object</type><parameter>newthis</parameter></methodparam> + <modifier>public</modifier> <type>Closure</type><methodname>Closure::call</methodname> + <methodparam><type>object</type><parameter>to</parameter></methodparam> + <methodparam choice="opt"><type>mixed</type><parameter>parameter</parameter></methodparam> <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam> </methodsynopsis> <para> - Temporarily binds the closure to <parameter>newthis</parameter>, and calls - it with any given parameters. + Calls the closure with the given parameters and returns the result, with $this bound to the given object + <parameter>to</parameter> </para> </refsect1> <refsect1 role="parameters"> &reftitle.parameters; <variablelist> <varlistentry> - <term><parameter>newthis</parameter></term> + <term><parameter>to</parameter></term> <listitem> <para> - The <type>object</type> to bind the closure to for the duration of the - call. </para> </listitem> </varlistentry> <varlistentry> - <term><parameter>...</parameter></term> + <term><parameter>args</parameter></term> <listitem> <para> - Zero or more parameters, which will be given as parameters to the - closure. </para> </listitem> </varlistentry> @@ -44,9 +41,29 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - Returns the return value of the closure. </para> </refsect1> + <refsect1 role="changelog"> + &reftitle.changelog; + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>7.0.0</entry> + <entry> + Added Closure::call + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </refsect1> <refsect1 role="examples"> &reftitle.examples; <example> @@ -54,34 +71,12 @@ <programlisting role="php"> <![CDATA[ <?php -class Value { - protected $value; - - public function __construct($value) { - $this->value = $value; - } - - public function getValue() { - return $this->value; - } -} - -$three = new Value(3); -$four = new Value(4); - -$closure = function ($delta) { var_dump($this->getValue() + $delta); }; -$closure->call($three, 4); -$closure->call($four, 4); -?> +$foo = new StdClass; +$foo->bar = 3; +$foobar = function ($qux) { var_dump($this->bar + $qux); }; +$foobar->call($foo, 4); // prints int(7) ]]> </programlisting> - &example.outputs; - <screen> -<![CDATA[ -int(7) -int(8) -]]> - </screen> </example> </refsect1> </refentry> => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=63267 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=63267 ------------------------------------------------------------------ Modified: en/language/functions.xml By: anonymous on 2015-07-24 17:30:58 =================================================================== --- en/language/functions.xml +++ en/language/functions.xml @@ -1,18 +1,18 @@ <?xml version="1.0" encoding="utf-8"?> - - <chapter xml:id="language.functions" xmlns="http://docbook.org/ns/docbook"> - <title>Functions</title> - - <sect1 xml:id="functions.user-defined"> - <title>User-defined functions</title> + +<chapter xml:id="language.functions" xmlns="http://docbook.org/ns/docbook"> + <title>Functions</title> - <para> - A function may be defined using syntax such as the following: - </para> - <para> - <example> - <title>Pseudo code to demonstrate function uses</title> - <programlisting role="php"> + <sect1 xml:id="functions.user-defined"> + <title>User-defined functions</title> + + <para> + A function may be defined using syntax such as the following: + </para> + <para> + <example> + <title>Pseudo code to demonstrate function uses</title> + <programlisting role="php"> <![CDATA[ <?php function foo($arg_1, $arg_2, /* ..., */ $arg_n) @@ -22,37 +22,37 @@ } ?> ]]> - </programlisting> - </example> - </para> - - <simpara> - Any valid PHP code may appear inside a function, even other - functions and <link linkend="keyword.class">class</link> - definitions. - </simpara> - <para> - Function names follow the same rules as other labels in PHP. A - valid function 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: - <literal>[a-zA-Z_x7f-xff][a-zA-Z0-9_x7f-xff]*</literal>. - </para> - &tip.userlandnaming; - <simpara> - Functions need not be defined before they are referenced, - <emphasis>except</emphasis> when a function is conditionally defined as - shown in the two examples below. - </simpara> - <para> - When a function is defined in a conditional manner such as the two - examples shown. Its definition must be processed <emphasis>prior</emphasis> - to being called. - </para> - <para> - <example> - <title>Conditional functions</title> - <programlisting role="php"> + </programlisting> + </example> + </para> + + <simpara> + Any valid PHP code may appear inside a function, even other + functions and <link linkend="keyword.class">class</link> + definitions. + </simpara> + <para> + Function names follow the same rules as other labels in PHP. A + valid function 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: + <literal>[a-zA-Z_x7f-xff][a-zA-Z0-9_x7f-xff]*</literal>. + </para> + &tip.userlandnaming; + <simpara> + Functions need not be defined before they are referenced, + <emphasis>except</emphasis> when a function is conditionally defined as + shown in the two examples below. + </simpara> + <para> + When a function is defined in a conditional manner such as the two + examples shown. Its definition must be processed <emphasis>prior</emphasis> + to being called. + </para> + <para> + <example> + <title>Conditional functions</title> + <programlisting role="php"> <![CDATA[ <?php @@ -158,26 +158,54 @@ ]]> </programlisting> </example> - <note> - <simpara> - Recursive function/method calls with over 100-200 recursion levels can - smash the stack and cause a termination of the current script. Especially, - infinite recursion is considered a programming error. - </simpara> - </note> + <note> + <simpara> + Recursive function/method calls with over 100-200 recursion levels can + smash the stack and cause a termination of the current script. Especially, + infinite recursion is considered a programming error. + </simpara> + </note> </para> - + </sect1> - + <sect1 xml:id="functions.arguments"> <title>Function arguments</title> - + <simpara> Information may be passed to functions via the argument list, which is a comma-delimited list of expressions. The arguments are evaluated from left to right. </simpara> - + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>5.1.0</entry> + <entry>classes,interfaces and arrays type declaration</entry> + </row> + <row> + <entry>5.4.0</entry> + <entry><type>callable</type> type declaration</entry> + </row> + <row> + <entry>7.0.0</entry> + <entry>scalar (<type>int</type>, + <type>float</type>, + <type>string</type>, + <type>bool</type>) type declaration</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> <para> PHP supports passing arguments by value (the default), <link linkend="functions.arguments.by-reference">passing by @@ -202,8 +230,8 @@ </example> </para> <sect2 xml:id="functions.arguments.by-reference"> - <title>Passing arguments by reference</title> - + <title>Making arguments be passed by reference</title> + <simpara> By default, function arguments are passed by value (so that if the value of the argument within the function is changed, it does @@ -235,7 +263,7 @@ </sect2> <sect2 xml:id="functions.arguments.default"> <title>Default argument values</title> - + <para> A function may define C++-style default values for scalar arguments as follows: @@ -287,7 +315,7 @@ ]]> </programlisting> </example> - + </para> <simpara> The default value must be a constant expression, not (for @@ -355,333 +383,192 @@ </simpara> </note> </sect2> - - <sect2 xml:id="functions.arguments.type-declaration"> - <title>Type declarations</title> - - <note> - <para> - Type declarations were also known as type hints in PHP 5. - </para> - </note> - + <sect2 xml:id="functions.scalar-type-declaration"> + <title>Scalar Type Hints</title> <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 an error is generated: in PHP 5, this will be a recoverable fatal - error, while PHP 7 will throw a <classname>TypeError</classname> - exception. + Starting with PHP 7, a function can specify a scalar type name as a type hint + in addition to class names, interface names, <type>array</type>, and + <type>callable</type>. The supported scalar type hints are <type>string</type>, + <type>int</type>, <type>float</type> and <type>bool</type>. </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;. + The handling of function scalar type hints depends on the per-file + strict_types directive. If this directive is set to 0 or not specified, + PHP will attempt to convert the supplied argument value to the type specified + by the type hint if they do not match. If this directive is set to 1, + a type mismatch will cause a TypeError to be thrown. </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>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; + <para> + A type hinted value will always be of the specified type within the function, + irrespective of the strict_types setting. An integer value will always be accepted + for an argument with a <type>float</type> type hint, though the reverse will not + happen. + </para> + <para> <example> - <title>Basic class type declaration</title> + <title>Scalar Type Hint Examples</title> <programlisting role="php"> <![CDATA[ <?php -class C {} -class D extends C {} +declare(strict_types=1); // Fatal error if this is not the first statement +include "foo.php"; -// This doesn't extend C. -class E {} +foo(); // strictly type-checked function call -function f(C $c) { - echo get_class($c)."n"; +function foobar() { + foo(); // strictly type-checked function call +} + +class baz { + function foobar() { + foo(); // strictly type-checked function call + } } -f(new C); -f(new D); -f(new E); -?> ]]> </programlisting> - &example.outputs; - <screen> + <programlisting role="php"> <![CDATA[ -C -D +<?php +declare(strict_types=1); // file 1 -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> +/* + file 1 - strictly type checked + file 2 - weakly type checked +*/ - <example> - <title>Basic interface type declaration</title> - <programlisting role="php"> -<![CDATA[ -<?php -interface I { public function f(); } -class C implements I { public function f() {} } +include 'file2.php'; -// This doesn't implement I. -class E {} +a(1); // strictly type checked +b(1); // strictly type checked -function f(I $i) { - echo get_class($i)."n"; +function a(int $a) { + return $a; } -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> +<?php // file 2 - <example> - <title>Nullable type declaration</title> - <programlisting role="php"> -<![CDATA[ -<?php -class C {} +b(1); // weakly type checked -function f(C $c = null) { - var_dump($c); +function b(int $a) { + return $a; } -f(new C); -f(null); ?> + ]]> </programlisting> - &example.outputs; - <screen> + <programlisting role="php"> <![CDATA[ -object(C)#1 (0) { -} -NULL -]]> - </screen> - </example> - </sect3> +<?php // file 1 - <sect3 xml:id="functions.arguments.type-declaration.strict"> - <title>Strict typing</title> +/* + file 1 - weakly type checked + file 2 - strictly type checked +*/ - <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>integer</type> for a parameter that expects a <type>string</type> - will get a variable of type <type>string</type>. - </para> +include 'file2.php'; - <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>integer</type> may be given - to a function expecting a <type>float</type>. - </para> +a(1); // weakly type checked +b(1); // weakly type checked - <para> - To enable strict mode, the &declare; statement is used with the - <literal>strict_types</literal> declaration: - </para> +function a(int $a) { + return $a; +} - <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"> -<![CDATA[ -<?php +?> + +<?php // file 2 declare(strict_types=1); -function sum(int $a, int $b) { - return $a + $b; +b(1); // strictly type checked + +function b(int $a) { + return $a; } -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> + </programlisting> </example> - - <example> - <title>Weak typing</title> - <programlisting role="php"> + </para> + + + <sect3> + <para> + <example> + <title>Type Widening</title> + <programlisting role="php"> <![CDATA[ -<?php -function sum(int $a, int $b) { - return $a + $b; +<?php +declare(strict_types=1); + +function a(float $a) { + var_dump($a); // float(1) } -var_dump(sum(1, 2)); +$a = 1; // int(1) +var_dump($a); +a($a); -// 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> - + </programlisting> + </example> + </para> + </sect3> + <sect3 xml:id="functions.scalar-type-declaration-error"> + <title>Type Error</title> + <para>Absences of a &try; &catch; block will result in a <constant>E_ERROR</constant></para> <example> - <title>Catching <classname>TypeError</classname></title> + <title>Type Error with try catch</title> <programlisting role="php"> <![CDATA[ -<?php +<?php declare(strict_types=1); -function sum(int $a, int $b) { - return $a + $b; +function show(int $intNum) +{ + return $a; } + try { - var_dump(sum(1, 2)); - var_dump(sum(1.5, 2.5)); + + show("1"); + } catch (TypeError $e) { - echo 'Error: '.$e->getMessage(); + + var_dump($e->getmessage()); // "Argument 1 passed to show() must be of the type + // integer, string given, called in %s on line %d" } ?> ]]> </programlisting> - &example.outputs; - <screen> + <programlisting role="php"> <![CDATA[ -int(3) -Error: Argument 1 passed to sum() must be of the type integer, float given, called in - on line 10 +<?php +declare(strict_types=1); + +function show(int $intNum) +{ + return $a; +} + + show("1"); // Fatal Error + +?> ]]> - </screen> + </programlisting> </example> </sect3> </sect2> <sect2 xml:id="functions.variable-arg-list"> <title>Variable-length argument lists</title> - + <simpara> PHP has support for variable-length argument lists in user-defined functions. This is implemented using the @@ -690,16 +577,16 @@ <function>func_get_arg</function>, and <function>func_get_args</function> functions in PHP 5.5 and earlier. </simpara> - + <sect3 xml:id="functions.variable-arg-list.new"> <title><literal>...</literal> in PHP 5.6+</title> - + <para> In PHP 5.6 and later, argument lists may include the <literal>...</literal> token to denote that the function accepts a variable number of arguments. The arguments will be passed into the given variable as an array; for example: - + <example> <title>Using <literal>...</literal> to access variable arguments</title> <programlisting role="php"> @@ -725,12 +612,12 @@ </screen> </example> </para> - + <para> You can also use <literal>...</literal> when calling functions to unpack an <type>array</type> or <classname>Traversable</classname> variable or literal into the argument list: - + <example> <title>Using <literal>...</literal> to provide arguments</title> <programlisting role="php"> @@ -756,20 +643,20 @@ </screen> </example> </para> - + <para> You may specify normal positional arguments before the <literal>...</literal> token. In this case, only the trailing arguments that don't match a positional argument will be added to the array generated by <literal>...</literal>. </para> - + <para> It is also possible to add a <link linkend="language.oop5.typehinting">type hint</link> before the <literal>...</literal> token. If this is present, then all arguments captured by <literal>...</literal> must be objects of the hinted class. - + <example> <title>Type hinted variable arguments</title> <programlisting role="php"> @@ -801,7 +688,7 @@ </screen> </example> </para> - + <para> Finally, you may also pass variable arguments <link linkend="functions.arguments.by-reference">by reference</link> by @@ -809,21 +696,21 @@ (<literal>&</literal>). </para> </sect3> - + <sect3 xml:id="functions.variable-arg-list.old"> <title>Older versions of PHP</title> - + <para> No special syntax is required to note that a function is variadic; however access to the function's arguments must use <function>func_num_args</function>, <function>func_get_arg</function> and <function>func_get_args</function>. </para> - + <para> The first example above would be implemented as follows in PHP 5.5 and earlier: - + <example> <title>Accessing variable arguments in PHP 5.5 and earlier</title> <programlisting role="php"> @@ -850,13 +737,14 @@ </example> </para> </sect3> - + </sect2> + </sect1> - + <sect1 xml:id="functions.returning-values"> <title>Returning values</title> - + <para> Values are returned by using the optional return statement. Any type may be returned, including arrays and objects. This causes the @@ -864,20 +752,36 @@ 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 hints</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> - <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) @@ -887,18 +791,18 @@ 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() @@ -908,18 +812,18 @@ list ($zero, $one, $two) = small_numbers(); ?> ]]> - </programlisting> - </example> - </para> - <para> - To return a reference from a function, use the reference operator & 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 & 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() @@ -930,129 +834,168 @@ $newref =& returns_reference(); ?> ]]> - </programlisting> - </example> - </para> - <simpara> - For more information on references, please check out <link - linkend="language.references">References Explained</link>. - </simpara> - </sect2> + </programlisting> + </example> + </para> + <simpara> + For more information on references, please check out <link + linkend="language.references">References Explained</link>. + </simpara> + </sect2> + <sect2> + <title>Return Type Hints</title> + <para> + Starting with PHP 7, a function can specify the type of value that + it returns. This is achieved by adding a colon (:) followed by the + type name after the closing parenthesis of the function declaration. + </para> + <para> + Valid values for a return type hint are class names, interface names, + <type>array</type>, and the scalar types <type>string</type>, + <type>int</type>, <type>float</type> and <type>bool</type>. + </para> + <para> + The handling of function return types depends on the per-file + strict_types directive. If this directive is set to 0 or not specified, + PHP will attempt to convert the returned value to the type specified by + the return type hint if they do not match. If this directive is set to 1, + a type mismatch will cause a TypeError to be thrown. + </para> + <para> + Return types that are specified on an object's method must match those + specified on the parent method. However, if the parent class does not + specify a return type, a child class may introduce a return type hint. + </para> + <para> + <example> + <title>The strict_types directive</title> + <programlisting role="php"> +<![CDATA[ +<?php +declare(strict_types=1); // file1.php - <sect2 xml:id="functions.returning-values.type-declaration"> - <title>Return type declarations</title> +// file 1 - strictly type checked +// file 2 - weakly type checked - <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> +include "file2.php"; - <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> +var_dump(a()); // works correctly +var_dump(b()); // fatal TypeError - <note> - <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; +function b() : int{ + return "1"; +} +?> + - <example> - <title>Basic return type declaration</title> - <programlisting role="php"> -<![CDATA[ <?php -function sum($a, $b): float { - return $a + $b; +// file2.php +function a(): int{ + return "1"; } -// Note that a float will be returned. -var_dump(sum(1, 2)); ?> ]]> </programlisting> - &example.outputs; - <screen> -<![CDATA[ -float(3) -]]> - </screen> </example> - + </para> + <para> <example> - <title>Strict mode in action</title> + <title>More Return Types</title> <programlisting role="php"> <![CDATA[ <?php declare(strict_types=1); -function sum($a, $b): int { - return $a + $b; +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 + } } -var_dump(sum(1, 2)); -var_dump(sum(1, 2.5)); +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.outputs; - <screen> + </programlisting> + </example> + </para> + <para> + <example> + <title>Return a class</title> + <programlisting role="php"> <![CDATA[ -int(3) +<?php +declare(strict_types=1); -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 +interface A { + static function make(); +} +class B implements A { + static function make(): B { //valid + return new B(); + } +} ]]> - </screen> - </example> - + </programlisting> + </example> + </para> + <para> <example> - <title>Returning an object</title> - <programlisting role="php"> + <title>TypeError</title> + <para>Incorrect return type will result in a TypeError</para> + <programlisting role="php"> <![CDATA[ <?php -class C {} +declare(strict_types=1); -function getC(): C { - return new C; +function show(): int{ + return "1"; } -var_dump(getC()); -?> -]]> - </programlisting> - &example.outputs; - <screen> -<![CDATA[ -object(C)#1 (0) { +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" } +?> ]]> - </screen> - </example> - </sect3> + </programlisting> + </example> + </para> </sect2> </sect1> - + <sect1 xml:id="functions.variable-functions"> <title>Variable functions</title> - + <para> PHP supports the concept of variable functions. This means that if a variable name has parentheses appended to it, PHP will look for @@ -1157,70 +1100,12 @@ </programlisting> </example> </para> - <para> - As of PHP 5.4.0, you can call any <type>callable</type> stored in a variable. - <example> - <title>Complex callables</title> - <programlisting role="php"> -<![CDATA[ -class Foo -{ - static function bar() - { - echo "barn"; - } - function baz() - { - echo "bazn"; - } -} - -$func = array("Foo", "bar"); -$func(); // prints "bar" -$f = array(new Foo, "baz"); -$func(); // prints "baz" -$f = "Foo::bar"; -$func(); // prints "bar" as of PHP 7.0.0; prior, it raised a fatal error -]]> - </programlisting> - </example> - </para> - + <para> See also <function>is_callable</function>, <function>call_user_func</function>, <link linkend="language.variables.variable"> - variable variables</link> and <function>function_exists</function>. + variable variables</link> and <function>function_exists</function>. </para> - - <sect2 role="changelog"> - &reftitle.changelog; - <para> - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>&Version;</entry> - <entry>&Description;</entry> - </row> - </thead> - <tbody> - <row> - <entry>7.0.0</entry> - <entry> - 'ClassName::methodName' is allowed as variable function. - </entry> - </row> - <row> - <entry>5.4.0</entry> - <entry> - Arrays, which are valid callables, are allowed as variable functions. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> - </para> - </sect2> </sect1> <sect1 xml:id="functions.internal"> @@ -1278,14 +1163,14 @@ <sect1 xml:id="functions.anonymous"> <title>Anonymous functions</title> - + <simpara> Anonymous functions, also known as <literal>closures</literal>, allow the creation of functions which have no specified name. They are most useful as the value of <link linkend="language.types.callback">callback</link> parameters, but they have many other uses. </simpara> - + <example> <title>Anonymous function example</title> <programlisting role="php"> @@ -1299,7 +1184,7 @@ ]]> </programlisting> </example> - + <simpara> Closures can also be used as the values of variables; PHP automatically converts such expressions into instances of the @@ -1307,7 +1192,7 @@ variable uses the same syntax as any other assignment, including the trailing semicolon: </simpara> - + <example> <title>Anonymous function variable assignment example</title> <programlisting role="php"> @@ -1329,7 +1214,7 @@ Closures may also inherit variables from the parent scope. Any such variables must be passed to the <literal>use</literal> language construct. </simpara> - + <example> <title>Inheriting variables from the parent scope</title> <programlisting role="php"> @@ -1389,7 +1274,7 @@ ]]> </screen> </example> - + <simpara> Inheriting variables from the parent scope is <emphasis>not</emphasis> the same as using global variables. @@ -1398,7 +1283,7 @@ function in which the closure was declared (not necessarily the function it was called from). See the following example: </simpara> - + <example> <title>Closures and scoping</title> <programlisting role="php"> @@ -1493,7 +1378,7 @@ </informaltable> </para> </sect2> - + <sect2 role="notes"> &reftitle.notes; <note> @@ -1504,11 +1389,11 @@ </simpara> </note> </sect2> - + </sect1> + +</chapter> - </chapter> -  +--> No newline at end of file => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=63827 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=63827 ------------------------------------------------------------------ Modified: en/language/constants.xml By: Christopher Pitt on 2015-07-28 18:02:53 =================================================================== --- en/language/constants.xml +++ en/language/constants.xml @@ -57,6 +57,12 @@ For more information on scope, read the manual section on <link linkend="language.variables.scope">variable scope</link>. </simpara> + + <simpara> + There are a number of useful + <link linkend="reserved.constants">predefined constants</link> + which provide environmental/runtime information. + </simpara> <sect1 xml:id="language.constants.syntax"> <title>Syntax</title> => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=63864 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=63864 ------------------------------------------------------------------ Modified: en/reference/filesystem/functions/fopen.xml By: on 2015-08-07 11:40:32 =================================================================== --- en/reference/filesystem/functions/fopen.xml +++ en/reference/filesystem/functions/fopen.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="utf-8"?> - + <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.fopen"> <refnamediv> <refname>fopen</refname> @@ -133,8 +133,7 @@ <entry> Open for writing only; place the file pointer at the end of the file. If the file does not exist, attempt to create it. - In this mode, <function>fseek</function> only affects - the reading position, writes are always appended. + In this mode, <function>fseek</function> has no effect, writes are always appended. </entry> </row> <row> => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=63982 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=63982 ------------------------------------------------------------------ Modified: en/reference/misc/functions/eval.xml By: Bernhard Breytenbach on 2015-08-16 11:24:49 =================================================================== --- en/reference/misc/functions/eval.xml +++ en/reference/misc/functions/eval.xml @@ -40,9 +40,9 @@ The code must not be wrapped in opening and closing <link linkend="language.basic-syntax.phpmode">PHP tags</link>, i.e. <literal>'echo "Hi!";'</literal> must be passed instead of - <literal>'<? echo "Hi!"; ?>'</literal>. It is still possible to leave and + <literal>'<?php echo "Hi!"; ?>'</literal>. It is still possible to leave and re-enter PHP mode though using the appropriate PHP tags, e.g. - <literal>'echo "In PHP mode!"; ?>In HTML mode!<? echo "Back in PHP mode!";'</literal>. + <literal>'echo "In PHP mode!"; ?>In HTML mode!<?php echo "Back in PHP mode!";'</literal>. </para> <para> Apart from that the passed code must be valid PHP. This includes that all statements => Put this change into your patches : https://edit.php.net/?project=php&action=putIntoMyPatches&idDB=64229 => Delete this change: https://edit.php.net/?project=php&action=deleteThisChange&idDB=64229 ------------------------------------------------------------------ -- https://edit.php.net/ This email is send automatically by the Php Docbook Online Editor.