PHPStan: настройка, уровни и лучшие практики

Быстрые ссылки

Добавление PHPStan в проект
Типы ошибок и уровни
Настройка PHPStan
Игнорирование ошибок
Опциональные правила
Заключение

Логотип PHPStan

Что такое статический анализ и зачем нужен PHPStan

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

Ключевые свойства PHPStan:

Работает без выполнения приложения.
Поддерживает расширения и пользовательские правила.
Имеет режимы строгости (уровни) — от базовой проверки до очень строгой.

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

Добавление PHPStan в проект

Для запуска PHPStan требуется PHP 7.1 или новее — это требование к версии PHP, которая исполняет сам анализатор; PHPStan сам может анализировать код, совместимый с более старыми версиями PHP.

Рекомендуется устанавливать PHPStan через Composer как dev-зависимость:

composer require --dev phpstan/phpstan

После установки бинарник будет доступен по пути vendor/bin/phpstan. Первый запуск по умолчанию можно выполнить для каталога с исходниками:

vendor/bin/phpstan analyse src

Команда просканирует директорию src и вернёт список ошибок или сообщение об отсутствии ошибок. В больших кодовых базах анализ может занять от нескольких секунд до нескольких минут в зависимости от объёма кода и конфигурации кеша.

Успешный запуск PHPStan

Если всё в порядке, вы увидите зелёное сообщение “[OK] No errors”. В противном случае будет список найденных проблем и указания, где их исправить.

Типы ошибок и уровни строгости

PHPStan выполняет большое количество проверок. Основные категории ошибок:

Проблемы с системой типов — присвоение неверного значения типизированному свойству, несоответствие сигнатур методов интерфейсам или родительским методам.
Ошибки вызовов функций/методов — некорректное число аргументов или неправильные типы.
Неизвестные классы, функции и методы — попытка использовать несуществующие элементы.
Доступ к неопределённым переменным — использование переменной вне зоны видимости или без гарантированного значения.
Проверка «мёртвого» кода — ветви, которые никогда не выполнятся, или выражения, дающие предсказуемый результат.

Проверки сгруппированы по уровням от 0 до 8; специальный уровень max соответствует самому строгому набору проверок. По умолчанию PHPStan запускается на уровне 0. Практическая рекомендация: достигните чистоты на текущем уровне и только затем переходите на следующий.

Простой пример ошибки типов (показано для иллюстрации):

// Пример: ожидается int, а передаётся string
function add(int $a, int $b): int
{
    return $a + $b;
}

add('1', 2); // PHPStan укажет на несовпадение типа

Когда уровни полезны

Уровень 0 — базовые проверки: синтаксис, вызовы функций, существование классов.
Уровни 1–4 — постепенное ужесточение проверок типов и совместимости сигнатур.
Уровни 5–8 и max — самые строгие проверки, включая расширенные анализы потоков данных и детекцию тонких ошибок.

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

Неудачный запуск PHPStan с ошибками

Конфигурирование PHPStan

CLI удобен для разовых запусков, но для команд лучше добавить конфигурацию в репозиторий. PHPStan использует формат NEON, похожий на YAML.

Создайте файл phpstan.neon в корне проекта — он будет автоматически подхватываться при запуске анализа без указания аргументов:

vendor/bin/phpstan analyse

Если нужно указать альтернативный файл конфигурации, используйте флаг --configuration:

vendor/bin/phpstan analyse --configuration /phpstan-config.neon

Пример простого phpstan.neon как отправная точка:

parameters:
  level: 0
  paths:
    - src
  excludes_analyse:
    - tests/_data

Этот файл эквивалентен вызову CLI для папки src. Добавляйте дополнительные директории в paths по одной на строку. Чтобы исключить файлы и каталоги из анализа, используйте excludes_analyse.

Шаблон phpstan.neon (расширенный пример с комментариями):

