PHP strict_types

Summary: in this tutorial, you’ll learn how to enable strict typing using the PHP strict_types directive.

Introduction to the PHP strict typing

Type hints allow you to declare types for function parameters and return values. For example:

<?php

function add(int $x, int $y)
{
    return $x + $y;
}

echo add(1.5, 2.5); // 3Code language: PHP (php)

In this example, the add() function accepts two integers and returns the sum of them.

However, when you pass two floats 1.5 and 2.5, the add() function returns 3 because PHP implicitly coerces the values to the target types by default. In this case, PHP coerces the floats into integers.

To enable strict typing, you can use the declare(strict_types=1); directive at the beginning of the file like this:

<?php

declare(strict_types=1);

function add(int $x, int $y)
{
    return $x + $y;
}

echo add(1.5, 2.5); Code language: PHP (php)

By adding the strict typing directive to the file, the code will execute in the strict mode. PHP enables the strict mode on a per-file basis.

In the strict mode, PHP expects the values with the type matching with the target types. If there’s a mismatch, PHP will issue an error.

If you execute the script again, PHP will issue an error as follows:

Fatal error: Uncaught TypeError: Argument 1 passed to add() must be of the type int, float given, called in ...Code language: PHP (php)

Note that you need to place the declare(strict_types=1); directive at the beginning of the script file before any other statements.

PHP strict_types: the special case

The strict typing directive has a special case when the target type is float. If the target type is float, you can pass a value of type integer. For example:

<?php

declare(strict_types=1);

function add(float $x, float $y)
{
    return $x + $y;
}

echo add(1, 2); // 3Code language: PHP (php)

PHP strict_types and include

Suppose you define the add() function in the functions.php file:

<?php

declare(strict_types=1);

function add(int $x, int $y)
{
    return $x + $y;
}Code language: PHP (php)

And you include the functions.php in the index.php file:

<?php

include 'functions.php';

echo add(1.5, 2.5);Code language: PHP (php)

Even though the functions.php declares the strict typing directive, it does not affect the index.php.

Note that the include construct loads the code from another file into a file. And you’ll learn more about it in the later tutorial.

When you call a function defined in a file with strict typing (functions.php) from a file without strict typing (index.php), PHP will respect the preference of the caller (index.php). That means it’s up to the caller to decide whether to use the strict mode or not. In this case, the index.php won’t execute in the strict mode.

Summary

• Use the PHP strict_types directive to enable strict typing or strict mode.
• In strict mode, PHP accepts only values corresponding to the type declarations and issue a TypeError exception if there’s a mismatch.
• When you include code from another file, PHP uses the mode of the caller.