# New features

## Scalar type declarations

Scalar [type declarations](#language.types.declarations) come in two flavours: coercive (default) and strict. The following types for parameters can now be enforced (either coercively or strictly): strings (`string`), integers (`int`), floating-point numbers (`float`), and booleans (`bool`). They augment the other types introduced in PHP 5: class names, interfaces, `array` and `callable`.

<div class="informalexample">

```
<?php
// Coercive mode
function sumOfInts(int ...$ints)
{
    return array_sum($ints);
}

var_dump(sumOfInts(2, '3', 4.1));

   
```

ENTITY

    int(9)

       

</div>

To enable strict mode, a single ENTITY 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 [return type declarations](#language.types.declarations), built-in PHP functions, and functions from loaded extensions.

Full documentation and examples of scalar type declarations can be found in the [type declaration](#language.types.declarations) reference.

## Return type declarations

PHP 7 adds support for [return type declarations](#language.types.declarations). Similarly to [argument type declarations](#language.types.declarations), return type declarations specify the type of the value that will be returned from a function. The same [types](#language.types.declarations) are available for return type declarations as are available for argument type declarations.

<div class="informalexample">

```
<?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]));

   
```

ENTITY

    Array
    (
        [0] => 6
        [1] => 15
        [2] => 24
    )

       

</div>

Full documentation and examples of return type declarations can be found in the [return type declarations](#language.types.declarations). reference.

## Null coalescing operator

The null coalescing operator (`??`) has been added as syntactic sugar for the common case of needing to use a ternary in conjunction with `isset`. It returns its first operand if it exists and is not ENTITY; otherwise it returns its second operand.

<div class="informalexample">

```
<?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';
?>

   
```

</div>

## Spaceship operator

The spaceship operator is used for comparing two expressions. It returns -1, 0 or 1 when `$a` is respectively less than, equal to, or greater than `$b`. Comparisons are performed according to PHP's usual [type comparison rules](#types.comparisons).

<div class="informalexample">

```
<?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
?>

   
```

</div>

## Constant arrays using `define`

`Array` constants can now be defined with `define`. In PHP 5.6, they could only be defined with ENTITY.

<div class="informalexample">

```
<?php
define('ANIMALS', [
    'dog',
    'cat',
    'bird'
]);

echo ANIMALS[1]; // outputs "cat"
?>

   
```

</div>

## Anonymous classes

Support for anonymous classes has been added via `new class`. These can be used in place of full class definitions for throwaway objects:

<div class="informalexample">

```
<?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());
?>

   
```

ENTITY

    object(class@anonymous)#2 (0) {
    }

       

</div>

Full documentation can be found in the [anonymous class reference](#language.oop5.anonymous).

## Unicode codepoint escape syntax

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.

<div class="informalexample">

```
<?php

echo "\u{aa}", PHP_EOL;
echo "\u{0000aa}", PHP_EOL;

echo "\u{9999}", PHP_EOL;

echo <<<EOT
\u{01f418}
EOT;

?>

   
```

ENTITY

    ª
    ª (same as before but with optional leading 0's)
    香

       

</div>

## Closure::call

Closure::call is a more performant, shorthand way of temporarily binding an object scope to a closure and invoking it.

<div class="informalexample">

```
<?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);

   
```

ENTITY

    1
    1

       

</div>

## Filtered `unserialize`

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.

<div class="informalexample">

```
<?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]);

   
```

</div>

## `IntlChar`

The new `IntlChar` 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.

<div class="informalexample">

```
<?php

printf('%x', IntlChar::CODEPOINT_MAX);
echo IntlChar::charName('@');
var_dump(IntlChar::ispunct('!'));

   
```

ENTITY

    10ffff
    COMMERCIAL AT
    bool(true)

       

</div>

In order to use this class, the [Intl](#book.intl) extension must be installed.

## Expectations

Expectations are a backwards compatible enhancement to the older `assert` function. They allow for zero-cost assertions in production code, and provide the ability to throw custom exceptions when the assertion fails.

While the old API continues to be maintained for compatibility, `assert` is now a language construct, allowing the first parameter to be an expression rather than just a `string` to be evaluated or a `bool` value to be tested.

<div class="informalexample">

```
<?php
ini_set('assert.exception', 1);

class CustomError extends AssertionError {}

assert(false, new CustomError('Some error message'));
?>

   
```

ENTITY

    Fatal error: Uncaught CustomError: Some error message

       

</div>

Full details on this feature, including how to configure it in both development and production environments, can be found on the manual page of the `assert` language construct.

## Group `use` declarations

Classes, functions and constants being imported from the same ENTITY can now be grouped together in a single ENTITY statement.

<div class="informalexample">

```
<?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};
?>

   
```

</div>

## Generator Return Expressions

This feature builds upon the generator functionality introduced into PHP 5.5. It enables for a `return` 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 `Generator::getReturn()` method, which may only be used once the generator has finished yielding values.

<div class="informalexample">

```
<?php

$gen = (function() {
    yield 1;
    yield 2;

    return 3;
})();

foreach ($gen as $val) {
    echo $val, PHP_EOL;
}

echo $gen->getReturn(), PHP_EOL;

   
```

ENTITY

    1
    2
    3

       

</div>

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.

## Generator delegation

Generators can now delegate to another generator, `Traversable` object or `array` automatically, without needing to write boilerplate in the outermost generator by using the ENTITY construct.

<div class="informalexample">

```
<?php
function gen()
{
    yield 1;
    yield 2;
    yield from gen2();
}

function gen2()
{
    yield 3;
    yield 4;
}

foreach (gen() as $val)
{
    echo $val, PHP_EOL;
}
?>

   
```

ENTITY

    1
    2
    3
    4

       

</div>

## Integer division with `intdiv`

The new `intdiv` function performs an integer division of its operands and returns it.

<div class="informalexample">

```
<?php
var_dump(intdiv(10, 3));
?>

   
```

ENTITY

    int(3)

       

</div>

## Session options

`session_start` now accepts an `array` of options that override the [session configuration directives](#session.configuration) normally set in php.ini.

These options have also been expanded to support [session.lazy_write](#ini.session.lazy-write), which is on by default and causes PHP to only overwrite any session file if the session data has changed, and `read_and_close`, which is an option that can only be passed to `session_start` to indicate that the session data should be read and then the session should immediately be closed unchanged.

For example, to set [session.cache_limiter](#ini.session.cache-limiter) to `private` and immediately close the session after reading it:

<div class="informalexample">

```
<?php
session_start([
    'cache_limiter' => 'private',
    'read_and_close' => true,
]);
?>

   
```

</div>

## `preg_replace_callback_array`

The new `preg_replace_callback_array` function enables code to be written more cleanly when using the `preg_replace_callback` 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.

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.

## CSPRNG Functions

Two new functions have been added to generate cryptographically secure integers and strings in a cross platform way: `random_bytes` and `random_int`.

## `list` can always unpack objects implementing `ArrayAccess`

Previously, `list` was not guaranteed to operate correctly with objects implementing `ArrayAccess`. This has been fixed.

## Other Features

- Class member access on cloning has been added, e.g. `(clone $foo)-ENTITYbar()`.