parameters:
  # Уровень строгости: 0..8 или max
  level: 2

  # Папки и файлы для анализа
  paths:
    - src
    - lib

  # Исключаемые пути (шаблоны)
  excludes_analyse:
    - tests/_data
    - src/legacy/*

  # Игнорируем ошибки (см. раздел ниже)
  ignoreErrors:
    - message: '/Return type .* is not covariant(.*)/'
      paths:
        - src/ExampleClass.php

includes:
  - vendor/phpstan/phpstan/conf/bleedingEdge.neon

Игнорирование ошибок (ignoreErrors)

Иногда встречаются проблемы, которые вы не можете срочно исправить (унаследованный код, внешняя библиотека и т.д.). Игнорирование ошибок даёт временную передышку, но используется только при осознанном решении.

Пример конфигурации ignoreErrors в phpstan.neon:

parameters:
  ignoreErrors:
    - message: '/Return type string of method ExampleClass::example\(\) is not covariant(.*)/'
      paths:
        - src/ExampleClass.php

Пара советов по ignoreErrors:

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

Когда ignoreErrors — плохая идея

Когда вы игнорируете системно много ошибок — это снижает ценность анализа.
Когда игнорируются ошибки, связанные с API или контрактами (интерфейсы/наследование) — это может привести к регрессиям.

Опциональные правила и тонкая настройка

PHPStan предоставляет набор настроек, которые не зависят от уровней, но усиливают или ослабляют проверку. Некоторые из них:

checkAlwaysTrueInstanceof — указывает случаи, когда выражение instanceof всегда true.
checkAlwaysTrueStrictComparison — отмечает сравнения с === и !==, которые всегда дают true.
checkFunctionNameCase — проверяет соответствие регистра имени функции с её определением.
polluteScopeWithLoopInitialAssignments — по умолчанию true; при значении false предотвращает доступ к переменным цикла вне его тела.
reportStaticMethodSignatures — заставляет проверять подписи статических методов при переопределении.

Включать настройку следует, понимая последствия — некоторые команды предпочитают не включать строгие правила по историческим причинам.

Практические шаблоны и чеклисты

Ниже — практические артефакты, которые облегчат внедрение PHPStan в команду.

Шаблон простого workflow для CI (пример):

Установить зависимости и кеш composer в CI.
Запустить vendor/bin/phpstan analyse --no-progress.
При обнаружении ошибок: fail build; обязать исправление в PR.
При необходимости временно разрешить отдельные ошибки через ignoreErrors и создать задачу на устранение.

Критерии приёмки для повышения уровня PHPStan (пример для перехода с уровня N на N+1):

Ветка проекта проходит phpstan analyse на уровне N без ошибок.
Для всех ошибок уровня N+1 созданы задачи и определён план исправлений.
Все критические ошибки уровня N+1 устранены в приоритетных модулях.

Чеклист для ролей

Разработчик:
- Запустил PHPStan локально перед PR.
- Исправил выявленные ошибки или объяснил, почему игнорирование допустимо.
Тимлид:
- Проверил, что изменения не понижают уровень качества.
- Контролирует списки ignoreErrors и задачи по исправлению наследия.
Инженер CI:
- Обеспечил корректную интеграцию PHPStan в pipeline.
- Настроил кеши и артефакты для ускорения анализов.

Роль-based checklist ускоряет внедрение и снижает трение для команды.

Когда PHPStan не помогает или даёт ложные срабатывания

PHPStan не заменяет тестирование бизнес-логики и может выдавать ложные положительные срабатывания в случаях:

Динамически создаваемые свойства или методы (через get, call) без соответствующих аннотаций.
Сильное использование магии и runtime-логики, которую невозможно корректно вывести статическим анализом.
Отсутствие phpdoc и типовой информации в старом коде.

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

Альтернативы и совместное использование

На рынке есть другие инструменты статического анализа PHP — полезно знать, чем они отличаются:

Psalm — строгий статический анализатор с мощным type-inference и возможностью автоматического исправления (type assertions).
Phan — ранний аналитический инструмент для PHP с хорошей производительностью для больших кодовых баз.

Матричный обзор (качественный):

Простота установки: PHPStan, Psalm — обе просты через Composer.
Глубина анализa: Psalm и PHPStan предлагают глубокую проверку, но с разными акцентами.
Сообщество и плагины: оба имеют расширения; выбор зависит от бизнес-требований и привычек команды.

Можно использовать PHPStan и Psalm в связке: например, один инструмент для быстрого CI-проверки, другой — для периодического глубокого аудита.

Runbook при падении CI из-за PHPStan

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

Советы по миграции существующего кода

Начните с уровня 0 и постепенно повышайте уровень, исправляя ошибки шаг за шагом.
Ведите журнал найденных ошибок и назначайте владельцев для модулей.
Используйте excludes_analyse и ignoreErrors временно, но планируйте их удаление.
В больших кодовых базах фиксируйте ошибки по пакетам (пакет за пакетом), чтобы не блокировать всю команду.

Краткий глоссарий

Статический анализ — поиск ошибок в коде без его исполнения.
NEON — формат конфигурации, похожий на YAML, используемый PHPStan.
Уровень (level) — параметр строгости проверок PHPStan.
ignoreErrors — секция конфигурации для временного исключения конкретных сообщений.

Модель зрелости для внедрения PHPStan (высокоуровневая)

Нулевая зрелость: инструмент не установлен.
Базовая: PHPStan установлен, уровень 0, CI оповещает о критических ошибках.
Прогрессирующая: постепенное повышение уровней, создание задач на устранение унаследованных проблем.
Зрелая: PHPStan на уровне max либо на выбранном высоком уровне, минимальные ignoreErrors, процесс интегрирован в CI и процесс принятия кода.

Заключение

PHPStan — эффективный инструмент для повышения качества PHP-кода. Его сила в раннем обнаружении ошибок типов, некорректных вызовов и потенциально опасных участков кода. Установка и базовая конфигурация просты, но реальная ценность появляется при интеграции в процесс разработки: CI, код-ревью и постепенное повышение уровня строгих проверок.

Важно: не рассматривайте PHPStan как замену тестам. Это инструмент, который дополняет юнит- и интеграционные тесты, делая код более предсказуемым и поддерживаемым.

Важно: используйте ignoreErrors экономно и документируйте причины для каждого исключения.

Краткая контрольная сводка:

Настройте PHPStan через Composer и добавьте phpstan.neon в репозиторий.
Запускайте анализ локально и в CI; повышайте уровень шаг за шагом.
Документируйте игнорируемые ошибки и планируйте их устранение.

Введение в PHPStan для PHP-разработчиков