Как читать определения функции (прототип)

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

Замечание: Предпосылки: Базовое понимание типов

Хотя 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 («иголка») и принимает разные типы, поэтому он называется «смешанным». Этот смешанный параметр needle (то, что мы ищем) может быть любым скалярным значением (string, integer, или float), либо массивом. Параметр 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.