Справочник PHP 8+

php.ini · OPcache

Запуск и настройка

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

Главная особенность модели PHP — shared nothing: ни один запрос не видит память предыдущего. Глобальные переменные, статические свойства, открытые соединения — всё создаётся заново и уничтожается в конце. Отсюда простота отладки и отсюда же цена: код компилируется на каждом запросе, если его не закэшировать.

PHP стартует в выбранном SAPI — php-fpm для веба, cli для консоли, встроенный сервер для разработки.
Читается php.ini, подключаются расширения, применяются настройки пула.
Входной файл разбирается и компилируется в опкоды — низкоуровневые инструкции Zend VM.
OPcache кладёт опкоды в общую память: со второго запроса шаг компиляции пропускается.
Опкоды выполняются; классы подтягиваются автозагрузчиком по мере первого обращения.
Вывод уходит клиенту, память освобождается, всё состояние процесса сбрасывается.

советJIT нужен не всем

JIT компилирует горячие опкоды в машинный код и заметно ускоряет вычисления: обработку изображений, математику, разбор данных. Типичное веб-приложение упирается не в процессор, а в базу и сеть, поэтому там выигрыш от JIT обычно в пределах шума, а от OPcache — кратный.

Консоль

php -v                    # версия и включённые SAPI-расширения
php -m                    # список загруженных расширений
php --ini                 # какие ini-файлы реально прочитаны
php -i | grep opcache     # что с кэшем опкодов
php -l file.php           # проверить синтаксис, ничего не выполняя
php -r 'echo PHP_INT_MAX;' # выполнить строку
php -a                    # интерактивная оболочка
php -S localhost:8000 -t public   # встроенный сервер: только для разработки

Настройки, которые приходится трогать чаще всего, и способы узнать, что происходит с окружением.

16 шт.

опции: PHP_VERSION_ID для сравнений

PHP_VERSION;        // '8.4.3'
PHP_VERSION_ID;     // 80403
PHP_OS_FAMILY;      // 'Linux'
PHP_SAPI;           // 'cli' | 'fpm-fcgi'
PHP_EOL; PHP_INT_MAX; PHP_FLOAT_EPSILON;

опции: error_get_last() внутри

register_shutdown_function(static function (): void {
    $e = error_get_last();
    if ($e !== null && $e['type'] === E_ERROR) {
        error_log('фатальная: ' . $e['message']);
    }
});

пример

opcache.enable / validate_timestamps

Кэш опкодов. На проде проверку времени файлов отключают: PHP перестаёт опрашивать диск на каждом запросе, а деплой сбрасывает кэш перезапуском.

опции: memory_consumption, max_accelerated_files

opcache.enable=1
opcache.validate_timestamps=0
opcache.memory_consumption=256
opcache.max_accelerated_files=20000

Разные настройки для разработки и прода

php.ini — продINI

display_errors = Off
log_errors = On
error_reporting = E_ALL
zend.assertions = -1

opcache.enable = 1
opcache.validate_timestamps = 0     ; сброс кэша — перезапуском FPM при деплое
opcache.memory_consumption = 256
opcache.max_accelerated_files = 20000
opcache.interned_strings_buffer = 16

php.ini — разработкаINI

display_errors = On
error_reporting = E_ALL
zend.assertions = 1

opcache.enable = 1
opcache.validate_timestamps = 1
opcache.revalidate_freq = 0         ; изменения видны сразу

граблиЗабытый opcache.validate_timestamps=0 после деплоя

С отключённой проверкой времени PHP не заметит, что файлы изменились: сайт продолжит работать на старом коде, пока не перезапустят FPM или не позовут opcache_reset(). Если деплой раскладывает файлы в тот же каталог — это классические «полчаса странного поведения» после выката.

Проверить, что окружение действительно такое, как думаете

bin/env-check.phpPHP

declare(strict_types=1);

$checks = [
    'версия' => version_compare(PHP_VERSION, '8.3', '>='),
    'opcache' => function_exists('opcache_get_status')
        && (opcache_get_status(false)['opcache_enabled'] ?? false),
    'кодировка' => ini_get('default_charset') === 'UTF-8',
    'ошибки не на экран' => ini_get('display_errors') === '' || !filter_var(
        ini_get('display_errors'), FILTER_VALIDATE_BOOL
    ),
    'расширения' => !array_diff(['mbstring', 'pdo_mysql', 'intl'], get_loaded_extensions()),
];

foreach ($checks as $name => $ok) {
    printf("%-22s %s\n", $name, $ok ? 'ок' : 'ПРОВЕРЬТЕ');
}

namespace · use

Пространства имён и автозагрузка

Имя класса — это путь к файлу, по которому его найдут в момент первого обращения. Вся схема держится на одном соглашении и одной функции.

Пространство имён — это префикс к именам, не более: он не создаёт области видимости для переменных и не влияет на выполнение. Зато по полному имени класса автозагрузчик вычисляет путь к файлу — и подключает его ровно тогда, когда класс впервые понадобился.

Не нашёлся файл или имя класса внутри не совпало с ожидаемым — будет «Class not found».

src/Mail/Sender.phpPHP

<?php

declare(strict_types=1);

namespace App\Mail;                    // одна на файл — и первой инструкцией после declare

use App\Config\Settings;               // импорт класса
use App\Mail\Transport\{Smtp, Sendmail};   // групповой импорт
use App\Support\Str as StrHelper;      // псевдоним
use function App\Support\slugify;      // импорт функции
use const App\Support\VERSION;         // импорт константы

final class Sender
{
    public function send(): void
    {
        $t = new Smtp();               // короткое имя — из-за use
        $x = new \DateTimeImmutable(); // обратный слеш: глобальное пространство
        strlen('...');                 // встроенные функции ищутся и в глобальном тоже
    }
}

граблиВнутри пространства имён \ обязателен для классов

В файле с namespace App; запись new DateTime() означает App\DateTime — и падает с «Class not found». Для функций правило мягче: если функции нет в текущем пространстве, PHP посмотрит в глобальном. Для классов такого запасного пути нет.

11 шт.

опции: бросать исключение из загрузчика не нужно

spl_autoload_register(static function (string $class): void {
    $prefix = 'App\\';
    if (!str_starts_with($class, $prefix)) {
        return;
    }
    $rel = substr($class, strlen($prefix));
    $file = __DIR__ . '/src/' . str_replace('\\', '/', $rel) . '.php';
    if (is_file($file)) {
        require $file;
    }
});

пример

namespace

Объявляется первой инструкцией файла (после declare). Фигурная форма с несколькими пространствами в одном файле существует, но в нормальном коде не встречается.

опции: один файл — одно пространство

<?php

declare(strict_types=1);

namespace App\Domain\Order;

Что делать с «Class not found»

Проверьте регистр: на macOS файл sender.php найдётся, на боевом Linux — нет.
Сверьте имя пространства внутри файла с путём: App\Mail\Sender → src/Mail/Sender.php при префиксе App\ → src/.
Убедитесь, что каталог вообще указан в autoload composer.json, а не только в autoload-dev.
После добавления новой секции автозагрузки выполните composer dump-autoload.
Если класс из пакета — проверьте, что пакет в require, а не только в require-dev.

Оптимизация автозагрузки на проде

Консоль

composer install --no-dev --optimize-autoloader   # таблица «класс → файл» вместо поиска
composer dump-autoload --classmap-authoritative   # неизвестный класс даже не ищем на диске

советИмя класса — это адрес файла

Единственная причина, по которой автозагрузка вообще работает, — соглашение. Как только в файле оказываются два класса, или имя файла не совпадает с именем класса, или пространство имён не соответствует каталогу, автозагрузчик перестаёт находить код. Отсюда правило «один класс — один файл», не связанное ни с какой эстетикой.

Throwable

Ошибки и исключения

В PHP 8 почти всё, что раньше было предупреждением, стало исключением. Ловить их принято точечно, а не одним catch на весь файл.

Всё, что можно бросить, реализует Throwable. Дальше развилка: Error — это ошибки самого языка (не тот тип, деление на ноль, нет метода), Exception — ошибки приложения. Ловить Error обычно не нужно: он означает, что код написан неверно.

Свой класс исключения наследуют от Exception или его потомков: реализовать Throwable напрямую язык не разрешает.

PHP

try {
    $order = $repo->find($id) ?? throw new NotFound("заказ $id");  // throw — выражение с 8.0
    $order->pay($amount);
} catch (NotFound | AccessDenied $e) {      // несколько типов одним блоком
    return $this->error(404, $e->getMessage());
} catch (PaymentFailed) {                   // без переменной, если она не нужна (8.0)
    return $this->error(402, 'платёж отклонён');
} catch (Throwable $e) {
    $this->log->error($e->getMessage(), ['exception' => $e]);
    throw $e;                               // не проглатываем: пробрасываем выше
} finally {
    $this->lock->release();                 // выполнится в любом случае
}

Предупреждения PHP — это не исключения

Обращение к несуществующему ключу, include пропавшего файла, деление на ноль через % — часть из этого по-прежнему диагностика движка, а не Throwable. Чтобы такие места тоже попадали в catch, их превращают в исключения обработчиком.

src/bootstrap.phpPHP

set_error_handler(static function (int $no, string $msg, string $file, int $line): bool {
    if (!(error_reporting() & $no)) {
        return false;          // уровень подавлен настройкой — пусть PHP разбирается сам
    }
    throw new ErrorException($msg, 0, $no, $file, $line);
});

set_exception_handler(static function (Throwable $e): void {
    error_log((string) $e);
    http_response_code(500);
    echo 'Что-то пошло не так';
});

граблиcatch (Throwable) на каждом шаге прячет ошибки

Перехват всего подряд превращает TypeError и опечатку в имени метода в «ошибку сервиса»: приложение продолжает работать со сломанными данными. Ловите то, что умеете обработать, а общий catch оставьте одному месту — на границе, где формируется ответ.

Слева — классы и конструкции. Из встроенных классов исключений в приложении обычно бросают четыре-пять; остальные полезно узнавать в чужих трассировках.

19 шт.

пример

Throwable

Общий интерфейс. Годится для объявления типов; свой класс должен наследовать Exception или Error, а не реализовывать интерфейс напрямую.

опции: getMessage, getCode, getFile, getLine, getPrevious, getTrace

function report(Throwable $e): void
{
    error_log($e::class . ': ' . $e->getMessage());
}

Своя иерархия исключений

src/Exception/PHP

// одно базовое на приложение — по нему ловят «всё наше»
interface AppException extends Throwable {}

// на домен — от LogicException или RuntimeException, по смыслу
class OrderException extends RuntimeException implements AppException {}

final class OrderNotFound extends OrderException
{
    public static function byId(int $id): self
    {
        return new self("заказ $id не найден");
    }
}

final class OrderAlreadyPaid extends OrderException {}

// на границе HTTP ловим свои и переводим в коды ответа
try {
    $this->handler->run($request);
} catch (OrderNotFound $e) {
    return new Response(404, $e->getMessage());
} catch (AppException $e) {
    return new Response(409, $e->getMessage());
}

советИсключение с именованным конструктором читается как предложение

throw OrderNotFound::byId($id) говорит и что случилось, и с чем. Заодно формулировка сообщения лежит в одном месте — и её можно поменять, не бегая по всему проекту.

Ресурсы освобождает finally, а не последняя строка

PHP

$fh = fopen($path, 'r');
try {
    foreach (readRows($fh) as $row) {
        if ($row['broken']) {
            return null;         // ранний выход — файл всё равно закроется
        }
    }
} finally {
    fclose($fh);
}

вниманиеСообщение исключения видит не только разработчик

Текст getMessage() часто оказывается в ответе API или на экране пользователя. Пути к файлам, SQL-запросы и содержимое переменных туда попадать не должны: детали — в лог через контекст, пользователю — что случилось и что делать.

get_debug_type()

Типы и приведение

Тип есть у значения, а не у переменной. Объявленный тип — это проверка на входе, и строгость этой проверки выбирает файл, из которого пришёл вызов.

В PHP тип принадлежит значению: переменная просто держит то, что в неё положили. Зато у параметров, свойств, возвращаемых значений и констант класса можно объявить тип — и тогда PHP проверяет значение на входе.

Что он сделает с неподходящим значением, решает не объявление, а файл, из которого сделан вызов: с declare(strict_types=1) в его первой строке несоответствие сразу даёт TypeError, без него PHP сначала попробует привести значение к нужному типу.

Объявление типа одно и то же — разойдутся только вызовы из файлов с разным режимом.

src/Price.phpPHP

<?php

