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

PHP Manual
Об этом руководстве
Как читать определения функции (прототип)

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

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

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

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

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

strlen

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

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

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

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

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

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

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

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

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

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

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

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

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

(PHP 4 >= 4.3.0, PHP 5)

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