Оголошення типів

Оголошення типів дозволено додавати до аргументів функції, значенням, що повертаються, і властивостям класу (останнє починаючи з PHP 7.4.0). Оголошені типи гарантують, що під час виклику значення належить тому типу, який для нього вказано, інакше буде викинуто виняток TypeError

Кожен тип, який підтримує PHP, за винятком ресурсів (resource), дозволено вказувати при об'явленні користувача типу. На цій сторінці наведено журнал змін доступності окремих типів та документацію про те, як їх застосовувати в оголошеннях типів.

Зауваження :

Коли клас реалізує метод інтерфейсу або перевизначає метод, який вже був визначений батьківським класом, метод, що знову визначається, повинен бути сумісний з визначенням, яке було зроблено раніше. Метод сумісний, якщо він дотримується правила варіантності

список змін

Версия	Опис
8.3.0	Додано підтримку типізації констант класів, інтерфейсів, трейтів та перерахувань.
8.2.0	Додано підтримку типів DNF.
8.2.0	Додано підтримку типу true.
8.2.0	Типи null та false тепер можна використовувати автономно.
8.1.0	Додано підтримку перетинів типів.
8.1.0	Повернення за посиланням з функції з типом значення, що повертається void застарів.
8.1.0	Додано підтримку типу повертаного значення never.
8.0.0	Додана підтримка типу значення, що повертається mixed
8.0.0	Додано підтримку типу повертаного значення static.
8.0.0	Додано підтримку об'єднання типів.
7.4.0	Додано підтримку типізації властивостей класів.
7.2.0	Додана підтримка типу значення object, що повертається.
7.1.0	Додана підтримка типу значення, що повертається iterable
7.1.0	Додано підтримку типу повертаного значення void.
7.1.0	Додана підтримка типу значення nullable.

Примітка щодо використання атомарних типів

Атомарні типи мають прямолінійну поведінку з незначними застереженнями, які описані в цьому розділі.

Скалярні типи

Увага

Псевдоніми імен для скалярних типів (bool, int, float, string) не підтримуються. Натомість вони розглядаються як імена класів або інтерфейсів. Наример, коли в якості типу вказано booleanочікується, що значення виконує умова instanceof щодо класу чи інтерфейсу boolean, а не значення типу bool:

Loading...

Результат виконання наведеного прикладу в PHP 8:

Warning: "boolean" will be interpreted as a class name. Did you mean "bool"? Write "\boolean" to suppress this warning in /in/9YrUX on line 2

Fatal error: Uncaught TypeError: test(): Argument #1 ($param) must be of type boolean, bool given, called in - on line 3 and defined in -:2
Stack trace:
#0 -(3): test(true)
#1 {main}
  thrown in - on line 2

void

Зауваження :

Повернення за посиланням з void-функції застарілий починаючи з PHP 8.1.0, оскільки така функція суперечлива. Раніше під час її виклику видавалася помилка рівня E_NOTICE: Тільки посилання на змінні повинні повертатися за посиланням
Loading...

Тип Callable

Цей тип не можна оголошувати як тип якості класу.

Зауваження: Цей тип неможливо вказати як назву функції.

Оголошення типів у параметрах передачі за посиланнями

Якщо у параметрі, що передається за посиланням, оголошується тип значення, що повертається, тип змінної перевіряється тільки при вході в функцію, на початку дзвінка, але не при поверненні функції. Тобто функція може змінити тип посилання змінну.

Приклад #1 Типизовані параметри, що передаються за посиланням

Loading...

Висновок наведеного прикладу буде схожим на:

int(1)

Fatal error: Uncaught TypeError: array_baz(): Argument #1 ($param) must be of type array, int given, called in - on line 9 and defined in -:2
Stack trace:
#0 -(9): array_baz(1)
#1 {main}
  thrown in - on line 2

Примітка щодо складових типів

На оголошення складових типів поширюється низка обмежень і під час компіляції PHP виконає перевірку оголошених типів на надмірність, щоб запобігти простим помилкам.

Застереження

До PHP 8.2.0 та появи DNF-типів, було неможливо комбінувати пересічені та об'єднані типи.

Об'єднання типів

Увага

Неможливо поєднувати два типи значень false та true. Натомість вказують bool.

Застереження

Оскільки до PHP 8.2.0 не можна було визначати false і null як окремі типи, об'єднання типів, що складалося лише з цих типів, було неприпустимим. Сюди входять типи: false, false|nullи?false

Синтаксичний цукор типу Nullable

Оголошення одного базового типу може бути позначене як nullable шляхом додавання до типу префікса у вигляді знака питання (? ). Тому ?TиT|null ідентичні.

Зауваження: Цей синтаксис підтримується з PHP 7.1.0 та передує підтримці об'єднання типів.

Зауваження :