declare(strict_types=1);   // первая строка файла, иначе фатальная ошибка

final class Price
{
    public function __construct(
        private readonly int $amount,       // тип свойства
        private readonly string $currency = 'RUB',
    ) {}

    public function withVat(float $rate): static   // тип аргумента и возврата
    {
        return new static((int) round($this->amount * (1 + $rate)), $this->currency);
    }
}

$p = new Price(1000);
$p->withVat(0.2);      // 1200
$p->withVat('0.2');    // TypeError: строка не float, режим строгий

Какие вообще бывают значения

null

единственное значение «ничего»; переменная без значения тоже null

bool

true / false; приведение к нему — самая частая причина неожиданностей

int

целое, 64 бита на обычной сборке; при переполнении молча становится float

float

число с плавающей точкой; 0.1 + 0.2 !== 0.3 — это не баг PHP, а IEEE 754

string

последовательность байтов, а не символов; длина в strlen() — в байтах

array

упорядоченная хэш-таблица: и список, и словарь одновременно

object

экземпляр класса; единственный тип, который передаётся по ссылке на объект

callable

то, что можно вызвать: имя функции, замыкание, [$obj, 'method']

iterable

array или Traversable — всё, что можно обойти в foreach

resource

открытый файл, соединение; в PHP 8 их массово заменили объектами

граблиЦелое переполнилось и стало дробным

PHP_INT_MAX + 1 не упадёт и не обрежется — результат станет float, потеряв точность. Для денег и идентификаторов это тихая порча данных: считайте в копейках или храните строкой.

что сделает объявленный тип

тип параметра

переданное значение

проверяемый вызов

Слева — то, что можно написать в объявлении типа. Версия у пункта означает, с какой версии PHP это объявление вообще принимается.

18 шт.

пример

int, float, string, bool

Скалярные типы. В обычном режиме PHP приведёт к ним что сможет, в строгом — только int дорастёт до float.

опции: проверяются на входе и на возврате

function ndigits(int $n): string
{
    return str_pad((string) $n, 4, '0', STR_PAD_LEFT);
}

Узнать тип значения

PHP

get_debug_type(1.0);          // 'float'   — так же пишется в объявлении типа
get_debug_type(new DateTime); // 'DateTime'
get_debug_type(null);         // 'null'
get_debug_type([]);           // 'array'

gettype(1.0);                 // 'double'  — историческое название, в объявление не вставить
gettype(new DateTime);        // 'object'  — какой именно класс, не скажет

// проверки по одному типу
is_int($v); is_float($v); is_string($v); is_bool($v);
is_array($v); is_object($v); is_callable($v); is_iterable($v);
is_numeric($v);               // число или строка, которую PHP считает числом
$v instanceof Countable;      // объект нужного класса или интерфейса

советget_debug_type() вместо gettype()

Появилась в 8.0 и возвращает ровно те названия, которые пишут в объявлениях типов: int, float, bool, null, имя класса. Поэтому её удобно подставлять в сообщения об ошибках: там будет float, а не загадочное double.

Приведение руками

PHP

(int) '42abc';     // 42     — читает, пока читается
(int) 'abc';        // 0
(int) 12.9;         // 12     — отбрасывает дробную часть, а не округляет
(int) true;         // 1
(bool) '0';         // false  — единственная непустая строка, которая ложна
(bool) '0.0';       // true
(bool) [];          // false
(string) 3.0;       // '3'
(array) $object;    // свойства в массив: приватные получат служебные ключи
(object) ['a' => 1];// stdClass с полем a

intdiv(7, 2);       // 3      — целочисленное деление без приведения
7 <=> 2;            // 1
round(2.5);         // 3.0    — половина от нуля
(int) round(2.5);   // 3

граблиСтрока «0» — единственная ложная непустая строка

Ложны: false, 0, 0.0, -0.0, '', '0', [], null. Строка '0.0', строка с пробелом и пустой объект — истинны. Поэтому if ($_GET['page']) теряет страницу «0», а if (count($rows)) честнее, чем if ($rows).

Нормализация входа на границе приложения

src/Http/Input.phpPHP

declare(strict_types=1);

final class Input
{
    /** Всё, что пришло по HTTP, — строки. Превращаем их в типы один раз и в одном месте. */
    public static function int(array $src, string $key, ?int $default = null): ?int
    {
        $raw = $src[$key] ?? null;
        if (!is_string($raw) || !preg_match('/^-?\d+$/', $raw)) {
            return $default;
        }
        return (int) $raw;   // приведение уже безопасно: формат проверен
    }
}

$page = Input::int($_GET, 'page', 1);

советstrict_types ставят во все файлы проекта

Режим действует на файл с вызовом, а не на файл с объявлением, поэтому «включить строгость проекту» нельзя одной настройкой — только строкой в каждом файле. Зато в строгом режиме f('5') падает там, где написана ошибка, а не тремя слоями ниже.

match · ?? · |>

Операторы и выражения

Сравнение, выбор ветки и короткие записи «если пусто». Здесь же главное изменение PHP 8: число и нечисловая строка больше не равны.

Два оператора сравнения делают разное. === проверяет тип и значение, == сначала приводит операнды к общему типу и только потом сравнивает. Правила приведения PHP 8 переписал: раньше число сравнивалось со строкой как число, теперь — наоборот.

Число со числовой строкой по-прежнему сравнивается как число: 0 == '0.0' — правда.

PHP

0 == 'abc';        // PHP 8: false, PHP 7: true
'1' == '01';       // true  — обе строки числовые, сравниваются как числа
'10' == '1e1';     // true  — то же самое
100 == '1e2';      // true
'abc' == 0;        // false
null == false;     // true
[] == false;       // true
'' == null;        // true

0 === '0';         // false — === не приводит вообще ничего
$a <=> $b;         // -1, 0 или 1: меньше, равно, больше

Выбор ветки: match вместо switch

PHP

$label = match (true) {
    $n < 0   => 'отрицательное',
    $n === 0 => 'ноль',
    default  => 'положительное',
};

// match: строгое сравнение (===), возвращает значение, без провала в следующую ветку,
// при непопадании и без default — UnhandledMatchError
$code = match ($status) {
    'new', 'draft' => 201,      // несколько условий на ветку
    'done'         => 200,
    default        => 400,
};

// switch: нестрогое сравнение (==), ничего не возвращает, без break падает дальше
switch ($status) {
    case 'new':
        $code = 201;
        break;
    default:
        $code = 400;
}

граблиswitch сравнивает нестрого

switch (0) войдёт в case 'abc' в PHP 7 и в case '' — в PHP 8. match этого не умеет по определению: он сравнивает через ===, поэтому ветка срабатывает только на точное совпадение типа и значения.

сравните два значения

слева

справа

Операторы по убыванию того, как часто их пишут. Приоритет здесь не указан: когда он неочевиден, скобки дешевле, чем таблица приоритетов в голове.

20 шт.

опции: подробнее — в узле «генераторы»

function lines(string $file): Generator {
    $fh = fopen($file, 'r');
    while (($l = fgets($fh)) !== false) {
        yield rtrim($l);
    }
}

пример

=== и !==

Строгое сравнение: сначала тип, потом значение. Для объектов — один и тот же экземпляр.

опции: единственное сравнение без сюрпризов

$a === $b;
$obj1 === $obj2;   // тот же объект, а не такой же

?? и ?: — разные вопросы

PHP

$_GET = ['page' => '0', 'q' => ''];

$_GET['page'] ?? 1;    // '0'  — ключ есть и не null
$_GET['page'] ?: 1;    // 1    — '0' ложно, и страница потерялась
$_GET['nope'] ?? 1;    // 1    — ключа нет, молча
$_GET['nope'] ?: 1;    // 1 + Warning: Undefined array key

// правило: ?? спрашивает «есть ли значение», ?: спрашивает «истинно ли оно»

match как таблица решений

src/Http/ErrorMapper.phpPHP

final class ErrorMapper
{
    public function status(Throwable $e): int
    {
        return match (true) {
            $e instanceof ValidationError => 422,
            $e instanceof NotFoundError   => 404,
            $e instanceof AccessDenied    => 403,
            $e instanceof RuntimeException => 500,
            default => 500,
        };
    }
}

советmatch (true) читается как список условий

Каждая ветка — самостоятельное условие, первое истинное выигрывает. Это та же лестница if / elseif, но без повторения переменной и с обязательным результатом: забыть ветку и получить null не выйдет.

Конвейер вместо матрёшки

PHP

// до 8.5: читается изнутри наружу, а пишется снаружи внутрь
$slug = str_replace(' ', '-', mb_strtolower(trim($title)));

// 8.5: тот же порядок, в котором думаешь
$slug = $title
    |> trim(...)
    |> mb_strtolower(...)
    |> fn(string $s): string => str_replace(' ', '-', $s);

вниманиеЕсли целевая версия ниже 8.5

Конвейер — синтаксис, а не функция: код с |> не запустится на 8.4 и ниже, и заменить его полифилом нельзя. Проверяйте минимальную версию в composer.json прежде, чем переписывать цепочки.

string

Строки

Строка в PHP — это последовательность байтов, а не символов. Отсюда две половины стандартной библиотеки: байтовая и та, что с приставкой mb_.

Строка хранит байты. Пока текст в ASCII, байт и символ совпадают, и разницы не видно. Как только появляется кириллица или эмодзи, strlen() начинает считать не то, а substr() — резать символ пополам. Для текста берут функции mb_*, которые знают про кодировку.

PHP

$s = 'Привет';

strlen($s);          // 12 — байтов
mb_strlen($s);       // 6  — символов
substr($s, 0, 3);    // "Пр" с половиной буквы: битый байт
mb_substr($s, 0, 3); // 'При'
strtoupper($s);      // 'Привет' — не сработало: функция знает только латиницу
mb_strtoupper($s);   // 'ПРИВЕТ'

// а ещё есть символы из нескольких кодовых точек
mb_strlen('👨‍👩‍👦');    // 5, а глазами — один

Четыре способа записать строку

PHP

$name = 'мир';
$user = ['name' => 'Аня'];

'Привет, $name';            // 'Привет, $name'  — одинарные кавычки ничего не подставляют
"Привет, $name";            // 'Привет, мир'
"Ключ: {$user['name']}";    // фигурные скобки нужны для выражений посложнее переменной
"Метод: {$obj->name()}";

$html = <<<HTML
    <p>Привет, $name</p>
    HTML;                   // heredoc: подстановка работает, отступ закрывающей метки срезается

$raw = <<<'TXT'
    $name останется текстом
    TXT;                    // nowdoc: как одинарные кавычки

советОтступ у heredoc можно не ломать

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

строка — это байты

строка

по байтам и по символам

Самое нужное из нескольких сотен строковых функций. Приставка mb_ означает «понимает кодировку»: для пользовательского текста берите её, для протоколов и двоичных данных — байтовую версию.

23 шт.

опции: третий аргумент — предел частей

explode(',', 'a,b,c');        // ['a','b','c']
explode(',', $csv, 2);         // хвост целиком во втором элементе
implode(', ', ['a', 'b']);

пример

str_contains()8.0

Есть ли подстрока. До 8.0 писали strpos($h, $n) !== false и регулярно забывали про !== false.

опции: регистрозависима

if (str_contains($email, '@')) { }

Сборка текста: sprintf вместо склейки

PHP

// склейка прячет структуру и ломается на переводе
$msg = 'Пользователь ' . $name . ' купил ' . $n . ' шт. на ' . number_format($sum, 2) . ' ₽';

// шаблон видно целиком, порядок аргументов можно поменять под язык
$msg = sprintf(
    'Пользователь %s купил %d шт. на %s ₽',
    $name,
    $n,
    number_format($sum, 2, ',', ' '),
);

Экранирование по месту вывода, а не по месту ввода

templates/comment.phpPHP

<!-- в HTML -->
<p><?= htmlspecialchars($comment) ?></p>

<!-- в атрибуте — то же самое, с 8.1 одинарные кавычки экранируются по умолчанию -->
<a title="<?= htmlspecialchars($title) ?>">…</a>

<!-- в JavaScript — не htmlspecialchars, а JSON -->
<script>const user = <?= json_encode($user, JSON_THROW_ON_ERROR | JSON_HEX_TAG) ?>;</script>

граблиЭкранирование «на входе» портит данные

Если htmlspecialchars() применяют к тексту перед сохранением в базу, то в базе лежит уже не текст пользователя, а HTML. Такое поле нельзя отдать в JSON, в письмо или в PDF без обратного преобразования — и рано или поздно кто-нибудь экранирует его второй раз.

