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

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

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

Хотя PHP и является слабо типизированным языком, важно иметь базовое представление о типах, так как они играют большую роль в PHP.

Определения функций показывают нам какого типа значения они возвращают. Для первого примера возьмем определение функции strlen():

strlen

(PHP 4, PHP 5)
strlen -- Возвращает длину строки

Описание
int strlen ( string $string )

Возвращает длину переданной строки.

**Объяснение определения функции**
Часть	Описание
strlen	Имя функции.
(PHP 4, PHP 5)	strlen() была во всех версиях PHP 4 и PHP 5
int	Тип возвращаемого этой функцией значения, в данном случае integer (так как длина строки измеряется числом).
( string $string )	Первый (и в данном случае единственный) параметр/аргумент этой функции называется `string`, а его типом является string.

Можно переписать вышеуказанное определение функции в более общем виде:

      возвращаемый тип    имя функции    ( тип параметра   имя параметра )

Много функций принимают несколько параметров, например, in_array(). Ее прототип выглядит так:

      bool in_array ( mixed $needle, array $haystack [, bool $strict = FALSE ] )

Что это означает? in_array() возвращает boolean, TRUE в случае успешной работы (если needle был найден в haystack) или FALSE в случае возникновения ошибки (если needle не был найден в haystack). Первый параметр называется needle ("иголка") и может принимать много различных типов, поэтому он называется "смешанным". Этот смешанный needle (то, что мы ищем) может быть любым скалярным значением (string, integer, или float), либо массивом. haystack ("стог сена", массив, в котором мы ищем) - это второй параметр. Третий необязательный параметр называется strict ("строго"). Все необязательные параметры пишутся в [ квадратных скобках ]. Руководство указывает, что параметр strict по умолчанию принимает значение boolean FALSE. Смотрите отдельную страницу документации по каждой функции для более подробной информации по их работе.

Символ & (амперсанд), поставленный перед параметром функции позволяет передавать значение этого параметра по ссылке:

 
       int preg_match ( string $pattern , string $subject [, array &$matches 
      [, int $flags = 0 [, int $offset = 0 ]]] )

В данном примере мы можем использовать третий опциональный параметр &$matches, который будет передан по ссылке.

Есть также функции с более сложной информацией о версиях PHP. Возьмем для примера html_entity_decode():

(PHP 4 >= 4.3.0, PHP 5)

Это означает, что функция появилась в официальных версиях языка только с выхода PHP 4.3.0.