Ще один спосіб досягти nullable-аргументів - вказати null значенням за промовчанням. Такий спосіб не рекомендований, оскільки якщо значення за замовчуванням буде змінено в дочірньому класі, виникне порушення сумісності типів, так як в оголошення типу потрібно буде додати тип null.

Приклад #2 Старий спосіб вказівки nullable-аргументів
Loading...
Результат виконання наведеного прикладу:
object(C)#1 (0) {
}
NULL

Повторювані та надлишкові типи

Надлишкові типи, які можна знайти без виконання завантаження класу, призведуть до помилки під час компіляції, щоб відловити неточності в оголошеннях складових типів. У них включено:

Кожне ім'я після дозволу внутрішніми засобами мови може зустрічатися лише один раз. Наприклад, типиint|string|INTилиCountable&Traversable&COUNTABLEприведуть до помилки.
Вказівка типуmixed(з іншими типами) призведе до помилки.
Для об'єднаних типів:
- Якщо вказано тип bool, то false чи true не може бути вказано додатково.
- Якщо вказано тип об'єкта, типи класів не можна вказувати додатково.
- Якщо вказано типiterable, то array іTraversableне можна вказувати додатково.
Для перетятих типів:
- Вказівка типу, що не відноситься до типу класу, призведе до помилки.
- Вказівка self, parent або static призведе до помилки.
Для DNF-типів:
- Якщо вказано більш загальний тип, то суворіший тип буде надлишковим.
- Дублювання членів у пересічених типах.

Зауваження: Це не гарантує, що тип мінімальний, оскільки для цього довелося б завантажити всі зазначені типи класів.

Наприклад, якщо AиB - це псевдоніми класів, то A|B залишається коректним об'єднанням типів, навіть якщо його можна звести або до A, либо кB. Аналогічно, якщо клас B extends A {}, тоA|B також є коректним поєднанням типів, навіть якщо його можна звести до просто A

Loading...

Приклади

Приклад #3 Приклад оголошення типу класу

Loading...

Результат виконання наведеного прикладу в PHP 8:

C
D

Fatal error: Uncaught TypeError: f(): Argument #1 ($c) must be of type C, E given, called in /in/gLonb on line 14 and defined in /in/gLonb:8
Stack trace:
#0 -(14): f(Object(E))
#1 {main}
  thrown in - on line 8

Приклад #4 Приклад оголошення типу інтерфейсу

Loading...

Результат виконання наведеного прикладу в PHP 8:

C

Fatal error: Uncaught TypeError: f(): Argument #1 ($i) must be of type I, 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

Приклад #5 Приклад оголошення типу значення, що повертається

Loading...

Результат виконання наведеного прикладу:

float(3)

Приклад #6 Повернення об'єкта

Loading...

Результат виконання наведеного прикладу:

object(C)#1 (0) {
}

Приклад #7 Оголошення аргументу типу Nullable

Loading...

Результат виконання наведеного прикладу:

object(C)#1 (0) {
}
NULL

Приклад #8 Оголошення типу значення, що повертається Nullable

Loading...

Приклад #9 Оголошення типу якості класу

Loading...

Сувора типізація

За промовчанням PHP перетворюватиме значення неправильного типу на очікувані. Наприклад, якщо рядковий (string) параметр функції передати ціле число (int), воно перетворюється на рядок (string).

Можна увімкнути режим суворої типізації на рівні файлу. У цьому режимі тип значення повинен суворо відповідати оголошеному, інакше буде викинуто виняток TypeError. Єдиний виняток із цього правила — передача цілого значення (int) туди, де очікується число з плаваючою точкою (float).

Увага

На дзвінки з внутрішніх функцій дія strict_types не розповсюджується.

Для включення суворої типізації вказують оператор declare з оголошенням strict_types :

Зауваження :

Сувора типізація поширюється на виклики функцій, зроблених зсередини файла з увімкненою строгою типізацією, а не до функцій, оголошених у цьому файлі. Якщо з файлу без увімкненої суворої типізації викликається функція, яка була визначена у файлі зі суворою типізацією, то будуть використані установки по типізації зухвалої сторони - тобто правила суворої типізації будуть проігноровані і для значень застосовуватиметься приведення типів.

Зауваження :

Сувора типізація визначається лише для оголошень скалярних типів.

Приклад #10 Сувора типізація для значень аргументів

Loading...

Результат виконання наведеного прикладу в PHP 8:

int(3)

Fatal error: Uncaught TypeError: sum(): Argument #1 ($a) must be of type int, 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

Приклад #11 Приведення типів для значень аргументів

Loading...

Результат виконання наведеного прикладу:

int(3)
int(3)

Приклад #12 Сувора типізація для значень, що повертаються

Loading...

Результат виконання наведеного прикладу:

int(3)

Fatal error: Uncaught TypeError: sum(): Return value must be of type int, float returned in -:5
Stack trace:
#0 -(9): sum(1, 2.5)
#1 {main}
  thrown in - on line 5