Безопасное усечение длинного текста

PHP

function excerpt(string $text, int $limit = 140): string
{
    $text = trim(preg_replace('/\s+/u', ' ', strip_tags($text)));
    if (mb_strlen($text) <= $limit) {
        return $text;
    }
    // режем по символам, а не по байтам, и не посреди слова
    $cut = mb_substr($text, 0, $limit);
    $space = mb_strrpos($cut, ' ');
    return rtrim($space === false ? $cut : mb_substr($cut, 0, $space), " ,.;:") . '…';
}

советМодификатор u в регулярных выражениях

Без него preg_* работает с байтами: . съест один байт кириллической буквы, а \w не будет считать её буквой. Для текста флаг u обязателен — и он же требует, чтобы строка была корректным UTF-8.

array

Массивы

Один тип на все случаи: список, словарь, очередь и набор — это всё упорядоченная хэш-таблица с ключами int и string.

Массив PHP — упорядоченная хэш-таблица. Порядок вставки сохраняется всегда, ключом может быть только int или string, всё остальное приводится: 1.7 станет 1, true — 1, null — пустой строкой, а строка "7" — числом 7.

PHP

$a = [];
$a[1.7] = 'дробный';   // ключ 1
$a[true] = 'булев';    // ключ 1 — перезаписал предыдущий
$a['7'] = 'строка';    // ключ 7, целое
$a[null] = 'ничего';   // ключ ''

var_dump(array_keys($a));   // [1, 7, '']

// список — это массив с ключами 0,1,2… без пропусков
array_is_list([1, 2, 3]);        // true
array_is_list([1 => 'a']);       // false
array_is_list(['a', 'b' => 1]);  // false

Копирование и ссылки

Массив присваивается по значению, но копия делается лениво: пока никто не пишет, обе переменные смотрят в одни данные. Объект внутри массива при этом не копируется — копируется ссылка на него.

PHP

$a = [1, 2, 3];
$b = $a;         // копии ещё нет
$b[] = 4;        // вот теперь копия: $a остался [1, 2, 3]

$objects = [new ArrayObject([1])];
$copy = $objects;
$copy[0][] = 2;  // тот же объект: изменились оба массива

// ссылка в foreach переживает цикл — классические грабли
$rows = [1, 2, 3];
foreach ($rows as &$row) { $row *= 2; }
unset($row);     // без этого следующий foreach испортит последний элемент

граблиЗабытый unset($row) после foreach по ссылке

После цикла $row остаётся ссылкой на последний элемент. Следующий foreach ($rows as $row) будет на каждом шаге писать в него — и массив закончится дублем предпоследнего значения. Либо unset() сразу после цикла, либо не брать по ссылке вовсе: array_map() или новый массив.

Разбор массива на переменные

PHP

[$first, $second] = ['раз', 'два'];
['id' => $id, 'name' => $name] = $row;      // по ключам
[, $second] = $pair;                        // пропустить элемент
[[$a, $b], [$c, $d]] = $matrix;             // вложенно

foreach ($rows as ['id' => $id, 'sum' => $sum]) {
    // разбор прямо в заголовке цикла
}

// распаковка в другой массив; строковые ключи — с 8.1
$defaults = ['limit' => 10, 'offset' => 0];
$query = [...$defaults, 'limit' => 50];

Функции сгруппированы по задаче: сначала обход и преобразование, потом поиск, потом сортировка и структурные операции.

27 шт.

опции: для «значений по умолчанию» удобнее +

array_merge([1, 2], [3]);          // [1, 2, 3]
[1, 2] + [3, 4, 5];                // [1, 2, 5]
$options = $given + $defaults;

опции: чтение и запись ведут себя по-разному

$city = $data['user']['address']['city'] ?? null;
$tree['a']['b'][] = 1;   // уровни создадутся сами

пример

array_map()

Новый массив из результатов вызова. С одним массивом ключи сохраняются, с несколькими — нет. null вместо функции склеивает массивы по позициям.

опции: несколько массивов — параллельно

$names = array_map(fn(User $u) => $u->name, $users);
$pairs = array_map(null, $keys, $values);

Индексация вместо поиска в цикле

PHP

// было: O(n) поиск внутри O(n) цикла
foreach ($orders as $order) {
    foreach ($users as $user) {
        if ($user->id === $order->userId) { /* ... */ }
    }
}

// стало: один проход на индекс, дальше обращение по ключу
$byId = array_column($users, null, 'id');
foreach ($orders as $order) {
    $user = $byId[$order->userId] ?? null;
}

Массив как набор

PHP

// набор из ключей: проверка принадлежности — по хэшу, а не перебором
$allowed = array_flip(['create', 'update', 'delete']);

if (isset($allowed[$action])) { /* ... */ }

// пересечение по ключам — способ оставить только разрешённые поля
$clean = array_intersect_key($input, array_flip(['title', 'body']));

советСписок или словарь — решайте заранее

array_filter(), array_diff() и array_unique() сохраняют ключи, а json_encode() превращает массив с дырами в объект. Если результат должен уехать в JSON как массив — закрывайте цепочку array_values(), иначе фронтенд однажды получит {"1": …}.

Когда массив уже не нужен

PHP

// весь файл в памяти
$lines = file('big.csv');
$rows = array_map('str_getcsv', $lines);

// по строке за раз: память не растёт с размером файла
function rows(string $path): Generator
{
    $fh = fopen($path, 'r');
    try {
        while (($row = fgetcsv($fh)) !== false) {
            yield $row;
        }
    } finally {
        fclose($fh);
    }
}

вниманиеФункция получает копию, а объект — нет

Передача массива в функцию не копирует данные, пока функция их не меняет. Но если внутри что-то присваивается, копия создаётся целиком — на миллионе строк это заметно. Либо &$array, либо генератор, либо объект.

function

Функции и аргументы

Объявление, типы, значения по умолчанию и четыре способа передать аргумент — включая именованные, которые убирают из вызова ряды из true, null и false.

Объявление функции — это имя, список параметров и, по желанию, объявленные типы. Всё, что не передано и не имеет значения по умолчанию, — ошибка вызова: с PHP 8 ArgumentCountError, а не предупреждение.

PHP

declare(strict_types=1);

function paginate(
    array $rows,                 // обязательный
    int $page = 1,               // со значением по умолчанию
    int $perPage = 20,
    ?string $sort = null,        // ? обязателен: неявный nullable устарел в 8.4
): array {
    $offset = ($page - 1) * $perPage;
    return array_slice($rows, $offset, $perPage);
}

paginate($rows);                          // 2-й и далее — по умолчанию
paginate($rows, perPage: 50);             // именованный: пропустили $page
paginate($rows, sort: 'id', page: 2);     // порядок именованных не важен

Четыре способа передать аргументы

позиционно

по порядку; после именованного аргумента позиционных быть не может

именованно — с 8.0

perPage: 50; имя параметра становится частью публичного контракта

списком — `...$args`

в объявлении собирает остаток, в вызове раскладывает массив

по ссылке — `&$x`

функция меняет переменную вызывающего; в новом коде почти не нужен

граблиИмя параметра теперь тоже контракт

Как только кто-то вызвал вашу функцию с именованным аргументом, переименование параметра — ломающее изменение. В библиотеках это отдельная причина не переименовывать параметры в минорных версиях.

Возврат

PHP

class Repository
{
    public function find(int $id): ?User { }   // объект или null
    public function total(): int { }           // ровно int
    public function save(): void { }           // ничего: return; можно, а return null; — нет
    public function fail(string $m): never { } // не вернётся: бросит или завершит
    public function copy(): static { }         // объект того класса, у которого вызвали
}

// несколько значений — массивом или объектом; список разбирается на месте
[$ok, $error] = validate($input);

13 шт.

опции: для чистых функций и with-методов

class Order
{
    #[\NoDiscard]
    public function withStatus(string $s): static {}
}

// $order->withStatus('paid');  →  Warning: результат потерян

пример

Именованные аргументы8.0

Аргумент по имени параметра. Убирает из вызова цепочки null, null, true и делает читаемым вызов с флагами.

опции: после них позиционных быть не может

json_encode($data, flags: JSON_PRETTY_PRINT);
setcookie('t', $v, httponly: true, samesite: 'Lax');

Флаги в вызове читаются только с именами

PHP

// что делают эти true и null — по вызову не понять
$pdf = render($html, true, null, false, 'A4');

// то же самое, но читается без документации
$pdf = render($html, landscape: true, format: 'A4');

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

src/Report/Params.phpPHP

// шесть параметров, половина необязательных — признак того, что это объект
final class ReportParams
{
    public function __construct(
        public readonly DateTimeImmutable $from,
        public readonly DateTimeImmutable $to,
        public readonly string $currency = 'RUB',
        public readonly bool $withTax = true,
    ) {}
}

function report(ReportParams $params): Report { /* ... */ }

report(new ReportParams(from: $from, to: $to, withTax: false));

советРанний выход вместо лестницы условий

Проверки в начале функции с немедленным return или throw держат основной путь на нулевом уровне вложенности. Сравните: три вложенных if против трёх охранных условий — вторые читаются сверху вниз и не заканчиваются частоколом закрывающих скобок.

PHP

function publish(Post $post, User $user): void
{
    if (!$user->can('publish')) {
        throw new AccessDenied();
    }
    if ($post->isPublished()) {
        return;                       // уже сделано — не ошибка
    }

    $post->publish();                 // основной путь: без вложенности
}

Closure

Замыкания

Функция как значение: объект класса Closure, который можно передать, сохранить и привязать к другому объекту.

Замыкание — это объект класса Closure. Оно помнит область видимости, в которой создано: обычная форма берёт переменные списком use, стрелочная — сама, по значению, и только те, что реально упомянуты в теле.

PHP

$rate = 0.2;

// обычное: что захватить — пишем явно
$withVat = function (int $sum) use ($rate): int {
    return (int) round($sum * (1 + $rate));
};

// стрелочное: захватывает само, по значению, тело — одно выражение
$withVat = fn(int $sum): int => (int) round($sum * (1 + $rate));

// по ссылке: изменения видны снаружи
$total = 0;
$add = function (int $n) use (&$total): void { $total += $n; };
$add(5);   // $total === 5

Замыкание и $this

PHP

class Cart
{
    private array $items = [];

    public function totals(): array
    {
        // замыкание внутри метода видит $this автоматически
        return array_map(fn(Item $i) => $i->price * $i->qty, $this->items);
    }
}

// static-замыкание отказывается от $this: его нельзя привязать к объекту
$pure = static fn(int $a, int $b): int => $a + $b;

граблиСтрелочная функция захватывает значение, а не переменную

$fn = fn() => $i; внутри цикла запомнит текущее значение $i — и это обычно то, что нужно. Но если переменная меняется позже, замыкание об этом не узнает: для связи по ссылке нужна обычная форма с use (&$i).

11 шт.

опции: объект проходит как callable

final class Slugify
{
    public function __invoke(string $s): string
    {
        return mb_strtolower(trim($s));
    }
}

array_map(new Slugify(), $titles);

пример

function () use ()

Полная форма: тело из нескольких инструкций, захват списком. Захват по значению копирует переменную в момент создания замыкания.

опции: use (&$x) — по ссылке

$log = function (string $line) use ($file): void {
    file_put_contents($file, $line, FILE_APPEND);
};

Колбэк с состоянием вместо глобальной переменной

PHP

function counter(int $start = 0): Closure
{
    $n = $start;
    // захват по ссылке делает переменную состоянием замыкания
    return function () use (&$n): int {
        return $n++;
    };
}

$next = counter();
$next();   // 0
$next();   // 1

Мемоизация дорогого вызова

src/Support/memoize.phpPHP

function memoize(callable $fn): Closure
{
    $cache = [];
    return function (...$args) use ($fn, &$cache) {
        $key = serialize($args);
        return $cache[$key] ??= $fn(...$args);
    };
}

$rates = memoize($api->rate(...));
$rates('USD');   // запрос
$rates('USD');   // из кэша

вниманиеЗамыкание нельзя сериализовать

serialize() на объекте, у которого в свойстве лежит Closure, бросит исключение. Это всплывает там, где объекты кладут в кэш или в очередь: вместо замыкания в таких местах держат имя класса-обработчика или __invoke-объект.

Приватное — наружу, когда очень надо

PHP

// в тестах иногда нужно заглянуть внутрь объекта без geттера
$read = function (string $prop) { return $this->$prop; };
$value = Closure::bind($read, $object, $object::class)('secret');

Generator

Генераторы

Функция, которая отдаёт значения по одному и останавливается между ними. Миллион строк проходит через память по одной, а не целиком.

