PHPStan + WordPress: статический анализ кода плагинов и тем (2026)

Почему PHPStan – must‑have для разработчиков WordPress

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

Сочетание PHPStan и WordPress позволяет:

• Сократить количество undefined variable и call to undefined method;
• Обнаружить несовместимости с последними версиями PHP;
• Улучшить читаемость и поддерживаемость кода за счёт строгих типовых аннотаций.

Шаг 1. Установка PHPStan в проект WordPress

Самый простой способ – добавить PHPStan через Composer. Если ваш плагин или тема уже используют composer.json, выполните:

composer require --dev phpstan/phpstan:^1.10

Для чистого проекта без Composer можно создать composer.json вручную:

{
    "require-dev": {
        "phpstan/phpstan": "^1.10"
    }
}

После этого запустите composer install. Теперь в корне проекта появится файл vendor/bin/phpstan – ваш основной исполнитель.

Шаг 2. Базовая конфигурация PHPStan для WordPress

Создайте файл phpstan.neon в корне темы/плагина. Минимальная конфигурация выглядит так:

parameters:
    level: max
    paths:
        - src
    autoload_files:
        - %rootDir%/../vendor/autoload.php
    bootstrapFiles:
        - wp-load.php
    ignoreErrors:
        - '#Call to undefined method .*#'

Обратите внимание на два важных параметра:

• bootstrapFiles – подключает wp-load.php, чтобы PHPStan «знал» функции WordPress;
• ignoreErrors – позволяет временно подавлять известные «ложные» предупреждения.

Если ваш код лежит в директории src, укажите её в paths. Для тем, где файлы находятся в корне, замените путь на ./.

Шаг 3. Выбор уровня анализа

PHPStan поддерживает уровни от 0 до 8 (и max). Чем выше уровень – тем строгие проверки. Рекомендуем начинать с уровня 3, чтобы не «переполнять» выводом, а затем постепенно повышать:

1. Запустите анализ: vendor/bin/phpstan analyse – получите базовый набор ошибок.
2. Увеличьте уровень до 5, исправьте найденные проблемы.
3. Перейдите к max (уровень 8). На этом этапе ваш код будет соответствовать лучшим практикам PHP.

Пример команды с указанием уровня:

vendor/bin/phpstan analyse -l 5

Шаг 4. Интеграция PHPStan в CI/CD

Автоматический запуск анализа при каждом пуше позволяет поддерживать качество кода. Ниже пример конфигурации для GitHub Actions:

name: PHPStan CI
on: [push, pull_request]
jobs:
  phpstan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
          extensions: mbstring, intl
          tools: composer
      - name: Install dependencies
        run: composer install --prefer-dist --no-progress --no-suggest
      - name: Run PHPStan
        run: vendor/bin/phpstan analyse -l max

Если ваш проект использует GitLab CI, замените actions/checkout на gitlab/checkout и аналогично настройте шаги.

Не забудьте добавить автоматический бэкап перед запуском CI, чтобы в случае падения сборки вы могли восстановить рабочую ветку.

Шаг 5. Исправление типовых ошибок PHPStan в WordPress‑коде

Самые частые предупреждения и способы их устранения:

• Undefined variable – объявите переменную с типом в докблоке:

  /** @var WP_Post $post */
  global $post;

• Call to undefined method – проверьте, что нужный класс подключён, либо добавьте @method в PHPDoc.
• Argument type mismatch – используйте строгую типизацию функций:

  function my_plugin_render(string $template, array $data = []): string {
      // ...
  }

• Return type should be compatible – добавьте : void или : WP_Error|WP_Post в сигнатуру.

Для ускорения разработки включите Lazy Loading плагинов – это уменьшит количество файлов, которые нужно анализировать в каждом билде.

Шаг 6. Полезные плагины и расширения PHPStan для WordPress

Существует несколько готовых наборов правил, которые учитывают особенности WordPress API:

• phpstan/wordpress – набор правил, покрывающих функции, хуки и глобальные переменные.
• phpstan/extension-installer – упрощает подключение сторонних расширений.
• Для тем, использующих Gutenberg, полезно добавить phpstan/phpstan-phpunit и проверять блоки через Gutenberg reusable blocks.

Установить расширения можно командой:

composer require --dev phpstan/wordpress phpstan/extension-installer

После установки обновите phpstan.neon:

includes:
    - vendor/phpstan/wordpress/extension.neon

Шаг 7. Мониторинг и отчёты

Для удобного просмотра результатов можно генерировать HTML‑отчёт:

vendor/bin/phpstan analyse -l max --error-format=table > phpstan-report.txt
vendor/bin/phpstan analyse -l max --error-format=checkstyle > phpstan-report.xml

XML‑отчёт удобно интегрировать в CI‑системы, а текстовый – в Slack‑уведомления.

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

Заключение

Внедрение PHPStan в процесс разработки WordPress‑плагинов и тем – это инвестиция в надёжность, безопасность и масштабируемость проекта. Следуя 7‑шаговому плану, вы получите автоматизированный контроль качества кода, сократите количество багов в продакшене и сможете быстро реагировать на новые требования PHP.

Начните с установки, поднимите уровень анализа постепенно и интегрируйте проверку в CI/CD – и ваш код будет соответствовать современным стандартам разработки.