mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 08:28:54 +00:00

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
697 lines
18 KiB
XML
697 lines
18 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
|
|
<sect1 xml:id="migration70.new-features" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>New features</title>
|
|
|
|
<sect2 xml:id="migration70.new-features.scalar-type-declarations">
|
|
<title>Scalar type declarations</title>
|
|
|
|
<para>
|
|
Scalar
|
|
<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
|
|
numbers (<type>float</type>), and booleans (<literal>bool</literal>). They
|
|
augment the other types introduced in PHP 5: class names, interfaces,
|
|
<type>array</type> and <type>callable</type>.
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// Coercive mode
|
|
function sumOfInts(int ...$ints)
|
|
{
|
|
return array_sum($ints);
|
|
}
|
|
|
|
var_dump(sumOfInts(2, '3', 4.1));
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
int(9)
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
|
|
<para>
|
|
To enable strict mode, a single &declare; directive must be placed at the
|
|
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="language.types.declarations">return type declarations</link>,
|
|
built-in PHP functions, and functions from loaded
|
|
extensions.
|
|
</para>
|
|
|
|
<para>
|
|
Full documentation and examples of scalar type declarations can be found in
|
|
the
|
|
<link linkend="language.types.declarations">type declaration</link>
|
|
reference.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration70.new-features.return-type-declarations">
|
|
<title>Return type declarations</title>
|
|
|
|
<para>
|
|
PHP 7 adds support for
|
|
<link linkend="language.types.declarations">return type declarations</link>.
|
|
Similarly to
|
|
<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="language.types.declarations">types</link>
|
|
are available for return type declarations as are available for argument
|
|
type declarations.
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
function arraysSum(array ...$arrays): array
|
|
{
|
|
return array_map(function(array $array): int {
|
|
return array_sum($array);
|
|
}, $arrays);
|
|
}
|
|
|
|
print_r(arraysSum([1,2,3], [4,5,6], [7,8,9]));
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
Array
|
|
(
|
|
[0] => 6
|
|
[1] => 15
|
|
[2] => 24
|
|
)
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
|
|
<para>
|
|
Full documentation and examples of return type declarations can be found in
|
|
the
|
|
<link linkend="language.types.declarations">return type declarations</link>.
|
|
reference.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration70.new-features.null-coalesce-op">
|
|
<title>Null coalescing operator</title>
|
|
|
|
<para>
|
|
The null coalescing operator (<literal>??</literal>) has been added as
|
|
syntactic sugar for the common case of needing to use a ternary in
|
|
conjunction with <function>isset</function>. It returns its first operand
|
|
if it exists and is not &null;; otherwise it returns its second operand.
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// Fetches the value of $_GET['user'] and returns 'nobody'
|
|
// if it does not exist.
|
|
$username = $_GET['user'] ?? 'nobody';
|
|
// This is equivalent to:
|
|
$username = isset($_GET['user']) ? $_GET['user'] : 'nobody';
|
|
|
|
// Coalescing can be chained: this will return the first
|
|
// defined value out of $_GET['user'], $_POST['user'], and
|
|
// 'nobody'.
|
|
$username = $_GET['user'] ?? $_POST['user'] ?? 'nobody';
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
|
|
<!-- TODO: we don't need further details here, but this still has to be
|
|
added to the operator precedence table -->
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration70.new-features.spaceship-op">
|
|
<title>Spaceship operator</title>
|
|
<para>
|
|
The spaceship operator is used for comparing two expressions. It returns -1, 0
|
|
or 1 when <varname>$a</varname> is respectively less than, equal to, or greater
|
|
than <varname>$b</varname>. Comparisons are performed according to PHP's usual
|
|
<link linkend="types.comparisons">type comparison rules</link>.
|
|
</para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// Integers
|
|
echo 1 <=> 1; // 0
|
|
echo 1 <=> 2; // -1
|
|
echo 2 <=> 1; // 1
|
|
|
|
// Floats
|
|
echo 1.5 <=> 1.5; // 0
|
|
echo 1.5 <=> 2.5; // -1
|
|
echo 2.5 <=> 1.5; // 1
|
|
|
|
// Strings
|
|
echo "a" <=> "a"; // 0
|
|
echo "a" <=> "b"; // -1
|
|
echo "b" <=> "a"; // 1
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
|
|
<!-- TODO: we don't need further details here, but this still has to be
|
|
added to the operator precedence table -->
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration70.new-features.define-array">
|
|
<title>Constant arrays using <function>define</function></title>
|
|
|
|
<para>
|
|
<type>Array</type> constants can now be defined with
|
|
<function>define</function>. In PHP 5.6, they could only be defined with
|
|
&const;.
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
define('ANIMALS', [
|
|
'dog',
|
|
'cat',
|
|
'bird'
|
|
]);
|
|
|
|
echo ANIMALS[1]; // outputs "cat"
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration70.new-features.anonymous-classes">
|
|
<title>Anonymous classes</title>
|
|
|
|
<para>
|
|
Support for anonymous classes has been added via <literal>new
|
|
class</literal>. These can be used in place of full class definitions for
|
|
throwaway objects:
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
interface Logger {
|
|
public function log(string $msg);
|
|
}
|
|
|
|
class Application {
|
|
private $logger;
|
|
|
|
public function getLogger(): Logger {
|
|
return $this->logger;
|
|
}
|
|
|
|
public function setLogger(Logger $logger) {
|
|
$this->logger = $logger;
|
|
}
|
|
}
|
|
|
|
$app = new Application;
|
|
$app->setLogger(new class implements Logger {
|
|
public function log(string $msg) {
|
|
echo $msg;
|
|
}
|
|
});
|
|
|
|
var_dump($app->getLogger());
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
object(class@anonymous)#2 (0) {
|
|
}
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
|
|
<para>
|
|
Full documentation can be found in the
|
|
<link linkend="language.oop5.anonymous">anonymous class reference</link>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration70.new-features.unicode-codepoint-escape-syntax">
|
|
<title>Unicode codepoint escape syntax</title>
|
|
|
|
<para>
|
|
This takes a Unicode codepoint in hexadecimal form, and outputs that
|
|
codepoint in UTF-8 to a double-quoted string or a heredoc. Any valid
|
|
codepoint is accepted, with leading 0's being optional.
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
echo "\u{aa}";
|
|
echo "\u{0000aa}";
|
|
echo "\u{9999}";
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
ª
|
|
ª (same as before but with optional leading 0's)
|
|
香
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration70.new-features.closure-call-method">
|
|
<title><methodname>Closure::call</methodname></title>
|
|
|
|
<para>
|
|
<methodname>Closure::call</methodname> is a more performant, shorthand way
|
|
of temporarily binding an object scope to a closure and invoking it.
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
class A {private $x = 1;}
|
|
|
|
// Pre PHP 7 code
|
|
$getX = function() {return $this->x;};
|
|
$getXCB = $getX->bindTo(new A, 'A'); // intermediate closure
|
|
echo $getXCB();
|
|
|
|
// PHP 7+ code
|
|
$getX = function() {return $this->x;};
|
|
echo $getX->call(new A);
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
1
|
|
1
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</sect2>
|
|
<sect2 xml:id="migration70.new-features.filtered-unserialize">
|
|
<title>Filtered <function>unserialize</function></title>
|
|
|
|
<para>
|
|
This feature seeks to provide better security when unserializing objects on
|
|
untrusted data. It prevents possible code injections by enabling the
|
|
developer to whitelist classes that can be unserialized.
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
// converts all objects into __PHP_Incomplete_Class object
|
|
$data = unserialize($foo, ["allowed_classes" => false]);
|
|
|
|
// converts all objects into __PHP_Incomplete_Class object except those of MyClass and MyClass2
|
|
$data = unserialize($foo, ["allowed_classes" => ["MyClass", "MyClass2"]]);
|
|
|
|
// default behaviour (same as omitting the second argument) that accepts all classes
|
|
$data = unserialize($foo, ["allowed_classes" => true]);
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration70.new-features.intlchar">
|
|
<title><classname>IntlChar</classname></title>
|
|
|
|
<para>
|
|
The new <classname>IntlChar</classname> class seeks to expose additional
|
|
ICU functionality. The class itself defines a number of static methods and
|
|
constants that can be used to manipulate unicode characters.
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
printf('%x', IntlChar::CODEPOINT_MAX);
|
|
echo IntlChar::charName('@');
|
|
var_dump(IntlChar::ispunct('!'));
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
10ffff
|
|
COMMERCIAL AT
|
|
bool(true)
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
|
|
<para>
|
|
In order to use this class, the <link linkend="book.intl">Intl</link> extension must be installed.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration70.new-features.expectations">
|
|
<title>Expectations</title>
|
|
|
|
<para>
|
|
<link linkend="function.assert.expectations">Expectations</link> are a
|
|
backwards compatible enhancement to the older <function>assert</function>
|
|
function. They allow for zero-cost assertions in production code, and
|
|
provide the ability to throw custom exceptions when the assertion fails.
|
|
</para>
|
|
|
|
<para>
|
|
While the old API continues to be maintained for compatibility,
|
|
<function>assert</function> is now a language construct, allowing the first
|
|
parameter to be an expression rather than just a <type>string</type> to be
|
|
evaluated or a <type>bool</type> value to be tested.
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
ini_set('assert.exception', 1);
|
|
|
|
class CustomError extends AssertionError {}
|
|
|
|
assert(false, new CustomError('Some error message'));
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
Fatal error: Uncaught CustomError: Some error message
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
|
|
<para>
|
|
Full details on this feature, including how to configure it in both
|
|
development and production environments, can be found in the
|
|
<link linkend="function.assert.expectations">expectations section</link>
|
|
of the <function>assert</function> reference.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration70.new-features.group-use-declarations">
|
|
<title>Group <literal>use</literal> declarations</title>
|
|
|
|
<para>
|
|
Classes, functions and constants being imported from the same &namespace;
|
|
can now be grouped together in a single &use.namespace; statement.
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// Pre PHP 7 code
|
|
use some\namespace\ClassA;
|
|
use some\namespace\ClassB;
|
|
use some\namespace\ClassC as C;
|
|
|
|
use function some\namespace\fn_a;
|
|
use function some\namespace\fn_b;
|
|
use function some\namespace\fn_c;
|
|
|
|
use const some\namespace\ConstA;
|
|
use const some\namespace\ConstB;
|
|
use const some\namespace\ConstC;
|
|
|
|
// PHP 7+ code
|
|
use some\namespace\{ClassA, ClassB, ClassC as C};
|
|
use function some\namespace\{fn_a, fn_b, fn_c};
|
|
use const some\namespace\{ConstA, ConstB, ConstC};
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration70.new-features.generator-return-expressions">
|
|
<title>Generator Return Expressions</title>
|
|
|
|
<para>
|
|
This feature builds upon the generator functionality introduced into PHP 5.5.
|
|
It enables for a <literal>return</literal> statement to be used within a
|
|
generator to enable for a final expression to be returned (return by
|
|
reference is not allowed). This value can be fetched using the new
|
|
<literal>Generator::getReturn()</literal> method, which may only be used
|
|
once the generator has finished yielding values.
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
$gen = (function() {
|
|
yield 1;
|
|
yield 2;
|
|
|
|
return 3;
|
|
})();
|
|
|
|
foreach ($gen as $val) {
|
|
echo $val, PHP_EOL;
|
|
}
|
|
|
|
echo $gen->getReturn(), PHP_EOL;
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
1
|
|
2
|
|
3
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
|
|
<para>
|
|
Being able to explicitly return a final value from a generator is a handy
|
|
ability to have. This is because it enables for a final value to be returned
|
|
by a generator (from perhaps some form of coroutine computation) that can be
|
|
specifically handled by the client code executing the generator. This is far
|
|
simpler than forcing the client code to firstly check whether the final
|
|
value has been yielded, and then if so, to handle that value specifically.
|
|
</para>
|
|
</sect2>
|
|
<sect2 xml:id="migration70.new-features.generator-delegation">
|
|
<title>Generator delegation</title>
|
|
|
|
<para>
|
|
Generators can now delegate to another generator,
|
|
<classname>Traversable</classname> object or <type>array</type>
|
|
automatically, without needing to write boilerplate in the outermost
|
|
generator by using the &yield.from; construct.
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
function gen()
|
|
{
|
|
yield 1;
|
|
yield 2;
|
|
yield from gen2();
|
|
}
|
|
|
|
function gen2()
|
|
{
|
|
yield 3;
|
|
yield 4;
|
|
}
|
|
|
|
foreach (gen() as $val)
|
|
{
|
|
echo $val, PHP_EOL;
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
1
|
|
2
|
|
3
|
|
4
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration70.new-features.intdiv">
|
|
<title>Integer division with <function>intdiv</function></title>
|
|
|
|
<para>
|
|
The new <function>intdiv</function> function performs an integer division
|
|
of its operands and returns it.
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
var_dump(intdiv(10, 3));
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
int(3)
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration70.new-features.session-options">
|
|
<title>Session options</title>
|
|
|
|
<para>
|
|
<function>session_start</function> now accepts an <type>array</type> of
|
|
options that override the
|
|
<link linkend="session.configuration">session configuration directives</link>
|
|
normally set in php.ini.
|
|
</para>
|
|
|
|
<para>
|
|
These options have also been expanded to support
|
|
<link linkend="ini.session.lazy-write">session.lazy_write</link>, which is
|
|
on by default and causes PHP to only overwrite any session file if the
|
|
session data has changed, and <literal>read_and_close</literal>, which is
|
|
an option that can only be passed to <function>session_start</function> to
|
|
indicate that the session data should be read and then the session should
|
|
immediately be closed unchanged.
|
|
</para>
|
|
|
|
<para>
|
|
For example, to set
|
|
<link linkend="ini.session.cache-limiter">session.cache_limiter</link> to
|
|
<literal>private</literal> and immediately close the session after reading
|
|
it:
|
|
</para>
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
session_start([
|
|
'cache_limiter' => 'private',
|
|
'read_and_close' => true,
|
|
]);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration70.new-features.preg-repace-callback-array-function">
|
|
<title><function>preg_replace_callback_array</function></title>
|
|
|
|
<para>
|
|
The new <function>preg_replace_callback_array</function> function enables
|
|
code to be written more cleanly when using the
|
|
<function>preg_replace_callback</function> function. Prior to PHP 7,
|
|
callbacks that needed to be executed per regular expression required the
|
|
callback function to be polluted with lots of branching.
|
|
</para>
|
|
|
|
<para>
|
|
Now, callbacks can be registered to each regular expression using an
|
|
associative array, where the key is a regular expression and the value is a
|
|
callback.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration70.new-features.csprng-functions">
|
|
<title><link linkend="book.csprng">CSPRNG</link> Functions</title>
|
|
|
|
<para>
|
|
Two new functions have been added to generate cryptographically secure
|
|
integers and strings in a cross platform way:
|
|
<function>random_bytes</function> and <function>random_int</function>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration70.new-features.list-arrayaccess">
|
|
<title>
|
|
<function>list</function> can always unpack objects implementing
|
|
<classname>ArrayAccess</classname>
|
|
</title>
|
|
|
|
<para>
|
|
Previously, <function>list</function> was not guaranteed to operate
|
|
correctly with objects implementing <classname>ArrayAccess</classname>.
|
|
This has been fixed.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 xml:id="migration70.new-features.others">
|
|
<title>Other Features</title>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
Class member access on cloning has been added,
|
|
e.g. <literal>(clone $foo)->bar()</literal>.
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</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
|
|
-->
|