Одно yield в теле превращает функцию в генератор: при вызове тело не выполняется, а возвращается объект Generator. Тело двигается только тогда, когда у генератора просят следующее значение, и замирает ровно на yield — со всеми локальными переменными.

Генератор не ускоряет обработку — он снимает потолок по памяти.

PHP

function rows(string $path): Generator
{
    $fh = fopen($path, 'r');
    try {
        while (($row = fgetcsv($fh)) !== false) {
            yield $row;                 // здесь функция замирает до следующего шага
        }
    } finally {
        fclose($fh);                    // finally отработает и при выходе из foreach через break
    }
}

foreach (rows('orders.csv') as $i => $row) {
    // $i — ключ: по умолчанию счётчик с нуля
}

Ключи, возврат и двусторонняя связь

PHP

function pairs(): Generator
{
    yield 'id' => 1;          // свой ключ
    $answer = yield 'q' => 2; // yield как выражение: получает то, что передали в send()
    return 'итог';            // доступно после обхода
}

$gen = pairs();
$gen->current();     // 2 — нет, сначала первое значение
$gen->send('ответ'); // продолжает с места yield, возвращает следующее значение
$gen->getReturn();   // 'итог' — только когда генератор дошёл до конца

граблиГенератор нельзя перемотать и пройти дважды

foreach по одному генератору второй раз бросит Exception: Cannot rewind a generator that was already run. Если результат нужен дважды — либо вызывайте функцию-генератор заново, либо соберите её в массив через iterator_to_array(), приняв расход памяти сознательно.

11 шт.

опции: возврат вложенного доступен как значение выражения

function tree(array $nodes): Generator
{
    foreach ($nodes as $node) {
        yield $node;
        yield from tree($node->children);
    }
}

пример

yield $value

Отдать значение и замереть. Ключ по умолчанию — счётчик с нуля, как в списке.

опции: yield без значения отдаёт null

function ids(): Generator
{
    foreach ($this->rows as $row) {
        yield $row['id'];
    }
}

Конвейер из генераторов

src/Import/pipeline.phpPHP

function read(string $path): Generator
{
    $fh = fopen($path, 'r');
    try {
        while (($row = fgetcsv($fh)) !== false) {
            yield $row;
        }
    } finally {
        fclose($fh);
    }
}

function onlyPaid(iterable $rows): Generator
{
    foreach ($rows as $row) {
        if ($row[3] === 'paid') {
            yield $row;
        }
    }
}

function batch(iterable $rows, int $size): Generator
{
    $chunk = [];
    foreach ($rows as $row) {
        $chunk[] = $row;
        if (count($chunk) === $size) {
            yield $chunk;
            $chunk = [];
        }
    }
    if ($chunk !== []) {
        yield $chunk;             // хвост
    }
}

// файл любого размера проходит через постоянную память
foreach (batch(onlyPaid(read('orders.csv')), 500) as $chunk) {
    $db->insertMany($chunk);
}

граблиyield from не перенумеровывает ключи

Вложенный генератор отдаёт свои ключи — и они спокойно совпадут с ключами внешнего. В foreach это незаметно, а вот iterator_to_array($gen) молча потеряет элементы с одинаковыми ключами: из четырёх значений останется два. Лечится вторым аргументом false.

советВозвращайте iterable, а принимайте тоже iterable

Функция, объявленная с iterable, одинаково принимает массив и генератор — и вызывающий код решает, что ему важнее: простота или память. Это позволяет перевести обработку на генераторы позже, не переписывая сигнатуры.

Fiber

Файберы

Кусок кода, который можно остановить на любой глубине вызовов и продолжить позже. Фундамент асинхронных библиотек, а не инструмент прикладного кода.

Файбер — это отдельный стек вызовов, которым управляют руками. Запустили, внутри дошли до Fiber::suspend() — выполнение вернулось туда, откуда запускали, вместе с переданным значением. Потом resume() — и файбер продолжил с той же строки.

Отличие от генератора одно, но решающее: генератор умеет останавливаться только в своём теле, а файбер — на любой глубине вложенных вызовов. Поэтому на файберах строят асинхронные библиотеки: код внутри выглядит обычным, синхронным, а ждёт он неблокирующе.

PHP

$fiber = new Fiber(function (string $task): string {
    $answer = Fiber::suspend($task . ': жду ответа');   // отдали управление наружу
    return $answer . ': готово';                        // продолжили после resume()
});

$question = $fiber->start('запрос');   // 'запрос: жду ответа'
$fiber->resume('ответ');               // вернёт null: файбер дошёл до конца
$fiber->getReturn();                   // 'ответ: готово'
$fiber->isTerminated();                // true

вниманиеФайбер — это не параллелизм

В один момент времени работает ровно один файбер: PHP по-прежнему однопоточен. Файберы переключаются только там, где кто-то явно вызвал suspend(), — это кооперативная многозадачность, а не потоки и не процессы.

граблиFiber::suspend() вне файбера — ошибка

Вызов снаружи бросает FiberError: Cannot suspend outside of a fiber. Поэтому библиотеки вроде Amp и ReactPHP прячут файберы внутри своего планировщика: прикладной код зовёт их await, а не Fiber::suspend() напрямую.

9 шт.

пример

new Fiber(callable $callback)8.1

Создаёт файбер, но не запускает его. В колбэк уйдут аргументы start().

опции: создание ничего не выполняет

$fiber = new Fiber(function (int $id) {
    // тело выполнится только после start()
});

Планировщик в двадцать строк

src/Async/scheduler.phpPHP

/** Крутит файберы по очереди, пока все не закончатся. */
function run(callable ...$tasks): array
{
    $fibers = array_map(static fn(callable $t) => new Fiber($t), $tasks);
    $results = [];

    foreach ($fibers as $i => $fiber) {
        $fiber->start();
    }
    while ($fibers !== []) {
        foreach ($fibers as $i => $fiber) {
            if ($fiber->isTerminated()) {
                $results[$i] = $fiber->getReturn();
                unset($fibers[$i]);
                continue;
            }
            $fiber->resume();       // здесь настоящая библиотека ждала бы готовности сокета
        }
    }
    ksort($results);
    return $results;
}

run(
    function () { Fiber::suspend(); return 'первая'; },
    function () { Fiber::suspend(); return 'вторая'; },
);

советВ прикладном коде файберы почти не пишут руками

Их место — внутри Amp, ReactPHP, Swoole и очередей задач. Оттуда они выглядят как обычные вызовы: $response = $client->request($url) не блокирует процесс, потому что под капотом стоит Fiber::suspend(). Знать про файберы полезно, чтобы понимать, почему такой код вообще работает.

вниманиеОбщее состояние остаётся общим

Файберы делят память процесса: статические свойства, контейнер, открытые соединения. Переключение происходит только на suspend(), так что гонок в привычном смысле нет, но состояние, оставленное посреди операции, увидят все остальные файберы.

class

Классы и объекты

Объявление, конструктор в одну строку, наследование и позднее статическое связывание — всё, из чего собирают объекты в PHP 8.

Класс описывает свойства и методы, объект — их экземпляр. С PHP 8.0 конструктор умеет объявлять свойства прямо в параметрах: одна строка вместо трёх — объявления, параметра и присваивания.

src/Order.phpPHP

declare(strict_types=1);

final class Order                       // final: наследовать нельзя
{
    public const string STATUS_NEW = 'new';   // типизированная константа — с 8.3

    private array $items = [];

    public function __construct(
        public readonly int $id,              // продвижение: свойство + параметр сразу
        private Clock $clock = new SystemClock(),   // new в умолчании — с 8.1
    ) {}

    public static function draft(int $id): self   // именованный конструктор
    {
        return new self($id);
    }

    public function add(Item $item): static       // static: наследник вернёт себя
    {
        $this->items[] = $item;
        return $this;
    }
}

$order = Order::draft(7)->add($item);
$order::class;          // 'Order' — с 8.0 работает и на объекте
$order instanceof Order;

Наследование и позднее связывание

PHP

abstract class Model
{
    public static function create(): static   // static — «класс, у которого вызвали»
    {
        return new static();                  // позднее статическое связывание
    }

    public static function table(): string
    {
        return static::TABLE;                 // возьмёт константу наследника
    }

    abstract public function rules(): array;  // наследник обязан реализовать
}

final class User extends Model
{
    public const TABLE = 'users';

    public function rules(): array
    {
        return [];
    }
}

User::create();   // User, а не Model — из-за static вместо self

граблиself и static — не синонимы

self — это класс, в котором написана строка, static — класс, у которого вызвали метод. Фабрика с new self() в базовом классе всегда вернёт базовый класс, сколько бы наследников ни было. Это ломается тихо: тесты на базовом классе проходят.

Объект без имени

PHP

$logger = new class implements LoggerInterface {
    public function log(string $line): void
    {
        error_log($line);
    }
};

// анонимный класс с аргументами конструктора и родителем
$stub = new class($clock) extends BaseRepo {
    public function find(int $id): ?User { return null; }
};

14 шт.

опции: обращение через self:: или static::

final class Registry
{
    private static array $items = [];

    public static function put(string $k, mixed $v): void
    {
        self::$items[$k] = $v;
    }
}

опции: каждый вызов — новый класс

$clock = new readonly class implements Clock {
    public function now(): DateTimeImmutable
    {
        return new DateTimeImmutable('2024-01-01');
    }
};

опции: newLazyGhost, newLazyProxy

$r = new ReflectionClass(Heavy::class);
$obj = $r->newLazyGhost(function (Heavy $o): void {
    $o->__construct($deps);   // вызовется при первом обращении
});

опции: spl_object_id — идентификатор экземпляра

$a == $b;    // тот же класс и равные свойства
$a === $b;   // тот же объект

public function __clone(): void
{
    $this->createdAt = clone $this->createdAt;
}

пример

Продвижение свойств конструктора8.0

Модификатор видимости у параметра конструктора объявляет свойство и присваивает его. Работает вместе с readonly и объявленными типами.

опции: нельзя для callable и var

public function __construct(
    private readonly Mailer $mailer,
    private int $retries = 3,
) {}

Именованные конструкторы вместо флагов

PHP

final class Money
{
    private function __construct(
        public readonly int $amount,       // в копейках: float для денег не годится
        public readonly string $currency,
    ) {}

    public static function fromRubles(float $rub): self
    {
        return new self((int) round($rub * 100), 'RUB');
    }

    public static function zero(string $currency = 'RUB'): self
    {
        return new self(0, $currency);
    }
}

Money::fromRubles(199.90);

советЗакрытый конструктор + статические фабрики

Приватный __construct() заставляет создавать объект через методы с именами: Money::fromRubles(), Money::zero(). Каждый путь создания виден в списке методов, а не прячется в наборе необязательных аргументов.

Неизменяемый объект с with-методами

PHP

final readonly class Query
{
    public function __construct(
        public string $table,
        public int $limit = 20,
        public array $where = [],
    ) {}

    public function withLimit(int $limit): self
    {
        return new self($this->table, $limit, $this->where);
    }
}

$q = new Query('users')->withLimit(100);   // цепочка без скобок — с 8.4

вниманиеНаследование — не способ переиспользовать код

Если у наследника «почти то же самое, только другой способ сохранения», это композиция: передайте объект, который умеет сохранять. Наследование оправдано там, где наследник действительно является родителем и его можно подставить в любой код, ожидающий базовый тип.

readonly · hooks

Свойства

Типизированные, неизменяемые, с раздельной видимостью на чтение и запись и с перехватом чтения и записи — свойство в PHP 8.4 умеет почти всё, что раньше делали геттеры.

У свойства есть тип, видимость и — с 8.4 — хуки: код, который выполняется при чтении и записи. Снаружи это по-прежнему обычное свойство: $user->email = $v вместо $user->setEmail($v), но с проверкой внутри.

src/User.phpPHP

declare(strict_types=1);

class User
{
    // вычисляемое свойство: хранилища нет, есть только чтение
    public string $fullName {
        get => trim($this->first . ' ' . $this->last);
    }

    // обычное свойство с проверкой на записи
    public string $email {
        set (string $value) {
            $value = mb_strtolower(trim($value));
            if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
                throw new InvalidArgumentException('не похоже на адрес почты');
            }
            $this->email = $value;     // запись в само свойство, рекурсии нет
        }
    }

    // читают все, пишет только класс — с 8.4
    public private(set) int $version = 1;

    public function __construct(
        public string $first,
        public string $last,
        string $email,
    ) {
        $this->email = $email;         // сеттер отработает и здесь
    }
}

