PHPStan — руководство по статическому анализу PHP

Логотип PHPStan

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

Установка PHPStan в проект
Типы ошибок и уровни строгости
Конфигурация PHPStan
Игнорирование ошибок
Дополнительные правила и настройки
Внедрение в CI и практики команды
Критерии приёмки
Заключение

Что такое PHPStan

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

Короткое определение: статический анализ — проверка кода на ошибки без его выполнения.

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

Требования

Для запуска PHPStan требуется PHP 7.1 или новее (версия PHP для выполнения самого инструмента). Анализируемые файлы могут ориентироваться и на более старые версии PHP.
Рекомендуется управлять зависимостями через Composer.

Установка и начало работы с PHPStan

Лучше всего добавлять PHPStan как dev-зависимость через Composer:

composer require --dev phpstan/phpstan

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

vendor/bin/phpstan analyse src

Этот запуск просканирует все файлы в каталоге src. В крупных проектах анализ может занимать от нескольких секунд до нескольких минут.

Успешный запуск PHPStan: зелёное сообщение No errors

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

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

PHPStan содержит множество проверок. Частые категории ошибок:

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

Правила сгруппированы по уровням от 0 до 8; специальный уровень max означает максимально строгую проверку. По умолчанию запускается уровень 0 (минимальный набор проверок). Хорошая практика — проходить уровни по одному, исправляя накопленные замечания, прежде чем повышать строгость.

Неудачный запуск PHPStan: список ошибок и трассировка

Для смены уровня используйте флаг --level:

vendor/bin/phpstan analyse src --level 8

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

Конфигурация PHPStan

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

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

vendor/bin/phpstan analyse

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

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

Простой стартовый пример phpstan.neon:

parameters:
  level: 0
  paths:
    - src

Этот файл эквивалентен запуску vendor/bin/phpstan analyse src --level 0.

Чтобы исключить файлы из анализа, добавьте excludes_analyse внутри parameters:

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

Игнорирование отдельных ошибок

Иногда встречаются предупреждения, которые вы не можете исправить немедленно (например, внешняя несовместимость). В таких случаях можно явно игнорировать отдельные сообщения в конфиге. Делать это следует осторожно.

Пример ignoreErrors в phpstan.neon:

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

Здесь message — регулярное выражение для матчинга текста ошибки, а paths — массив путей, к которым применяется исключение. Лучше указывать максимально узкие шаблоны сообщений и точные файлы, чтобы не скрыть другие важные проблемы.

Дополнительные настройки и опции

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

Некоторые полезные опции:

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

Полный список опций и их описание доступен в официальной документации PHPStan.

Внедрение PHPStan в процесс разработки (мини-методология)

Мини-метод внедрения PHPStan в существующий проект:

Запустите PHPStan на уровне 0 и просмотрите список ошибок.
Исправьте наиболее частые и тривиальные проблемы (неопределённые переменные, опечатки в именах).
Постепенно повышайте уровень: 0 → 1 → 2 и т.д., фиксируя новый набор ошибок на каждом шаге.
Где исправление невозможно сразу, добавьте аккуратные ignoreErrors с узким scope.
Интегрируйте запуск в CI (см. раздел «Интеграция в CI»).
Со временем добавьте дополнительные правила или пользовательские расширения.

Эта итеративная модель даёт управление объёмом работ и снижает риск массового игнорирования ошибок.

Интеграция в CI и рабочий процесс команды

Пример включения PHPStan в конвейер CI (логика, не конфигурация конкретного CI):

На шаге сборки запускайте vendor/bin/phpstan analyse --configuration phpstan.neon.
Для веток с feature-разработкой можно использовать более мягкий уровень и предупреждения без остановки сборки, а для ветки main/master — строгий уровень, который блокирует сборку при ошибках.
Автоматизируйте формирование отчётов (json или junit) для интеграции с инструментами обзора качества кода.

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

Откройте лог CI и найдите первое упавшее сообщение PHPStan.
Если ошибка тривиальна — исправьте в новом коммите и отправьте PR.
Если ошибка связана с внешней библиотекой или особенностями старого кода — обсудите с командой и, если согласовано, временно добавьте ignoreErrors с точным путём.
Если массовые новые ошибки появились после повышения уровня — откатите изменение уровня и проверьте план по исправлению (migrational plan).

Роль-based чек-листы

Разработчик:

Запустить PHPStan локально перед PR.
Исправить ошибки уровня, принятого в проекте.
Не добавлять broad ignoreErrors без обсуждения.

Ревьюер:

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

DevOps/CI-инженер:

Настроить шаг анализа в CI.
Собирать отчёты и хранить их для ретроспектив.

Критерии приёмки

Билд не должен падать из-за ошибок PHPStan на ветке релиза.
Для новой фичи — количество ошибок уровня, принятого в проекте, равно нулю.
Любое добавление игнорирования сопровождается комментарием в PR и задачей на исправление (если нужно).

Когда PHPStan не помогает и ограничения

Логические ошибки бизнес-правил: PHPStan не понимает доменную логику и не выявит некорректные вычисления, если сигнатуры и типы корректны.
Скрытые ошибки времени выполнения (race conditions, network failures, конфликты миграций) — вне области статического анализа.
Проекты, где код генерируется динамически, могут требовать дополнительной конфигурации автозагрузки и stub-файлов.

Советы по миграции и совместимости

Если проект использует автозагрузку Composer, убедитесь, что autoload корректно настроен — иначе PHPStan не найдёт классы.
Для старого кода можно добавить отдельный phpstan.neon с более мягкими параметрами и постепенно улучшать его.
Сохраняйте phpstan.neon в репозитории и документируйте правила игнорирования.

Полезные сниппеты и шпаргалка команд

Запуск для конкретной папки:

vendor/bin/phpstan analyse src/Service --level 5

Экспорт отчёта в JSON (для последующей обработки):

vendor/bin/phpstan analyse --error-format json > phpstan-report.json

Запуск с указанием конфигурационного файла:

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

Примеры конфигураций и шаблоны

Шаблон, который полезно держать под рукой при старте:

parameters:
  level: 1
  paths:
    - src
  excludes_analyse:
    - src/legacy
  ignoreErrors:
    - message: '/Some legacy warning regex/'
      paths:
        - src/legacy/LegacyFile.php

Decision tree (Mermaid)

flowchart TD
  A[Начать использовать PHPStan?] --> B{Есть тестовая среда и CI?}
  B -- Да --> C[Добавить как dev-зависимость]
  B -- Нет --> D[Локальный запуск и постепенная интеграция]
  C --> E{Код современный и типизирован?}
  D --> E
  E -- Да --> F[Стартовать с уровня 6 и выше]
  E -- Нет --> G[Стартовать с уровня 0 и планировать миграцию]
  F --> H[Интегрировать в CI с failing build]
  G --> I[Интегрировать в CI как проверку, не фейл]

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

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

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

PHPStan анализирует только исходный код и не выполняет его. В CI-окружении следите за тем, чтобы конфигурационные файлы с правилами и исключениями не раскрывали секреты (пароли, токены). Храните секреты отдельно от кода.

Заключение

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

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

Ключевые действия для старта:

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

Введение в PHPStan: статический анализ для PHP