PHPTime

Как пользоваться документацией PHP: от поиска функции до миграции

Руководство PHP помогает ответить на два практических вопроса: как работает функция и будет ли она вести себя так же на сервере. Для первого достаточно разобраться в сигнатуре и возвращаемых значениях, для второго пригодятся требования к расширениям, changelog и руководства по миграции.

Как найти функцию по имени или по задаче

Если имя известно, начните с точного запроса в поиске руководства: str_contains, array_find или PDO::prepare. Для методов указывайте класс. С запросом prepare легко открыть страницу другого расширения и взять пример с другим контрактом.

Когда известно только действие, открывайте справочник подходящего расширения и смотрите список функций или методов. Для строк начните с раздела строковых функций, для работы с многобайтовым текстом загляните в mbstring, для JSON — в раздел JSON. Для операторов, преобразования типов и правил сравнения ищите в справочнике языка. Поиск по английскому названию операции помогает, если русская формулировка даёт мало результатов.

Проверяйте смысл похожих имён. str_contains() отвечает на вопрос, есть ли подстрока, а strpos() возвращает её позицию или false. Для совпадения в начале строки strpos() вернёт 0, поэтому проверка if (strpos(...)) его пропустит. У str_contains() есть свой пограничный случай: пустая подстрока считается найденной. Если она приходит из формы поиска, решите, должна ли пустая строка означать «показать всё».

Что читать на странице функции

  1. Описание и сигнатуру. Посмотрите типы аргументов, значения по умолчанию и тип результата. Символ & перед параметром означает передачу по ссылке. Если функция меняет входной массив, учитывайте это даже тогда, когда её возвращаемое значение вам не нужно.
  2. Параметры и возвращаемые значения. Здесь описано, что означают пустая строка, null, false и другие особые значения. Определите, какие из них функция возвращает при нормальной работе и какие сигнализируют об ошибке.
  3. Ошибки и исключения. Уточните реакцию на неверный тип, недопустимое значение и сбой операции. Например, TypeError и ValueError требуют разбираться с разными причинами.
  4. Примеры и примечания. Найдите пример, близкий к вашим входным данным. Если используете именованные аргументы встроенной функции, берите их имена из сигнатуры и проверяйте доступность на минимальной версии проекта.

Начинайте новые файлы со declare(strict_types=1), если проект придерживается строгой типизации. Для скалярных аргументов режим определяется файлом, из которого сделан вызов. Строгая типизация сама по себе не проверяет содержимое JSON, обязательные поля массива или диапазон чисел. Эти правила задаёт приложение.

Пример с JSON: где проходит граница контракта

У json_decode() результат типа mixed. Корректный JSON может содержать объект, массив, число или null. Флаг JSON_THROW_ON_ERROR переводит ошибки декодирования в JsonException. Форму успешно декодированных данных проверяйте отдельно.

PHP
<?php
declare(strict_types=1);

function readEmail(string $json): string
{
    // Некорректный JSON вызовет JsonException.
    $data = json_decode($json, associative: true, flags: JSON_THROW_ON_ERROR);

    // Проверяем наличие поля и его тип.
    if (!is_array($data) || !is_string($data['email'] ?? null)) {
        throw new InvalidArgumentException('Ожидается строковое поле email');
    }

    return $data['email'];
}

echo readEmail('{"email":"mailbox"}');

Пример проверяет тип поля. Если значение должно быть пригодно для отправки письма, добавьте отдельное правило проверки адреса. В обработчике запроса можно преобразовать обе ошибки в ответ клиенту, сохранив разные сообщения для некорректного JSON и для неподходящих данных.

Как проверить доступность функции и прочитать changelog

В верхней части страницы функции указано, к каким версиям PHP она относится. Для проекта с поддержкой PHP 8.3–8.5 ориентируйтесь на нижнюю границу. Например, array_find() появилась в PHP 8.4. Если минимальная версия проекта — 8.3, для поиска первого подходящего элемента можно использовать foreach с досрочным выходом. При минимальной версии 8.4 доступность array_find() уже входит в контракт проекта.

Затем откройте таблицу изменений на странице функции. В ней могут быть указаны добавленный параметр, смена значения по умолчанию, новый тип результата или исключение. Наличие функции во всех целевых версиях ещё не гарантирует, что конкретный вызов будет работать одинаково. Если поведение зависит от параметра со сменившимся значением по умолчанию, передайте нужное значение явно и покройте этот случай тестом.

Для функций расширений проверьте разделы установки и требований. Например, для работы PDO с PostgreSQL нужен драйвер pdo_pgsql. Узнать доступные драйверы можно через PDO::getAvailableDrivers(). Проверяйте окружение, в котором выполняется приложение: у консольного PHP и у PHP-FPM могут отличаться версия, конфигурация и список загруженных расширений.

У changelog есть два масштаба. Таблица изменений на странице функции помогает понять её контракт. Журнал изменений выпусков PHP помогает выяснить, исправили ли конкретный дефект в патч-релизе. При разборе дефекта ищите по имени функции, расширению или номеру ошибки и сравнивайте точные версии, например версию из рабочего контейнера и версию, на которой проходит тест.