$u = new User('Иван', 'Петров', '  IVAN@Example.COM ');
$u->fullName;   // 'Иван Петров'
$u->email;      // 'ivan@example.com'
$u->version = 5; // Error: Cannot modify private(set) property User::$version

Три состояния типизированного свойства

не инициализировано

тип есть, значения нет; чтение — Error: must not be accessed before initialization

со значением

обычная работа; тип проверяется при каждой записи

readonly — после записи

первая запись из класса разрешена, вторая — Error, даже из самого класса

граблиreadonly — не «константа объекта»

Ограничение только на переприсваивание свойства. Если в readonly-свойстве лежит массив, его нельзя изменить целиком, но объект внутри свойства менять можно сколько угодно: $this->logger->push(...) работает. Неизменяемость вглубь язык не обеспечивает.

13 шт.

пример

Тип свойства

Проверяется при каждой записи. Свойство с типом и без значения по умолчанию не инициализировано — это не null.

опции: кроме callable

class Post
{
    public string $title;      // не инициализировано
    public ?User $author = null;
    public array $tags = [];
}

Хуки вместо пары геттер-сеттер

PHP

// было: два метода и приватное поле
class Temperature
{
    private float $celsius = 0.0;

    public function getFahrenheit(): float { return $this->celsius * 9 / 5 + 32; }
    public function setFahrenheit(float $f): void { $this->celsius = ($f - 32) * 5 / 9; }
}

// стало: одно свойство, которого физически нет
class Temperature
{
    public float $celsius = 0.0;

    public float $fahrenheit {
        get => $this->celsius * 9 / 5 + 32;
        set (float $f) { $this->celsius = ($f - 32) * 5 / 9; }
    }
}

советХуки — способ не ломать публичный интерфейс

Свойство, которое уже используют как $obj->title, можно превратить в вычисляемое или добавить к нему проверку, не меняя ни одной строки в вызывающем коде. До 8.4 ради такой возможности заранее прятали всё за геттеры — теперь это не нужно.

граблиХук set пишет в само свойство, а не в другое

Внутри set присваивание $this->email = $value не вызывает хук заново — оно пишет в хранилище свойства. А вот обращение к другому свойству с хуком сработает как обычно, со всеми его проверками.

Неизменяемость без километра конструктора

PHP

final readonly class Filter
{
    public function __construct(
        public ?string $query = null,
        public ?int $categoryId = null,
        public int $page = 1,
    ) {}

    // до 8.5: перечисляем все поля
    public function withPage(int $page): self
    {
        return new self($this->query, $this->categoryId, $page);
    }
}

interface

Интерфейсы

Договор без реализации: что объект умеет, не говоря ни слова о том, как. Половина возможностей языка — от foreach до json_encode — держится на встроенных интерфейсах.

Интерфейс перечисляет публичные методы, константы и — с 8.4 — свойства, которые обязан иметь класс. Класс реализует сколько угодно интерфейсов, и каждый из них становится его типом: по интерфейсу пишут объявления параметров, а значит, подменить реализацию можно не трогая вызывающий код.

src/Clock.phpPHP

declare(strict_types=1);

interface Clock
{
    public function now(): DateTimeImmutable;
}

final class SystemClock implements Clock
{
    public function now(): DateTimeImmutable
    {
        return new DateTimeImmutable();
    }
}

final class FrozenClock implements Clock
{
    public function __construct(private readonly DateTimeImmutable $at) {}

    public function now(): DateTimeImmutable
    {
        return $this->at;
    }
}

// код зависит от интерфейса — и поэтому тестируется без ожидания реального времени
final class Subscription
{
    public function __construct(private readonly Clock $clock) {}

    public function isExpired(DateTimeImmutable $until): bool
    {
        return $this->clock->now() > $until;
    }
}

Сужать можно, расширять нельзя

PHP

interface Repository
{
    public function find(int $id): ?Model;
}

final class UserRepository implements Repository
{
    // возврат сузили: ?User вместо ?Model — так можно (ковариантность)
    public function find(int $id): ?User
    {
        return null;
    }
}

// а вот потребовать от аргумента больше, чем интерфейс, нельзя:
// параметр можно только расширить (контравариантность)

советИнтерфейс описывает роль, а не класс

Хороший интерфейс называется по тому, что объект умеет: Clock, Mailer, PasswordHasher. Интерфейс UserServiceInterface с двадцатью методами, у которого одна реализация, — это не абстракция, а второй файл с тем же содержимым.

Встроенные интерфейсы, на которые опирается сам язык: реализуете — и объект начинает работать в foreach, count(), json_encode() и квадратных скобках.

14 шт.

опции: getIterator(): Traversable

final class Collection implements IteratorAggregate
{
    public function __construct(private array $items) {}

    public function getIterator(): Generator
    {
        yield from $this->items;
    }
}

опции: current, key, next, rewind, valid

class Cursor implements Iterator
{
    public function current(): mixed { }
    public function key(): mixed { }
    public function next(): void { }
    public function rewind(): void { }
    public function valid(): bool { }
}

опции: offsetGet, offsetSet, offsetExists, offsetUnset

final class Config implements ArrayAccess
{
    public function offsetGet(mixed $k): mixed
    {
        return $this->data[$k] ?? null;
    }
}

пример

Traversable

Корень всего, что проходится в foreach. Напрямую не реализуется — только через Iterator или IteratorAggregate.

опции: iterable = array|Traversable

function each(iterable $items): void
{
    foreach ($items as $item) { }
}

Коллекция, которая ведёт себя как массив

src/Collection.phpPHP

final class Items implements IteratorAggregate, Countable, JsonSerializable
{
    /** @param list<Item> $items */
    public function __construct(private readonly array $items = []) {}

    public function getIterator(): Generator
    {
        yield from $this->items;
    }

    public function count(): int
    {
        return count($this->items);
    }

    public function jsonSerialize(): array
    {
        return array_values($this->items);
    }

    public function filter(callable $fn): self
    {
        return new self(array_values(array_filter($this->items, $fn)));
    }
}

$paid = new Items($rows)->filter(fn(Item $i) => $i->isPaid());
count($paid);
foreach ($paid as $item) { }
json_encode($paid);

вниманиеArrayAccess ломает подсказки типов

Для $container['db'] ни IDE, ни анализатор не знают тип результата — там mixed. Поэтому современные контейнеры и конфиги дают типизированные методы (getString(), get(Db::class)), а скобки оставляют для совместимости.

trait

Трейты

Кусок класса, который можно вставить в несколько классов. Не наследование и не интерфейс: код копируется в класс на этапе компиляции.

Трейт вкладывается в класс так, будто его методы и свойства написаны прямо там. Отсюда все свойства трейтов: они видят $this, участвуют в разрешении конфликтов и не создают отдельного типа — по трейту нельзя объявить параметр.

PHP

trait Timestamps
{
    public ?DateTimeImmutable $createdAt = null;

    public const string FORMAT = 'Y-m-d H:i';   // константы в трейтах — с 8.2

    abstract public function clock(): Clock;    // требование к классу-хозяину

    public function touch(): void
    {
        $this->createdAt ??= $this->clock()->now();
    }
}

final class Post
{
    use Timestamps;

    public function __construct(private readonly Clock $clock) {}

    public function clock(): Clock
    {
        return $this->clock;
    }
}

Post::FORMAT;                  // константа пришла из трейта
$post instanceof Timestamps;   // ошибка: трейт — не тип

Конфликты имён

PHP

trait Json { public function render(): string { return '{}'; } }
trait Xml  { public function render(): string { return '<x/>'; } }

final class Report
{
    use Json, Xml {
        Json::render insteadof Xml;      // чей метод победит
        Xml::render as renderXml;        // второй доступен под другим именем
        renderXml as protected;          // заодно можно сменить видимость
    }
}

граблиСтатическое свойство трейта — своё у каждого класса

Трейт со static $count даст отдельный счётчик каждому использующему классу: это копия, а не общее хранилище. Ровно та же история со статическими переменными внутри методов трейта — общего состояния между классами не будет.

10 шт.

опции: лучше abstract-метод

trait NeedsDeps
{
    // вместо конструктора — требование к классу-хозяину
    abstract protected function deps(): Deps;
}

пример

use в классе

Вставляет трейт. Методы трейта проигрывают методам самого класса и выигрывают у унаследованных от родителя.

опции: несколько трейтов через запятую

final class User
{
    use Timestamps, SoftDelete;
}

Хороший трейт — мелкий и без состояния

PHP

// трейт на одну механику: сравнение value-объектов
trait ComparesByValue
{
    public function equals(self $other): bool
    {
        return $this == $other;   // == сравнит класс и свойства
    }
}

// трейт на «умеет превращаться в массив»
trait ArrayableFromPublic
{
    public function toArray(): array
    {
        return get_object_vars($this);
    }
}

вниманиеТрейт с десятью методами и своим состоянием — это класс

Если трейт завёл свойства, конструирует объекты и обращается к базе, из него получится обычная зависимость: объект, который передают в конструктор. Такую зависимость видно в сигнатуре, её можно подменить в тесте — с трейтом не выйдет ни того, ни другого.

советТрейт не заменяет интерфейс

По трейту нельзя объявить тип, поэтому пара «интерфейс + трейт с реализацией по умолчанию» — обычная связка: интерфейс объявляет контракт и годится в объявлениях типов, трейт избавляет реализации от копипасты.

enum

Перечисления

Тип с заранее известным набором значений. Заменяет строковые константы там, где «статус» может быть только одним из четырёх.

Перечисление объявляет все свои значения сразу, и других быть не может. Каждый вариант — объект-одиночка, поэтому сравнивать их можно через ===, а объявление типа Status $status гарантирует, что внутрь не попадёт опечатка.

src/Order/Status.phpPHP

declare(strict_types=1);

enum Status: string           // привязанное: у каждого варианта есть скалярное значение
{
    case New = 'new';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';

    public function label(): string        // у перечислений бывают методы
    {
        return match ($this) {
            self::New => 'новый',
            self::Paid => 'оплачен',
            self::Shipped => 'отправлен',
            self::Cancelled => 'отменён',
        };
    }

    public function isFinal(): bool
    {
        return in_array($this, [self::Shipped, self::Cancelled], true);
    }

    public static function default(): self
    {
        return self::New;
    }
}

Status::Paid->value;            // 'paid'  — то, что уходит в базу
Status::Paid->name;             // 'Paid'  — имя варианта
Status::from('paid');           // Status::Paid, иначе ValueError
Status::tryFrom('nope');        // null вместо исключения
Status::cases();                // все варианты списком

Два вида перечислений

чистое — `enum Status`

варианты без значений; хранить в базе напрямую нельзя, зато ничего лишнего

привязанное — `enum Status: string`

у каждого варианта есть value типа int или string: его и пишут в базу и JSON

`->name`

имя варианта, есть у обоих видов; менять его — ломающее изменение, как и имя класса

`->value`

только у привязанного; это и есть контракт с внешним миром

граблиВ перечислении не бывает состояния

Свойства объявлять нельзя: варианты — одиночки, и любое «состояние» стало бы глобальным. Если варианту нужны данные, их возвращает метод через match ($this) или они лежат в константе-таблице.

11 шт.

пример

enum без типа — чистое8.1

Набор именованных вариантов без значений. Подходит, когда наружу перечисление не уезжает: режимы, направления сортировки.

опции: реализует UnitEnum

enum Direction
{
    case Asc;
    case Desc;
}

Перечисление вместо набора констант

PHP

// было: значение — любая строка, опечатка всплывёт в продакшене
final class Order
{
    public const STATUS_NEW = 'new';
    public const STATUS_PAID = 'paid';

    public string $status = self::STATUS_NEW;
}

$order->status = 'payed';   // тишина

// стало: тип не пустит ничего постороннего
final class Order
{
    public Status $status = Status::New;
}

$order->status = 'payed';   // TypeError сразу

Переходы состояний внутри перечисления

PHP

enum Status: string
{
    case New = 'new';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';

    /** @return list<self> */
    public function allowedNext(): array
    {
        return match ($this) {
            self::New => [self::Paid, self::Cancelled],
            self::Paid => [self::Shipped, self::Cancelled],
            self::Shipped, self::Cancelled => [],
        };
    }

    public function canMoveTo(self $next): bool
    {
        return in_array($next, $this->allowedNext(), true);
    }
}

советmatch по перечислению не нуждается в default

Если ветки покрывают все варианты, default не нужен — и это плюс: добавив новый вариант, вы получите UnhandledMatchError в первом же тесте, а не тихо уедете в ветку по умолчанию. С default новая карта состояний молча сломается.

