Почему стоит отказаться от слепого следования стандартам программирования
Единый формат кода экономит время, а проверяемый контракт защищает вызывающий код от поломок. Проблемы начинаются, когда личные предпочтения превращаются в обязательные правила. Разберём, что стоит закрепить в PHP-проекте, что поручить CI и какие решения оставить разработчикам.
Сколько стоит ещё одно правило
На ревью легко заметить имя переменной или длину метода. Гораздо дольше разбираться, что произойдёт, если клиент повторит запрос после тайм-аута, а первая операция уже записала данные. Если обсуждение стиля занимает всё внимание, у команды остаётся меньше времени на вопросы, от которых зависит поведение системы.
Прежде чем закреплять новое правило, разберите конкретный случай. Какую ошибку оно помогло бы предотвратить? Где это требование применимо? Как команда поймёт, что правило соблюдено? Например, обязательный ключ идемпотентности для операции списания даёт проверяемое свойство: повторный запрос с тем же ключом сохраняет результат первой операции. Требование держать любой метод короче 20 строк даёт число, по которому трудно судить о понятности кода.
То же касается метрик сложности и покрытия. Высокая сложность подсказывает, где стоит внимательно посмотреть на ветвления. Покрытие показывает, какие строки выполнялись во время тестов. Для решения о слиянии важнее выяснить, проверяет ли тест нужный результат при ошибке, повторном запросе или пустом ответе.
Форматирование отдайте инструменту
Возьмите общий профиль форматирования, например PSR-12, и храните настройки PHP CS Fixer или PHP_CodeSniffer в репозитории. Разработчик должен иметь возможность локально запустить ту же проверку, что выполняется в CI. Версию инструмента фиксируйте вместе с зависимостями проекта, чтобы обновление форматтера было обычным изменением с обозримым diff.
При подключении форматтера к действующему проекту удобнее вынести массовое форматирование в отдельный коммит. Так в следующем ревью будет проще увидеть изменения условий, типов и возвращаемых значений. Если старый модуль пока исключён из проверки, укажите точный путь: иначе исключение легко распространится и на новый код.
На конец 2026 года для проектов с поддерживаемыми ветками PHP 8.3–8.5 важно явно задать минимальную версию. Если пакет обещает работать на всём этом диапазоне, прогоняйте тесты на 8.3, 8.4 и 8.5. Код пакета и его зависимости должны устанавливаться на минимальной версии. Например, array_any() можно использовать при минимуме PHP 8.4, а для PHP 8.3 ту же проверку удобно выразить циклом foreach с ранним возвратом.
Строгие типы начинаются с границ приложения
Для новых PHP-файлов разумно принять declare(strict_types=1) и объявлять типы параметров, возвращаемых значений и свойств. В случае обычных вызовов пользовательских функций режим передачи скалярных аргументов определяется файлом, из которого сделан вызов. Если декларация стоит только в файле с объявлением функции, вызов из файла без неё по-прежнему может привести подходящую строку к числу.
HTTP-формы передают числа строками, а результат разбора JSON зависит от того, что прислал клиент. Преобразуйте внешние данные рядом с точкой входа, чтобы внутренняя функция получала уже проверенный аргумент. В этом примере поле количества принимает положительное целое или его строковую запись:
<?php
declare(strict_types=1);
function parseQuantity(mixed $value): int
{
// Форма передаёт строку, а JSON может передать целое число.
if (!is_int($value) && !is_string($value)) {
throw new InvalidArgumentException('Укажите целое количество.');
}
$quantity = filter_var($value, FILTER_VALIDATE_INT, [
'options' => ['min_range' => 1],
]);
if ($quantity === false) {
throw new InvalidArgumentException('Количество должно быть целым и больше нуля.');
}
return $quantity;
}
echo parseQuantity('12'); // 12На уровне HTTP это исключение можно преобразовать в ошибку конкретного поля. Внутренний код получает int и может опираться на уже проверенный нижний предел. Для действующего модуля вводите строгий режим вместе с проверкой его вызовов: добавление декларации может раскрыть зависимость от преобразований, которыми пользовался старый код.
Архитектурное правило должно отвечать на конкретный вопрос
Требование «у каждого сервиса должен быть интерфейс» слабо помогает выбрать структуру. Начните с того, кто зависит от сервиса и что может измениться. У платёжного шлюза есть внешний протокол, ошибки сети и отдельный жизненный цикл. Интерфейс на этой границе позволит прикладному коду оперировать результатом платежа и тестировать сценарии с отказом без обращения к провайдеру. Для внутреннего расчёта скидки с одной реализацией часто достаточно функции или класса с понятным контрактом.
Формулируйте архитектурные ограничения так, чтобы на ревью можно было указать конкретное нарушение. Например, «расчёт стоимости доставки получает тариф и параметры отправления аргументами» означает, что он не читает HTTP-запрос и не обращается за тарифом к базе. Так один расчёт можно использовать при оформлении заказа, в фоновом задании и в тесте с заранее заданным тарифом. А решение о том, будет ли расчёт классом, остаётся за автором изменения.
Выбирайте конструкции PHP по смыслу задачи. enum подходит для закрытого набора состояний, которым владеет приложение. Если внешний сервис может прислать новый статус без вашего релиза, обработайте неизвестное значение на границе. У строкового перечисления для этого есть tryFrom(): вызывающий код сможет сохранить исходное значение для диагностики и выбрать явное поведение для неизвестного статуса.
На ревью проверяйте последствия изменения
Хорошее замечание на ревью связывает участок кода со сценарием. Вместо «оберните это в транзакцию» можно написать: «Если сохранение позиций завершится ошибкой, заказ останется в базе без позиций. Можно ли сохранить обе записи в одной транзакции?» Теперь понятно, что должно происходить при сбое и какой тест подтвердит исправление. Если часть операции выполняет внешний сервис, отдельно обсудите повторы. Транзакция базы данных охватывает только изменения в её пределах.
- Форматтер проверяет отступы, пробелы и переносы.
- PHPStan или Psalm помогает находить несовместимые типы, неверные обращения к nullable-значениям и ошибки в описании структур массивов.
- Тесты закрепляют наблюдаемое поведение. Для обработчика команды это могут быть корректное сохранение, отказ при неверном вводе и отсутствие повторного изменения при дубле.
- Ревью связывает изменение с предметной областью. Здесь решают, кто может выполнить операцию, что считать повтором и какой результат получит клиент при частичном сбое.
При подключении статического анализа к большому проекту зафиксируйте текущие сообщения в baseline и проверяйте новые. По мере исправления старого кода удаляйте соответствующие записи. Это позволяет постепенно повышать требования без массового добавления подавлений в файлы приложения.
Когда исключение из правила оправдано
Одноразовой консольной утилите для сверки двух выгрузок может хватить простого сценария с несколькими функциями. Если в проекте обычно выделяют отдельные классы для чтения и записи файлов, утилита может обойтись без них. При этом ей всё ещё нужны понятное сообщение об ошибке чтения и корректный код завершения. Если появится второй потребитель той же логики или утилита станет регулярным заданием, структуру можно пересмотреть по реальному сценарию использования.
Обсуждайте исключение там, где меняется код. В описании изменения достаточно указать область действия, причину и условие пересмотра. Для подавления предупреждения статического анализатора укажите конкретную проверку и объясните, какую гарантию анализатор не видит. Если похожее исключение приходится обосновывать в нескольких модулях, проверьте, подходит ли исходное правило для всех этих модулей.
Чек-лист для команды PHP
- Укажите минимальную версию PHP и проверьте все ветки, поддержку которых обещаете пользователям проекта.
- Выберите один профиль форматирования и запускайте его одинаково локально и в CI.
- Типизируйте новый код и валидируйте входные данные в точках входа. При добавлении
strict_typesк существующему файлу проверьте вызовы из него. - Для каждого обязательного архитектурного ограничения запишите, какое поведение оно защищает и где действует.
- На ревью разбирайте права доступа, отказ зависимостей, частичную запись и повтор операций там, где эти сценарии применимы.
- Если правило регулярно вызывает споры, возьмите несколько реальных изменений и решите, можно ли его автоматизировать, сузить или убрать.
Начните с последнего спорного ревью. Передайте проверку оформления инструменту, зафиксируйте обнаруженную ошибку тестом и оставьте автору выбор реализации в пределах согласованного контракта.
Частые вопросы
Стоит ли полностью отказываться от стандартов программирования в PHP?
Сохраните единый формат и требования, которые защищают совместимость, данные и публичные контракты. Решения о структуре конкретного модуля обсуждайте с учётом его задачи и стоимости поддержки.
Нужно ли добавлять declare(strict_types=1) во все PHP-файлы?
Для новых файлов это подходящее соглашение команды. В существующих файлах добавляйте декларацию с учётом вызовов, которые могли полагаться на автоматическое преобразование скалярных аргументов. Внешние данные валидируйте отдельно.
Как сочетать PSR-12, статический анализ и код-ревью?
Используйте PSR-12 как профиль оформления и проверяйте его инструментом в CI. Поручите PHPStan или Psalm проверку типов, а на ревью обсуждайте поведение, контракты и последствия изменений для вызывающего кода.