Як читати визначення функції (прототип)

Кожна функція в посібнику задокументована так, щоб можна було швидко знайти потрібну інформацію. Знання того, як читати і розуміти даний текст, значно спрощує вивчення PHP. Замість того, щоб покладатись на приклади чи вирізати/вставляти чужий код, кожен повинен знати, як читати визначення функцій (прототипи). Почнемо:

Зауваження: Обов'язкова умова: початкове розуміння типів

Хоча PHP — це мова зі слабкою типізацією, треба мати хоча би поверхневе уявлення про типи та чому вони важливі.

Визначення функцій вказують нам, значення якого типу повертає та чи інша функція. Для нашого першого прикладу візьмемо визначення strlen():

strlen

(PHP 4, PHP 5, PHP 7)
strlen -- Отримати довжину рядка

Визначення
strlen ( string $string ) : int

Повертає довжину даного рядка.

Пояснення визначення функції

Частина	Визначення
strlen	Назва функції.
(PHP 4, PHP 5, PHP 7)	strlen() була в усіх версіях PHP 4, 5 та 7.
( string $string )	Перший (і в цьому випадку єдиний) параметр/аргумент з назвою string та з типом string.
int	Тип значення, що повертає функція — int (тобто довжина рядка — це ціле число).

Можна узагальнити наведене вище визначення функції наступним чином:

      ім'я функції    ( тип параметра   ім'я переметра ) : тип, що повертається

Багато функцій приймають декілька параметрів, наприклад, функція in_array(). Її прототип:

      in_array ( mixed $needle, array $haystack , bool $strict = false ) : bool

Що це означає? in_array() повертає логічне значення true у разі успіху (якщо needle було знайдено в haystack), або false в разі помилки у разі невдачі (якщо needle не було знайдене в haystack). Перший параметр називається needle і він може мати будь-який тип, тож ми називаємо його "mixed" (змішаним). Це needle (шукане) зі змішаним типом може мати скалярне значення (рядок, ціле число, число з рухомою точкою) або бути масивом. haystack (масив, в якому буде здійснено пошук) — це другий параметр. Третій необов'язковий параметр називається strict. Усі необов'язкові параметри мають початкові значення; якщо початкове значення невідоме, то це показано символом ?. Посібник зазначає, що параметр strict початково є логічним false. Докладніше про роботу функцій дивіться на сторінках посібника щодо кожної з них.

Крім того символ & (амперсанд), доданий до параметра функції, дозволяє передавати параметр за посиланням, як видно нижче:

       preg_match ( string $pattern , string $subject , array &$matches = null,
       int $flags = 0 , int $offset = 0 ) : int|false

В цьому прикладі ми бачимо, що третій необов'язковий параметр &$matches буде переданий за посиланням.

Також є прототипи, у яких зазначені підтримувані версії PHP. Візьмемо html_entity_decode() як приклад:

(PHP 4 >= 4.3.0, PHP 5, PHP 7)

Це означає, що дана функція стала доступна в PHP 4.3.0 та пізніших версіях.