вниманиеЗначение привязанного перечисления — часть контракта

value уезжает в базу, в JSON и в чужие системы. Менять его нельзя так же, как нельзя менять название колонки: понадобится миграция данных. Имя варианта (name) — контракт для кода.

__get() · __call()

Магические методы

Методы с двумя подчёркиваниями, которые PHP вызывает сам: при обращении к несуществующему свойству, при печати объекта, при клонировании и сериализации.

Магический метод — это запасной путь. PHP зовёт его, только когда обычный не сработал: __get() — если свойства нет или оно недоступно, __call() — если метода нет. Отсюда две особенности: магия не мешает обычным свойствам и методам, и она невидима для IDE, анализаторов и автодополнения.

PHP

final class Bag
{
    private array $data = [];

    public function __get(string $name): mixed
    {
        return $this->data[$name] ?? null;
    }

    public function __set(string $name, mixed $value): void
    {
        $this->data[$name] = $value;
    }

    public function __isset(string $name): bool
    {
        return isset($this->data[$name]);   // без него isset($bag->x) всегда false
    }

    public function __unset(string $name): void
    {
        unset($this->data[$name]);
    }
}

$bag = new Bag();
$bag->title = 'Привет';   // __set
isset($bag->title);       // __isset — иначе false, даже когда значение есть
$bag->title;              // __get

граблиget() без isset() ломает isset() и ??

isset($obj->prop) и $obj->prop ?? 'default' не зовут __get() — они зовут __isset(). Класс, где объявлен только __get(), будет уверенно отвечать, что свойства нет, и ?? всегда подставит значение по умолчанию.

Цена магии

IDE и анализаторы

не знают, какие свойства есть; спасает только @property в PHPDoc

скорость

вызов метода вместо чтения поля; на горячем пути это заметно

ошибки

опечатка в имени не ошибка, а новое «свойство» со значением null

рефакторинг

переименование поля не находится поиском по коду

12 шт.

опции: вместо интерфейса Serializable

public function __serialize(): array
{
    return ['id' => $this->id];
}

public function __unserialize(array $data): void
{
    $this->id = $data['id'];
}

пример

construct() / destruct()

Создание и уничтожение. Деструктор вызывается, когда исчезла последняя ссылка, или при завершении скрипта — порядок в конце не гарантирован.

опции: исключение в __destruct фатально

public function __destruct()
{
    $this->flush();
}

Прокси с логированием на __call()

src/Support/LoggingProxy.phpPHP

final class LoggingProxy
{
    public function __construct(
        private readonly object $inner,
        private readonly Logger $log,
    ) {}

    public function __call(string $method, array $args): mixed
    {
        $started = hrtime(true);
        try {
            return $this->inner->$method(...$args);
        } finally {
            $this->log->debug(sprintf(
                '%s::%s — %.1f мс',
                $this->inner::class,
                $method,
                (hrtime(true) - $started) / 1e6,
            ));
        }
    }
}

советС 8.4 половина поводов для __get() исчезла

Вычисляемое свойство, проверка при записи, «только чтение снаружи» — всё это теперь делают хуки и асимметричная видимость. В отличие от магии они объявлены явно, типизированы и видны анализатору. Магию оставляют там, где набор свойств действительно неизвестен заранее: в обёртках над данными и в прокси.

вниманиеМагия и производительность

__get() — это полноценный вызов метода вместо чтения поля, а __call() ещё и собирает массив аргументов. На единичных обращениях разницы нет, но в цикле на сто тысяч итераций она становится главным пунктом профиля.

DateTimeImmutable

Дата и время

Один класс на всё: разбор, форматирование, арифметика и часовые пояса. Берите неизменяемую версию — изменяемая портит объекты, которые вы кому-то передали.

В PHP два почти одинаковых класса. DateTime меняет сам себя: $d->modify('+1 day') сдвигает объект, который вы, возможно, уже куда-то передали. DateTimeImmutable возвращает новый объект и ничего не портит — в новом коде используют только его.

PHP

$at = new DateTimeImmutable('2024-03-31 12:00', new DateTimeZone('Europe/Moscow'));

$at->format(DATE_ATOM);                    // '2024-03-31T12:00:00+03:00'
$at->setTimezone(new DateTimeZone('UTC')); // тот же момент в другом поясе: 09:00
$at->getTimestamp();                       // секунды с 1970 года

$tomorrow = $at->modify('+1 day');         // новый объект
$at->format('d.m');                        // 31.03 — исходный не изменился

$start = new DateTimeImmutable('2024-01-01');
$end   = new DateTimeImmutable('2024-03-01');
$diff  = $start->diff($end);               // DateInterval
$diff->days;                               // 60 — всего дней
$diff->m;                                  // 2  — «месяцев и дней», а не месяцев всего

$start < $end;                             // объекты дат сравниваются напрямую

Разбор строки

PHP

new DateTimeImmutable('2024-03-31');            // ISO — понимается всегда
new DateTimeImmutable('now');
new DateTimeImmutable('first day of next month');
new DateTimeImmutable('@1700000000');           // из метки времени, пояс UTC

DateTimeImmutable::createFromFormat('d.m.Y', '31.03.2024');   // свой формат
DateTimeImmutable::createFromFormat('!d.m.Y', '31.03.2024');  // ! обнуляет время
DateTimeImmutable::createFromTimestamp(1700000000.5);         // с 8.4, дробные секунды

// разбор может не удаться — проверять обязательно
$d = DateTimeImmutable::createFromFormat('!d.m.Y', $input);
if ($d === false) {
    throw new InvalidArgumentException('ожидался формат дд.мм.гггг');
}

граблиcreateFromFormat без «!» подставляет текущее время

Разбирая '31.03.2024' по формату 'd.m.Y', PHP возьмёт сегодняшние часы, минуты и секунды. Две такие даты никогда не окажутся равны, а сравнение «начало дня» будет работать через раз. Восклицательный знак в начале формата обнуляет всё, что в нём не указано.

грабли«+1 month» от 31 января — это 2 марта

PHP прибавляет месяц к номеру месяца, а потом нормализует несуществующую дату: 31 февраля превращается во 2 марта. Если нужен «последний день следующего месяца», так и пишут: modify('last day of next month').

16 шт.

опции: DATE_ATOM, DATE_RFC3339, DATE_COOKIE

$d->format('d.m.Y H:i');   // 31.03.2024 12:00
$d->format(DATE_ATOM);      // 2024-03-31T12:00:00+03:00
$d->format('u');            // микросекунды

пример

new DateTimeImmutable($time, $tz)

Разбирает строку в человеческом формате: ISO, now, +3 days, next monday, first day of next month.

опции: без пояса — date.timezone

new DateTimeImmutable('first day of next month midnight');

Часы как зависимость

src/Clock.phpPHP

interface Clock                                  // так же выглядит PSR-20
{
    public function now(): DateTimeImmutable;
}

final class SystemClock implements Clock
{
    public function __construct(private readonly DateTimeZone $tz = new DateTimeZone('UTC')) {}

    public function now(): DateTimeImmutable
    {
        return new DateTimeImmutable('now', $this->tz);
    }
}

final class FrozenClock implements Clock
{
    public function __construct(private DateTimeImmutable $at) {}

    public function now(): DateTimeImmutable
    {
        return $this->at;
    }
}

// в тесте «через 30 дней подписка истекла» больше не нужно ждать 30 дней

советХранить в UTC, показывать в поясе пользователя

В базе — момент времени в UTC, в интерфейсе — setTimezone() на пояс пользователя. Это избавляет от целого класса ошибок: переход на летнее время, переезд сервера, пользователи из разных стран и «час, который случился дважды».

Диапазон дат без дыр

PHP

$from = new DateTimeImmutable('2024-01-01');
$to   = new DateTimeImmutable('2024-01-08');

$byDay = [];
foreach (new DatePeriod($from, new DateInterval('P1D'), $to) as $day) {
    $byDay[$day->format('Y-m-d')] = 0;      // заготовка с нулями
}

foreach ($rowsFromDb as $row) {
    $byDay[$row['day']] = (int) $row['count'];   // дни без данных останутся нулями
}

вниманиеСравнивать даты строками можно только в ISO

'2024-03-31' < '2024-04-01' работает, потому что порядок символов совпадает с порядком дат. Стоит формату стать d.m.Y — и сравнение начинает врать. Сравнивайте объекты: у DateTimeImmutable операторы <, >, == делают ровно то, что нужно.

json_encode()

JSON и сериализация

Две функции с десятком флагов и одна привычка: всегда включать исключения, иначе ошибка разбора выглядит как «пришёл null».

json_encode() превращает значение в строку, json_decode() — обратно. Без флага JSON_THROW_ON_ERROR обе при ошибке возвращают false или null и оставляют код ошибки в глобальном состоянии — это главный источник молчаливых потерь данных.

PHP

$json = json_encode($data, JSON_THROW_ON_ERROR
    | JSON_UNESCAPED_UNICODE      // «привет», а не при...
    | JSON_UNESCAPED_SLASHES      // http://a/b вместо http:\/\/a\/b
    | JSON_PRETTY_PRINT);         // с отступами: для логов и файлов

$data = json_decode($json, associative: true, flags: JSON_THROW_ON_ERROR);

// без ассоциативного режима объекты становятся stdClass
$obj = json_decode('{"a":1}');        // $obj->a
$arr = json_decode('{"a":1}', true);  // $arr['a']

json_validate($json);                 // с 8.3: проверить, не разбирая

Что уедет в JSON от объекта

PHP

final class Order implements JsonSerializable
{
    public function __construct(
        public readonly int $id,
        private readonly string $secret,
        public readonly DateTimeImmutable $at,
    ) {}

    public function jsonSerialize(): array
    {
        return [
            'id' => $this->id,
            'at' => $this->at->format(DATE_ATOM),   // иначе выедет структура DateTime
        ];
    }
}

json_encode(new Order(1, 'токен', new DateTimeImmutable()));
// {"id":1,"at":"2024-03-31T12:00:00+03:00"} — приватное поле не попало

граблиПустой массив в JSON — это [], а не {}

PHP не различает список и словарь, а JSON различает. Массив [] закодируется как [], массив с дырами в ключах — как объект. Если API обещает объект, приводите явно: (object) $map или JSON_FORCE_OBJECT; если массив — закрывайте цепочку array_values().

16 шт.

пример

JSON_THROW_ON_ERROR

Бросать JsonException вместо возврата false/null. Ставьте всегда: без него ошибка разбора неотличима от значения null в данных.

опции: работает у обеих функций

json_decode($raw, true, flags: JSON_THROW_ON_ERROR);

Одна обёртка на весь проект

src/Support/Json.phpPHP

declare(strict_types=1);

final class Json
{
    private const int FLAGS = JSON_THROW_ON_ERROR
        | JSON_UNESCAPED_UNICODE
        | JSON_UNESCAPED_SLASHES
        | JSON_PRESERVE_ZERO_FRACTION;

    public static function encode(mixed $value, bool $pretty = false): string
    {
        return json_encode($value, self::FLAGS | ($pretty ? JSON_PRETTY_PRINT : 0));
    }

    /** @return array<string, mixed> */
    public static function decode(string $json): array
    {
        $data = json_decode($json, true, 512, JSON_THROW_ON_ERROR);
        if (!is_array($data)) {
            throw new JsonException('ожидался объект или массив');
        }
        return $data;
    }
}

советФлаги задаются один раз, а не в каждом вызове

Набор флагов — это решение уровня проекта: кодировка, экранирование, точность чисел. Когда он повторяется в тридцати местах, рано или поздно где-то забудут JSON_THROW_ON_ERROR — и получат null вместо данных без единого сообщения.

вниманиеunserialize() на данных пользователя — дыра

Разбор сериализованной строки создаёт объекты и вызывает их магические методы — этого достаточно для запуска чужого кода в вашем процессе. Для данных извне только JSON. Если формат PHP всё же нужен, обязателен второй аргумент ['allowed_classes' => false].

preg_match()

Регулярные выражения

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

Шаблон — это строка, внутри которой сам шаблон обёрнут разделителями, а после закрывающего разделителя идут модификаторы. Для текста на кириллице модификатор u обязателен: без него движок работает с байтами, и . съедает половину буквы.

PHP

//  /       шаблон        /  модификаторы
$re = '/^(?<year>\d{4})-(\d{2})$/u';

if (preg_match($re, '2024-03', $m)) {
    $m[0];        // '2024-03'  — всё совпадение
    $m[1];        // '2024'     — первая группа
    $m['year'];   // '2024'     — она же по имени
    $m[2];        // '03'
}

