Статический анализ в PHP: рабочие приёмы с PHPStan

Вы запускаете phpstan analyse на проекте, которому пять лет, и получаете четыре тысячи ошибок. Естественная реакция — закрыть терминал и решить, что статический анализ не для вас. На самом деле проблема в том, что инструмент запущен неправильно: без baseline, сразу на максимальном уровне и на всём коде разом. Разберём, как получить пользу от анализа с первого дня, а не через месяц правок.

Речь пойдёт о PHPStan 1.x (актуальна ветка 1.11+; в 2024 году вышла ветка 2.0, часть настроек в ней переименована — об этом ниже). Psalm упомянем для сравнения, но основной инструмент здесь один. Установка PHPStan в конфигурацию CI и написание собственных правил — отдельные темы, здесь только рабочие приёмы внедрения и повседневного использования.

Что вообще ловит статический анализ в PHP

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

• обращение к методу на null — классический источник Call to a member function on null;
• несоответствие типов аргументов и возвращаемых значений;
• обращение к несуществующему свойству или методу класса;
• мёртвый код: условия, которые всегда истинны или ложны;
• неверные типы в PHPDoc, которые расходятся с сигнатурой.

PHPStan работает на уровнях от 0 до 9 (в 2.0 добавлен уровень max как псевдоним максимального). Уровень 0 проверяет базовые вещи: существование классов, функций, методов. Уровень 9 придирается к каждому mixed.

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

Первый запуск: не начинайте с уровня 9

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

Минимальная конфигурация phpstan.neon в корне проекта:

parameters:
    level: 0
    paths:
        - src
        - tests
    # исключаем сгенерированный код и вендор
    excludePaths:
        - src/Generated/*

Запуск:

vendor/bin/phpstan analyse

Если ошибок на нулевом уровне ноль — поднимайте до 1, снова запускайте, чините. И так далее. Так вы разбираетесь с ошибками порциями, а каждая порция осмысленна: уровень 1 — про неопределённые переменные, уровень 2 — про неизвестные методы на объектах и так далее. Точное распределение проверок по уровням смотрите в документации: phpstan.org/user-guide/rule-levels.

Baseline: заморозить старые ошибки, ловить новые

Даже двигаясь по уровням, на большом legacy вы упрётесь в сотни ошибок, которые не почините за один спринт. Здесь спасает baseline — снимок текущих ошибок, который PHPStan будет игнорировать, но новые ошибки того же типа поймает.

Генерация baseline:

vendor/bin/phpstan analyse --generate-baseline

Команда создаст файл phpstan-baseline.neon со списком всех текущих ошибок. Подключите его в основной конфиг:

includes:
    - phpstan-baseline.neon

parameters:
    level: 5
    paths:
        - src

Теперь phpstan analyse проходит чисто, потому что весь старый долг заморожен. Но если вы напишете новый код с ошибкой — анализатор её покажет. Это ключевой приём: команда сразу поднимает уровень до 5 или 6, а старый код чинит постепенно, вычёркивая строки из baseline.

Не превращайте baseline в свалку. Периодически перегенерируйте его — если вы починили часть ошибок, старые записи в файле останутся мёртвым грузом и скроют регрессии. Хорошая практика — раз в спринт запускать генерацию заново и смотреть в diff, сколько строк ушло.

Ложные срабатывания: игнорировать точечно

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

Пример подавления по шаблону в phpstan.neon:

parameters:
    ignoreErrors:
        # Laravel-фасады PHPStan видит как статические вызовы
        - '#Call to an undefined static method#'

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

/** @var \App\Service\PaymentGateway $gateway */
$gateway = $container->get('payment.gateway');
$gateway->charge($amount); // теперь PHPStan знает тип

Расширения для фреймворков

Голый PHPStan не знает про магию Laravel, Symfony или Doctrine. Без расширений вы получите гору ложных ошибок на Eloquent-моделях и сервис-контейнере. Ставьте специализированные пакеты:

• Laravel — larastan/larastan (бывший nunomaduro/larastan);
• Symfony — phpstan/phpstan-symfony;
• Doctrine — phpstan/phpstan-doctrine;
• PHPUnit — phpstan/phpstan-phpunit для проверки тестов.

Расширения подключаются через секцию includes в конфиге. Точные имена файлов расширений и способ подключения смотрите в README каждого пакета — они иногда меняются между мажорными версиями.

PHPStan или Psalm

Второй распространённый анализатор — Psalm от Vimeo. Оба решают ту же задачу, различия в деталях.

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

Что делать дальше

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

1. Добавьте запуск PHPStan в CI как обязательную проверку — иначе новый код с ошибками будет проходить в main.
2. Раз в спринт перегенерируйте baseline и смотрите, сокращается ли он.
3. Когда чистый код на текущем уровне стабилен неделю-две — поднимите уровень на единицу и повторите цикл.
4. Настройте локальный запуск в pre-commit хуке на изменённых файлах, чтобы ошибки ловились до пуша.

Цель — не дойти до уровня 9 любой ценой, а держать код на том уровне, где реальные баги ловятся, а шум терпимый. Для большинства проектов это уровень 5–6 с постепенным движением вверх.