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

В этой статье мы разберем, как правильно настроить Psalm для Laravel-проекта, который работает в Docker, и интегрируем его с PhpStorm для комфортной разработки.

Почему Psalm для Laravel?

Psalm проверяет типы данных, находить неиспользуемый код и потенциальные ошибки. Но "из коробки" он не понимает специфику Laravel. Для этого существует официальный плагин psalm/plugin-laravel, который использует barryvdh/laravel-ide-helper для генерации стабов. Это помогает Psalm понимать магические методы и фасады фреймворка.

Шаг 1: Установка зависимостей

Поскольку наш проект работает в Docker, все команды Composer должны выполняться внутри контейнера с PHP. Предположим, что ваш сервис называется app (или php), а управление осуществляется через docker compose.

Откройте терминал и выполните команду установки плагина. Это также автоматически установит сам vimeo/psalm, если его еще нет:

docker compose exec app composer require --dev psalm/plugin-laravel

Примечание: Замените app на имя вашего PHP-контейнера, если оно отличается.

Шаг 2: Инициализация конфигурации

После установки нужно создать файл конфигурации psalm.xml. Если вы запускаете Psalm впервые, используйте команду инициализации:

docker compose exec app ./vendor/bin/psalm --init

Psalm просканирует проект и предложит начальный уровень строгости (error level). Обычно рекомендуется начать с уровня 4 или 5, чтобы не получить тысячу ошибок сразу, а затем постепенно повышать планку до 1.

Шаг 3: Активация плагина Laravel

Это критически важный шаг. Без него Psalm будет ругаться на стандартные методы Laravel (например, User::find() или auth()->user()).

Выполните команду для включения плагина:

docker compose exec app ./vendor/bin/psalm-plugin enable psalm/plugin-laravel

Эта команда автоматически внесет необходимые изменения в файл psalm.xml, добавив конфигурацию плагина.

Шаг 4: Интеграция с PhpStorm

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

Вариант А: Использование плагина JetBrains (Рекомендуется)

1. Откройте Settings / Preferences -> Plugins.

2. Найдите и установите плагин Psalm (от JetBrains).

3. Перезагрузите IDE.

4. Перейдите в Settings -> Languages & Frameworks -> PHP -> Quality Tools -> Psalm.

5. Убедитесь, что путь к исполняемому файлу указан верно. В случае с Docker лучше настроить PhpStorm Deployment или использовать PHP Interpreters, чтобы IDE понимала, что файл vendor/bin/psalm находится внутри контейнера.

Вариант Б: External Tool

Если вы предпочитаете запускать анализ по кнопке:

1. Settings -> Tools -> External Tools.

2. Добавьте новый инструмент:

Name: Psalm

Program: docker (или путь к docker-compose)

Arguments: docker compose exec app ./vendor/bin/psalm $FilePath$ (для анализа текущего файла)

Working directory: $ProjectFileDir$

Важный нюанс Docker и путей

PhpStorm должен корректно сопоставлять пути между хост-машиной и контейнером. Если вы используете Docker Interpreter в настройках PHP проекта, Psalm сможет правильно указывать на строки ошибок в ваших локальных файлах. Проверьте настройки PHP Servers в IDE, чтобы пути мапились верно.

Шаг 5: Первый запуск и Baseline

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

Выполните команду:

docker compose exec app ./vendor/bin/psalm --set-baseline=psalm-baseline.xml

Это создаст файл psalm-baseline.xml, который "заморозит" текущие ошибки. В будущем Psalm будет сообщать только о новых проблемах, не тревожа вас старыми.

Рекомендации по использованию

1. Уровень строгости (Error Level):

В файле psalm.xml найдите атрибут errorLevel. Начните с 4. По мере исправления кода уменьшайте его до 1.

2. Игнорирование папок:

Убедитесь, что в psalm.xml исключены папки, которые не нужно проверять (например, vendor, node_modules, storage).

3. CI/CD:

Добавьте запуск Psalm в ваш пайплайн сборки. Это гарантирует, что новый код не пройдет проверку, если он содержит критические ошибки типов.

Заключение

Настройка Psalm в связке с Laravel, Docker и PhpStorm может занять немного времени, но это окупается снижением количества багов в продакшене. Официальный плагин psalm/plugin-laravel берет на себя всю сложность понимания магических методов фреймворка, а интеграция с IDE позволяет видеть проблемы прямо во время набора кода.

Начните с базовой настройки, используйте baseline для легкого старта и постепенно повышайте уровень строгости. Ваш код скажет вам спасибо!