preg_match_all('/\d+/u', 'a1 b22 c333', $all);   // $all[0] === ['1', '22', '333']
preg_replace('/\s+/u', ' ', $text);              // схлопнуть пробелы
preg_split('/[\s,]+/u', $line);                  // разбить по пробелам и запятым
preg_quote($userInput, '/');                     // экранировать пользовательский ввод

Модификаторы, которые действительно нужны

u

UTF-8: шаблон и строка — символы, а не байты. Для текста обязателен

i

без учёта регистра; с u работает и для кириллицы

m

^ и $ совпадают с началом и концом каждой строки, а не всего текста

s

. начинает совпадать и с переводом строки

x

пробелы и переводы строк в шаблоне игнорируются — можно писать с отступами и комментариями

граблиБез модификатора u кириллица — это байты

preg_match('/^.{3}$/', 'абв') не совпадёт: в строке шесть байтов. А \w без u не считает кириллицу буквой. Добавили u — и строка обязана быть корректным UTF-8, иначе функция вернёт false, а preg_last_error_msg() скажет почему.

14 шт.

опции: предел частей — третий аргумент

preg_split('/\R/u', $text);   // по любым переводам строки
preg_split('//u', $s, -1, PREG_SPLIT_NO_EMPTY);   // на символы

пример

preg_match()

Одно совпадение. Возвращает 1, 0 или false — последнее означает ошибку шаблона, и проверять надо строго.

опции: PREG_OFFSET_CAPTURE, PREG_UNMATCHED_AS_NULL

if (preg_match('/^\d+$/', $s) === 1) { }

Длинный шаблон читается только с модификатором x

PHP

$re = '/
    ^
    (?<protocol>https?)  ://          # схема
    (?<host>[^\/:\s]+)                # хост
    (?: : (?<port>\d+) )?             # необязательный порт
    (?<path>\/[^\s?]*)?               # путь
    $
/xu';

preg_match($re, 'https://example.com:8443/api/v1', $m);
$m['host'];   // 'example.com'
$m['port'];   // '8443'

вниманиеКатастрофический возврат

Шаблоны вида (\w+\s?)+$ на длинной строке без совпадения заставляют движок перебирать экспоненциальное число вариантов: запрос висит, процессор занят. Лечится конкретикой вместо вложенных квантификаторов и ограничением длины входа до проверки шаблоном.

советПроверять HTML регулярным выражением не нужно

Для HTML есть DOMDocument и Dom\HTMLDocument (8.4), для CSV — fgetcsv(), для почты и URL — filter_var(), для JSON — json_decode(). Регулярное выражение хорошо там, где формат простой и строгий: номер телефона, код купона, строка лога.

fopen() · php://

Файлы и потоки

Файл, сетевое соединение, память и стандартный ввод — для PHP это один и тот же поток, который открывают одной функцией.

Всё, что читается и пишется, в PHP — поток. Путь при открытии может быть обычным файлом, адресом https://, псевдофайлом php://memory или чем-то, что зарегистрировала библиотека. Поэтому функции работы с файлами одинаково читают и локальный CSV, и тело HTTP-запроса.

PHP

// целиком — когда файл заведомо небольшой
$text = file_get_contents($path);
file_put_contents($path, $text, LOCK_EX);
file_put_contents($log, $line . PHP_EOL, FILE_APPEND | LOCK_EX);

// по частям — когда размер неизвестен
$fh = fopen($path, 'rb');
try {
    while (($line = fgets($fh)) !== false) {
        // ...
    }
} finally {
    fclose($fh);
}

// псевдопотоки
$body = file_get_contents('php://input');     // сырое тело запроса
$buffer = fopen('php://temp', 'r+');          // память, с переездом на диск после 2 МБ
$stdout = fopen('php://stdout', 'w');

Режимы открытия

'r' / 'r+'

чтение / чтение и запись; файл должен существовать, указатель в начале

'w' / 'w+'

запись; файл создаётся или обрезается до нуля

'a' / 'a+'

дозапись в конец; существующее содержимое остаётся

'x' / 'x+'

создать и писать; если файл уже есть — ошибка. Так делают файлы-замки

'c' / 'c+'

открыть или создать без обрезания; подходит для flock() перед записью

'b'

двоичный режим: добавляйте всегда, иначе Windows подменяет переводы строк

граблиРежим 'w' стирает файл в момент открытия

Не при записи, а именно при fopen(). Если дальше код упадёт с исключением, на диске останется пустой файл вместо прежних данных. Для безопасной перезаписи пишут во временный файл и затем переименовывают.

15 шт.

опции: таймаут и redirects

$ctx = stream_context_create(['http' => [
    'method' => 'POST',
    'header' => "Content-Type: application/json\r\n",
    'content' => $json,
    'timeout' => 5,
]]);
file_get_contents($url, false, $ctx);

опции: проверяйте результат

$tmp = $path . '.tmp';
file_put_contents($tmp, $data);
rename($tmp, $path);   // читатели видят либо старое, либо новое

опции: PATHINFO_EXTENSION

$ext = pathinfo($name, PATHINFO_EXTENSION);
$real = realpath($base . '/' . $user);
if ($real === false || !str_starts_with($real, $base)) {
    throw new RuntimeException('путь вне каталога');
}

опции: расширению доверять нельзя

$mime = (new finfo(FILEINFO_MIME_TYPE))->file($uploaded);
if (!in_array($mime, ['image/png', 'image/jpeg'], true)) {
    throw new RuntimeException('только png и jpeg');
}

пример

file_get_contents() / file_put_contents()

Весь файл одной строкой. Второе умеет дозапись и блокировку и возвращает число записанных байтов или false.

опции: FILE_APPEND, LOCK_EX

$n = file_put_contents($path, $data, LOCK_EX);
if ($n === false) {
    throw new RuntimeException("не записалось: $path");
}

Атомарная перезапись

src/Support/write_atomic.phpPHP

function writeAtomic(string $path, string $data): void
{
    $tmp = $path . '.' . bin2hex(random_bytes(4)) . '.tmp';

    $fh = fopen($tmp, 'wb');
    if ($fh === false) {
        throw new RuntimeException("не открылся временный файл: $tmp");
    }
    try {
        if (fwrite($fh, $data) === false) {
            throw new RuntimeException("не записалось: $tmp");
        }
        fsync($fh);                 // данные действительно на диске
    } finally {
        fclose($fh);
    }

    if (!rename($tmp, $path)) {     // переименование в пределах ФС атомарно
        unlink($tmp);
        throw new RuntimeException("не переименовался: $tmp");
    }
}

советЗагруженные файлы проверяют по содержимому

$_FILES['f']['type'] приходит от браузера и подделывается тривиально, расширение — тем более. Реальный тип даёт finfo, а сам файл берут через move_uploaded_file() — она проверяет, что файл действительно загружен, а не подсунут путём.

Построчная обработка большого файла

PHP

$in = new SplFileObject('orders.csv');
$in->setFlags(SplFileObject::READ_CSV | SplFileObject::SKIP_EMPTY | SplFileObject::DROP_NEW_LINE);

$out = new SplFileObject('report.csv', 'w');
foreach ($in as $row) {
    if ($row === [null] || $row === false) {
        continue;                  // хвостовая пустая строка
    }
    $out->fputcsv([$row[0], (int) $row[2] * 2]);
}

SplObjectStorage

SPL: структуры и итераторы

Набор готовых классов на случаи, где массив уже мешает: очередь, стек, куча, множество объектов и обход дерева каталогов.

Массив PHP умеет почти всё — и поэтому не говорит о намерении. SplQueue в коде заявляет «это очередь», SplObjectStorage — «множество объектов», WeakMap — «данные, которые исчезнут вместе с объектом». Плюс часть структур экономит память там, где массив её не жалеет.

PHP

// множество объектов: ключ — сам объект, а не строка
$seen = new SplObjectStorage();
$seen->attach($user);
$seen->contains($user);        // true
$seen[$user] = ['at' => time()];   // к объекту можно привязать данные
count($seen);

// слабая карта: запись исчезает, когда объект больше никому не нужен
$cache = new WeakMap();
$cache[$entity] = $heavyComputation;   // утечки памяти не будет

// очередь и стек с понятным названием
$queue = new SplQueue();
$queue->enqueue($job);
$job = $queue->dequeue();

// массив фиксированной длины: меньше памяти на больших объёмах
$points = new SplFixedArray(1_000_000);

советWeakMap — правильный кэш «по объекту»

Обычный массив с ключом spl_object_id($obj) держит запись вечно, даже когда объект давно не нужен, — и в долгоживущем процессе это утечка. WeakMap (с 8.0) удаляет запись автоматически, как только исчезла последняя ссылка на ключ.

15 шт.

опции: SKIP_DOTS обязателен

$it = new RecursiveIteratorIterator(
    new RecursiveDirectoryIterator($dir, FilesystemIterator::SKIP_DOTS)
);
foreach ($it as $file) {
    if ($file->getExtension() === 'php') { }
}

пример

ArrayObject / ArrayIterator

Массив, завёрнутый в объект: передаётся по ссылке на объект, реализует ArrayAccess, Countable и IteratorAggregate.

опции: ARRAY_AS_PROPS

$config = new ArrayObject(['db' => 'mysql'], ArrayObject::ARRAY_AS_PROPS);
$config['db'];
$config->db;

Обход проекта без рекурсии

bin/find-todo.phpPHP

$dir = new RecursiveDirectoryIterator(__DIR__ . '/../src', FilesystemIterator::SKIP_DOTS);
$files = new RecursiveIteratorIterator($dir);
$php = new CallbackFilterIterator(
    $files,
    static fn(SplFileInfo $f): bool => $f->isFile() && $f->getExtension() === 'php',
);

foreach ($php as $file) {
    foreach (new SplFileObject($file->getPathname()) as $n => $line) {
        if (is_string($line) && str_contains($line, 'TODO')) {
            printf("%s:%d %s\n", $file->getPathname(), $n + 1, trim($line));
        }
    }
}

вниманиеSPL-структуры не бесплатны

Каждый элемент SplDoublyLinkedList — объект со своими накладными расходами, и на небольших объёмах обычный массив и быстрее, и экономнее. Берите SPL ради смысла («это очередь», «это множество объектов») или ради конкретной возможности, которой у массива нет.

#[Attribute]

Атрибуты и рефлексия

Метаданные, которые пишутся в коде и читаются программой. То, ради чего раньше разбирали PHPDoc-комментарии регулярными выражениями.

Атрибут — это объявление, которое компилятор сохраняет рядом с элементом кода, но сам не выполняет. Прочитать его можно только рефлексией, и только там он превращается в объект своего класса.

src/Routing/Route.phpPHP

declare(strict_types=1);

#[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
final class Route
{
    public function __construct(
        public readonly string $path,
        public readonly string $method = 'GET',
    ) {}
}

final class OrderController
{
    #[Route('/orders', method: 'GET')]
    #[Route('/orders/list')]                 // повторяемый — можно несколько
    public function index(): Response { /* ... */ }
}

// читаем: без этого шага атрибут не делает ничего
$rc = new ReflectionClass(OrderController::class);
foreach ($rc->getMethods() as $method) {
    foreach ($method->getAttributes(Route::class) as $attr) {
        $route = $attr->newInstance();       // вот здесь создаётся объект Route
        $router->add($route->method, $route->path, [$rc->getName(), $method->getName()]);
    }
}

советАтрибут сам по себе ничего не делает

Ни валидация, ни маршрут, ни кэш не появятся оттого, что вы написали #[Route]. Работает код, который читает атрибуты рефлексией. Именно поэтому фреймворки кэшируют результат чтения: рефлексия на каждом запросе — заметная трата.

Куда можно ставить

TARGET_CLASS

классы, интерфейсы, трейты, перечисления

TARGET_METHOD / TARGET_FUNCTION

методы и функции

TARGET_PROPERTY / TARGET_PARAMETER

свойства и параметры — на них держится валидация и внедрение зависимостей

TARGET_CLASS_CONSTANT

константы класса; с 8.5 — и обычные константы

TARGET_ALL | IS_REPEATABLE

везде; и разрешить несколько одинаковых на одном элементе

Сначала атрибуты, встроенные в сам PHP, затем рефлексия — то, чем их читают.

14 шт.

опции: фильтр по имени и INSTANCEOF

foreach ($rp->getAttributes(Column::class, ReflectionAttribute::IS_INSTANCEOF) as $a) {
    $a->getName();
    $a->getArguments();
    $a->newInstance();
}