Как использовать руководства по миграции

При переходе с PHP 8.3 на 8.5 пройдите руководства в порядке обновления: сначала с 8.3 на 8.4, затем с 8.4 на 8.5. Начните с несовместимых изменений, устаревших возможностей и изменений расширений. Список новых функций пригодится после того, как определите, какую минимальную версию сможет требовать проект.

В PHP 8.4 устарело неявное разрешение null для типизированного параметра со значением по умолчанию null. Найдите объявления вида string $locale = null и сделайте тип явным. Если null означает «выбрать локаль по умолчанию», сохраните этот смысл при изменении сигнатуры.

PHP
<?php
declare(strict_types=1);

function displayLocale(?string $locale = null): string
{
    // Без явно заданной локали берём значение приложения.
    return $locale ?? 'ru_RU';
}

echo displayLocale();

На целевой версии запустите тесты с error_reporting=E_ALL и проверьте журнал. Особое внимание уделите фоновым задачам и редким веткам, которые легко пропустить при ручной проверке. Если используете Composer, команда composer check-platform-reqs проверит требования установленных зависимостей к фактической версии PHP и расширениям. Запускайте её в целевом окружении, поскольку настройки платформы Composer могут моделировать версию, отличную от установленной.

Когда читать пользовательские комментарии

В комментариях к функциям встречаются примеры с необычными входными данными и замечания о зависимости поведения от платформы. Они особенно полезны, если описание объясняет обычный случай, а у вас проблема с пустой строкой, кодировкой, локалью или особенностью конкретного драйвера.

Посмотрите, для какой версии PHP и какого окружения приводится наблюдение. Сведите пример к нескольким строкам и запустите его на версиях, которые поддерживает проект. Если совет расходится с текущей сигнатурой или описанием ошибок, опирайтесь на контракт из руководства, а наблюдаемое поведение зафиксируйте тестом. Для различий между языковыми версиями руководства сверяйте страницу с английской версией.

Как пользоваться руководством без интернета

Сохраните HTML-версию из раздела загрузки документации. Распакованный комплект можно открывать в браузере. Для частых обращений сохраните в закладках оглавление, справочник языка и страницы расширений, которые использует проект. По отдельной странице удобно искать браузером, по всему комплекту — поиском редактора по папке.

Храните дату скачивания вместе с копией и обновляйте её перед миграцией. Офлайн-руководство отражает состояние документации на дату выгрузки, а пометки о версиях и changelog внутри подскажут, что применимо к вашей среде. Если нужное руководство по миграции отсутствует, добавьте его к комплекту перед работой без сети.

Чек-лист перед тем, как взять пример в проект

  • Откройте страницу нужной функции или метода и уточните типы, значения по умолчанию и возможные ошибки.
  • Сверьте минимальную версию PHP проекта с версией появления функции и используемых параметров.
  • Проверьте расширение и его настройки в том окружении, где приложение выполняет вызов.
  • При обновлении PHP прочитайте разделы несовместимости и устаревания для каждого перехода.
  • Проверьте обычный вызов, пограничное значение и ошибку. Для наблюдения из комментария добавьте тест, если от него зависит поведение приложения.

Частые вопросы

Как узнать, доступна ли функция в PHP 8.3?

Посмотрите версии в начале страницы функции, затем сверьте используемые параметры с таблицей изменений. Если функция относится к расширению, проверьте, загружено ли оно в окружении приложения.

Какой раздел читать при переходе с PHP 8.3 на 8.5?

Откройте оба руководства по миграции, для переходов на 8.4 и на 8.5. Начните с несовместимых изменений, устаревших возможностей и изменений расширений, от которых зависит проект.

Можно ли открыть руководство PHP без интернета?

Да. Скачайте HTML-версию руководства, распакуйте её и откройте оглавление в браузере. По отдельной странице ищите браузером, по всему комплекту — поиском редактора по папке.

Справка по теме

Ещё в разделе «Архитектура и практика»

Эффективный рефакторинг PHP-кода

Практическое руководство по рефакторингу в PHP 8.3–8.5. Как зафиксировать поведение тестами, усилить типизацию, разделить обязанности и удалить мёртвый код.

7 мин

Декаплинг и фреймворки в PHP: как перестать зависеть от чужих обновлений

Как отделить бизнес-логику от фреймворка в современных PHP-проектах. Интерфейсы, DTO, адаптеры, DI-контейнеры и стратегии миграции без остановки разработки.

7 мин

Как задать вопрос по PHP, чтобы получить ответ

Как задать вопрос по PHP: соберите минимальный воспроизводимый пример, укажите версии и условия запуска, приложите текст ошибки и выберите площадку.

7 мин

Учимся по видеозаписям конференций PHP Frameworks Day: практический гид

Как системно учиться по записям выступлений с PHP-конференций: выбирать доклады, конспектировать код, внедрять практики в проект.

5 мин