Type Hinting в PHP

В этом руководстве вы узнаете, как использовать Type Hinting (подсказки типов) PHP для объявления типов параметров функций и возвращаемых значений.

Введение в Type Hinting PHP

PHP — это динамически типизированный язык. Когда вы определяете функцию, вам не нужно объявлять типы параметров. Например:

<?php

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

$result = add(1,2);
echo $result; // 3

Функция add() принимает два аргумента и возвращает их сумму. В этом примере мы передаем в add() функцию два целых числа и получаем результат в виде целого числа.

Если вы передадите в функцию два числа с плавающей запятой add(), вы получите сумму чисел с плавающей запятой, которая является числом с плавающей запятой:

<?php

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

$result = add(1.0,2.5);
echo $result; // 3.5

Что еще интереснее, вы можете передать в функцию целое число и числовую строку add(), она вернет целое число:

<?php

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

$result = add(1,'2');
echo $result; // 3

В этом случае add() функция неявно преобразует числовую строку '2' в целое число 2 благодаря оператору +. Если PHP не сможет преобразовать строковый аргумент в целое число, он выдаст ошибку. Например:

<?php

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

$result = add('Hi','There');
echo $result;

Ошибка:

Fatal error: Uncaught TypeError: Unsupported operand types: string + string in ...Язык кода:  PHP  ( php )

Чтобы обеспечить соблюдение типов параметров функции и возвращаемого значения, вы можете использовать подсказки типов.

Обратите внимание, что PHP также позволяет использовать подсказки типов для свойств и методов класса.

Type Hinting PHP для параметров функции

Подсказки типов гарантируют, что PHP проверит тип значения во время вызова и выдаст ошибку TypeError в случае несоответствия.

Чтобы добавить подсказку типа к параметру, вы помещаете тип перед ним следующим образом:

<?php

function my_function(type $param1, type param2, ...) {
   // ...
}

В PHP 5 вы можете использовать array, callable и class для подсказок типов. В PHP 7+ вы также можете использовать скалярные типы, такие как bool, float, int и string.

Следующее определяет add() функцию, которая принимает два целых числа:

<?php

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

$result = add(1,2);
echo $result;  // 3

Однако если вы передадите два числа с плавающей запятой, вы получите результат в виде целого числа:

<?php

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

$result = add(1,2.5);
echo $result; // 3

В этом случае PHP неявно приводит 2.5 к целому числу ( 2) перед вычислением суммы. Следовательно, результат является целым числом.

По умолчанию PHP, если это возможно, приводит значение совместимого типа в ожидаемое объявление скалярного типа. Чтобы обеспечить значение с типом, соответствующим объявлению типа, вам необходимо объявить строгую типизацию .

Подсказки типов PHP для возвращаемого значения функции

Чтобы указать тип возвращаемого значения для функции, вы добавляете тип после заголовка функции следующим образом:

<?php

function my_function(type $param1, type $param2, ...) : type 
{
    // ..
}

В следующем примере определяется add() функция, которая принимает два целых числа и возвращает целое число:

<?php

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

echo add(10, 20);

Начиная с PHP 7.0, если функция не возвращает значение, вы используете void тип. Например:

<?php

function dd($data):void
{
    echo '<pre>';
    var_dump($data);
    echo '</pre>';
    die;
}

Тип объединения

Начиная с PHP 8.0, если функция возвращает значение нескольких типов, вы можете объявить ее как тип объединения. Например:

<?php

function add($x, $y): int | float
{
    return $x * $y;
}

echo add(10, 20); // 200 (int) 
echo add(1.5, 2.5); // 3.75 (float)

В этом примере add() функция возвращает целое число или число с плавающей запятой, в зависимости от типов аргументов.

Смешанный тип

Если функция возвращает значение многих типов, вы можете использовать смешанный тип. Смешанный тип означает один из нескольких типов. Смешанный тип. Это эквивалентно следующему типу объединения:

object|resource|array|string|int|float|bool|null

Смешанный вариант доступен начиная с PHP 8.0.0.

Например, встроенная функция filter_var() использует как тип объединения (массив|int), так и смешанный тип, как подсказывает тип:

filter_var(mixed $value, int $filter = FILTER_DEFAULT, array|int $options = 0): mixedЯзык кода:  PHP  ( php )

Тип, допускающий значение NULL

Следующее определяет функцию, которая принимает строку и возвращает верхний регистр этой строки:

<?php


function upper(string $str): string
{
    return strtoupper($str);
}
Язык кода:  HTML, XML  ( xml )

Если вы передадите аргумент со значением null, вы получите ошибку:

<?php

function upper(string $str): string
{
    return strtoupper($str);
}

$str = null;
echo upper($str);Язык кода:  HTML, XML  ( xml )

Ошибка:

Fatal error: Uncaught TypeError: Argument 1 passed to upper() must be of the type string, null givenЯзык кода:  открытый текст  ( открытый текст )

Чтобы исправить это, вы можете сделать параметр $str обнуляемым следующим образом:

<?php

function upper(?string $str): string
{
    return strtoupper($str);
}

$str = null;
echo upper($str);Язык кода:  HTML, XML  ( xml )

Тип, допускающий значение NULL, был введен в PHP 7.1.

PHP позволяет помечать объявления типов и возвращать значения как допускающие значение NULL, добавляя к имени типа вопросительный знак ( ?).

В приведенном выше примере мы добавляем ? к строковому типу параметра $str. Позволяет ?string передать строковый аргумент или значение NULL.

Обратите внимание, что смешанный тип уже включает нулевой тип. Поэтому вам не нужно включать смесь с нулевым значением, например:

? mixed

Кроме того, это приведет к ошибке.

Краткое содержание

  • Используйте Type Hinting PHP для параметров функций и типов возвращаемых значений.
  • Используйте void тип, если функция не возвращает никакого значения.
  • Используйте mixed тип или тип объединения, если параметр функции или возвращаемое значение функции ожидают нескольких типов.
  • Чтобы сделать тип допускающим значение NULL, поставьте перед типом вопросительный знак ( ?type).