пример

#[Attribute]8.0

Помечает класс как атрибут и задаёт, куда его разрешено ставить. Без него класс использовать как атрибут нельзя.

опции: TARGET_*, IS_REPEATABLE

#[Attribute(Attribute::TARGET_PROPERTY)]
final class Column {}

Свой атрибут проверки — и то, что его читает

src/Validation/PHP

#[Attribute(Attribute::TARGET_PROPERTY)]
final class NotBlank
{
    public function __construct(public readonly string $message = 'не может быть пустым') {}
}

final class Form
{
    #[NotBlank]
    public string $title = '';

    #[NotBlank(message: 'укажите текст')]
    public string $body = '';
}

final class Validator
{
    /** @return array<string, string> ошибки по именам свойств */
    public function validate(object $object): array
    {
        $errors = [];
        foreach (new ReflectionClass($object)->getProperties() as $property) {
            foreach ($property->getAttributes(NotBlank::class) as $attribute) {
                $value = $property->getValue($object);
                if (trim((string) $value) === '') {
                    $errors[$property->getName()] = $attribute->newInstance()->message;
                }
            }
        }
        return $errors;
    }
}

вниманиеРефлексия дорога — кэшируйте результат

Разбор атрибутов у сотни классов на каждом запросе съедает больше, чем сама работа. Правило простое: рефлексия выполняется один раз, результат складывается в массив или файл (var_export() + require), а в рантайме читается уже он.

советАтрибуты не заменяют конфигурацию

Маршруты и правила валидации рядом с кодом читаются лучше. А вот настройки окружения, подключения и списки сервисов в атрибуты не помещаются: их меняют без правки кода. Обычно проект использует и то, и другое, и это нормально.

composer.json

Composer

Менеджер зависимостей, который заодно раздаёт автозагрузку. Два файла: чего мы хотим и что в итоге установилось.

composer.json описывает пожелания: какие пакеты нужны и в каких пределах версий. composer.lock фиксирует результат: конкретные версии с контрольными суммами. На сервере выполняется composer install, который ставит ровно то, что в lock-файле, и поэтому у всех одинаковый набор.

composer.jsonJSON

{
  "name": "acme/shop",
  "type": "project",
  "require": {
    "php": "^8.3",
    "psr/log": "^3.0",
    "ext-mbstring": "*"
  },
  "require-dev": {
    "phpunit/phpunit": "^11.0",
    "phpstan/phpstan": "^2.0"
  },
  "autoload": {
    "psr-4": { "App\\": "src/" },
    "files": ["src/Support/helpers.php"]
  },
  "autoload-dev": {
    "psr-4": { "App\\Tests\\": "tests/" }
  },
  "scripts": {
    "test": "phpunit",
    "stan": "phpstan analyse --memory-limit=512M",
    "check": ["@stan", "@test"]
  },
  "config": {
    "sort-packages": true,
    "platform": { "php": "8.3.0" }
  }
}

Ограничения версий

^3.2

от 3.2 до 4.0 — разрешает минорные и патчи. Обычный выбор для библиотек

~3.2

от 3.2 до 3.3 — только патчи. Строже, чем ^

~3.2.1

от 3.2.1 до 3.3 — тоже только патчи, но с точкой отсчёта

3.*

любая версия ветки 3

>=3.2 <4.0

явный диапазон; пишут, когда нужны нестандартные границы

dev-main

ветка вместо версии — только для своих пакетов и временных правок

граблиcomposer.lock нужно коммитить

Без него composer install на сервере и в CI поставит другие версии, чем у вас на машине: диапазон ^3.0 со временем начинает означать другое. Правило: composer.lock в репозитории, vendor/ — нет.

Команды, которые нужны каждый день, и поля файла, которые действительно настраивают.

14 шт.

пример

composer install

Ставит ровно то, что записано в composer.lock. Это команда для сервера, CI и коллеги, который только клонировал репозиторий.

опции: --no-dev --optimize-autoloader на проде

composer install --no-dev --optimize-autoloader --no-interaction

Одна команда на проверку всего

composer.jsonJSON

{
  "scripts": {
    "lint": "parallel-lint src tests",
    "cs": "php-cs-fixer fix --dry-run --diff",
    "stan": "phpstan analyse",
    "test": "phpunit",
    "check": ["@lint", "@cs", "@stan", "@test"]
  }
}

Консоль

composer check          # то же самое запускает и CI, и разработчик
composer install --no-dev --optimize-autoloader   # сборка для прода

советОбновляйтесь малыми шагами

composer update всего сразу превращает обновление в отдельный проект с непонятным сроком. Раз в пару недель composer outdated --direct, затем обновление одного-двух пакетов с прогоном тестов — и версия зависимостей никогда не становится проблемой.

вниманиеПакет — это чужой код в вашем процессе

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

psr/log · psr/http

PSR — общие интерфейсы

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

PSR — это рекомендации группы PHP-FIG. Часть из них про оформление кода, часть — готовые пакеты с интерфейсами: psr/log, psr/container, psr/http-message. Второе важнее первого: библиотека, которая принимает LoggerInterface, работает с любым логгером, а не только с тем, о котором знал автор.

PHP

use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;

final class PaymentService
{
    public function __construct(
        private readonly LoggerInterface $log = new NullLogger(),
    ) {}

    public function pay(Order $order): void
    {
        $this->log->info('оплата начата', ['order' => $order->id]);
    }
}

// в проекте сюда попадёт Monolog, в тесте — свой заглушечный логгер:
// классу всё равно, он знает только интерфейс

советИнтерфейс из пакета — это не зависимость от фреймворка

psr/log — три файла без единой строки реализации. Пакет, который принимает LoggerInterface, не тянет за собой Monolog и вообще ничего не навязывает. Именно поэтому такие интерфейсы стали общим языком экосистемы.

Принятые стандарты, которые встречаются в реальных проектах. Номера идут по времени принятия, поэтому соседние номера редко связаны по смыслу.

12 шт.

опции: MiddlewareInterface, RequestHandlerInterface

public function process(
    ServerRequestInterface $request,
    RequestHandlerInterface $handler,
): ResponseInterface {
    return $handler->handle($request)->withHeader('X-Time', (string) time());
}

пример

PSR-1 и PSR-12 — стиль кода

Базовые правила и подробный стиль оформления: отступы, переносы, порядок модификаторов. Проверяются и исправляются автоматически.

опции: php-cs-fixer, PHP_CodeSniffer

vendor/bin/php-cs-fixer fix --rules=@PSR12

Зависимость от интерфейса, а не от библиотеки

PHP

// было: класс намертво связан с конкретным логгером и клиентом
final class Notifier
{
    public function send(string $to): void
    {
        (new Monolog\Logger('app'))->info('шлём ' . $to);
        (new GuzzleHttp\Client())->post('https://api.example.com/send');
    }
}

// стало: подменяется в тесте, не тянет лишнего в composer.json
final class Notifier
{
    public function __construct(
        private readonly ClientInterface $http,          // PSR-18
        private readonly RequestFactoryInterface $requests, // PSR-17
        private readonly LoggerInterface $log = new NullLogger(), // PSR-3
    ) {}
}

вниманиеPSR — не всегда лучший выбор

PSR-7 с его неизменяемыми объектами многословен, PSR-6 сложнее, чем нужно половине проектов. Смысл стандартов — в совместимости: они нужны там, где код должен подойти чужому приложению. Во внутреннем сервисе свой маленький интерфейс часто честнее.

phpstan · phpunit

Инструменты

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

PHP не компилируется заранее, поэтому «синтаксически верно» не значит «работает». Разницу закрывают инструменты: статический анализатор читает код и находит то, что упадёт при выполнении, тесты проверяют поведение, форматтер убирает споры о стиле из обсуждений.

Консоль

composer require --dev phpstan/phpstan phpunit/phpunit friendsofphp/php-cs-fixer rector/rector

vendor/bin/phpstan analyse src --level=8   # уровень 0 — мягкий, 9 (max) — строгий
vendor/bin/phpunit
vendor/bin/php-cs-fixer fix
vendor/bin/rector process src --dry-run

Что во что упирается

php -l

только синтаксис; бесплатно и мгновенно — годится как самый первый шаг в CI

PHPStan / Psalm

типы, недостижимый код, обращения к несуществующим методам — без запуска

PHPUnit

поведение: что код действительно делает с этими данными

php-cs-fixer

оформление; спорить о скобках больше не нужно

Rector

массовые правки: миграция на новую версию PHP, замена устаревшего

Xdebug

пошаговая отладка и покрытие тестами; на проде — выключен

советСтатический анализ начинают не с максимума

Поставьте уровень, на котором ошибок немного, зафиксируйте текущие проблемы в baseline (phpstan analyse --generate-baseline) и поднимайте планку по одному уровню. Так анализатор начинает приносить пользу с первого дня, а не «когда-нибудь потом».

10 шт.

пример

PHPStan

Статический анализатор с уровнями строгости от 0 до 10. Понимает PHPDoc-обобщения (list<User>, array<string, int>), которых в самом языке нет.

опции: baseline, расширения для фреймворков

parameters:
    level: 8
    paths: [src, tests]
    treatPhpDocTypesAsCertain: false

Минимальный набор в CI

.github/workflows/ci.ymlYAML

name: CI
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
          coverage: none
      - run: composer install --no-interaction --prefer-dist
      - run: composer audit --locked
      - run: vendor/bin/php-cs-fixer fix --dry-run --diff
      - run: vendor/bin/phpstan analyse --no-progress
      - run: vendor/bin/phpunit

советЛокально то же самое, что в CI

Если проверки запускаются одной командой (composer check), никто не узнаёт о нарушении стиля из красной сборки через десять минут. Полезно и в git-хуке перед коммитом — но только быстрые проверки, иначе его отключат.

вниманиеИнструменты не заменяют ревью

Анализатор не скажет, что метод называется неверно, абстракция протекает, а вместо трёх классов хватило бы функции. Он снимает механическую часть — и именно поэтому на ревью остаётся время для содержательной.

PHP_VERSION

Версии 8.0–8.5

Что появилось в каждом выпуске восьмёрки, что из старого перестало работать и как переезжать, не устраивая проект на полгода.

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

что даёт версия

граблиУстаревшее — это не «сломается завтра»

E_DEPRECATED ничего не ломает сегодня, но обещает ошибку в следующей крупной версии. Проект, где в логе тысячи deprecated-сообщений, обновляется рывком и с болью; проект, где их ноль, переезжает за вечер.

Все заметные возможности восьмёрки в одном списке — с версией, начиная с которой их можно писать. Фильтр понимает и номер версии: наберите «8.3», чтобы увидеть только её.

30 шт.

пример

Именованные аргументы8.0

Передача по имени параметра, а не по позиции.

опции: см. узел «функции»

setcookie('token', $v, httponly: true, samesite: 'Lax');

Как переезжать на новую версию

Поднимите "php": "^8.4" в composer.json и выполните composer update — часть пакетов обновится сама.
Прогоните тесты на новой версии с error_reporting(E_ALL) и включённым логированием: устаревшее проявится сразу.
Соберите deprecated-сообщения из логов — это и есть список работ.
Пропустите Rector с набором для целевой версии (withPhpSets) и просмотрите изменения глазами.
Поднимите уровень PHPStan: на новой версии он видит больше.
Выкатывайте на часть трафика, если есть такая возможность: часть несовместимостей вылезает только на реальных данных.

Проверка версии в коде

PHP

// сравнение строк версий работает, но PHP_VERSION_ID быстрее и надёжнее
if (PHP_VERSION_ID < 80300) {
    fwrite(STDERR, "нужен PHP 8.3 или новее, а тут " . PHP_VERSION . "\n");
    exit(1);
}

// возможность лучше проверять по её наличию, а не по номеру версии
if (function_exists('json_validate')) {
    $ok = json_validate($raw);
} else {
    json_decode($raw);
    $ok = json_last_error() === JSON_ERROR_NONE;
}

советМинимальную версию задаёт composer.json, а не сервер

Строка "php": "^8.3" в require не даст установить проект туда, где стоит 8.1, и заставит Composer подбирать совместимые версии пакетов. А config.platform фиксирует версию, под которую собираются зависимости, даже если локально у вас новее.

вниманиеНовый синтаксис нельзя закрыть полифилом

Функцию можно дописать самому, а |>, хуки свойств и readonly — нет: файл с ними не разберётся на старой версии вовсе, даже если эта ветка кода никогда не выполняется. Поэтому в библиотеках, поддерживающих несколько версий, новый синтаксис появляется только со сменой мажорной версии пакета.