The Clean Structure

Оформление

Чистый код: Настройка PHPStorm ​

Если вы еще не читали книгу "Чистый код. Создание, анализ и рефакторинг" Роберта Мартина, то самое время это сделать. Или можно ознакомится с выжимкой в статьях:

В прошлой статье Чистая структура я рассказал о своем понимании хорошей структуры PHP-проекта. Но хорошая структура проекта - это только половина дела, другая половина - чистота вашего кода, залог здоровья вашего проекта в будущем.
Следить за соблюдением всех требований Code Style, проверять сигнатуры методов, процент покрытия кода и многое другое во время Code Review - утомительно и провоцирует постоянные конфликты в команде.
Намного удобнее все проверки проводить автоматически и единообразно для всех и не только в CI/CD, но и локально - в PHPStorm.
С роботом сложно спорить. 😃

Автоматизируй это ​

Прежде всего нужно настроить максимально простой и удобный запуск проверок нашего кода.

Composer scripts ​

Сценарии Composer — удобный способ определения и выполнения команд.

Основной минус этого метода - надо зайти в контейнер с PHP и там выполнить команду composer bla-bla.
И тут нам на помощь приходит PHPStorm: после настройки, запуск команды проходит по кнопке в интерфейсе. using-the-composer.png

Makefile ​

Чтобы каждый раз не заходить в контейнер, кроме PHPStorm, можно использовать "обертку" в виде Makefile. Утилита make широко распространена и включена во множество дистрибутивов.

Современный аналог Makefile - Taskfile.

В проекте-примере я использую оба подхода:

  • для работы с Git и Docker использую Makefile,
  • через PHPStorm запускаю команды из Composer scripts.

Анализируй это ​

Линтеры, в мире PHP больше известны под названием статические анализаторы кода, помогают:

  • Обучать новых членов команды принятым стандартам
  • Контролировать общее качество кода
  • Уменьшить вероятность возникновения критичных ошибок
  • Автоматизировать проверки на этапе CI/CD

PHPStorm ​

В PHPStorm существует встроенный статический анализатор, но, к сожалению, его возможности ограничены. В дополнение к нему, рекомендую поставить плагин Php Inspections (EA Extended) - в realtime подсвечивает ошибки и дает полезные советы.

PHP_CodeSniffer / PHP CS Fixer ​

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

В PHPStorm можно настроить интеграцию и тогда ошибки будет подсвечиваться с realtime:

Есть более универсальный вариант - easy-coding-standard Объединяет PHP Code Fixer, Code Sniffer, Slevomat и Simplify, но к сожалению не имеет интеграции с PHPStorm.

Исторически сложилось, что я использую Code Sniffer. Публикую набор правил, которые я использую почти в каждом проекте.

PHPStan / Psalm ​

Эти статические анализаторы проверяют типизацию в коде:

В PHPStorm также можно настроить проверки в realtime:

Мне больше нравится PHPStan, тк для него много плагинов, например:

PHP Mess Detector ​

Этот статический анализатор выявляет потенциальные проблемы в коде, определяет неоптимальные и усложнённые места и многое другое

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

Rector ​

Очень полезная утилита - проверяет соответствие кода возможностям PHP и фремворков (более 700 правил). Так же умеет исправлять найденные ошибки.

Мой вариант настроек для Rector.

Symfony ​

Каждый фреймворк имеет свои команды валидации, для Symfony это:

  • bin/console cache:clear - Не только удаляет кеш, но и стоит новый
  • bin/console lint:container - Проверка конфигурации сервис-контейнеров
  • bin/console lint:twig --format=github - Проверка синтаксических ошибок в шаблонах
  • bin/console lint:yaml . --format=github - Проверка файлов конфигурации

Хорошие bundle'ы так же имеют команды для проверки, например:

  • bin/console doctrine:schema:validate - Проверка соответствия схемы в БД и файлов с mapping-ом

Тестируй это ​

Чистый код - это не только ценный мех CodeStyle и TypeHint, но ещё и автоматические тесты.

PHPUnit + Coverage ​

Тесты надо писать всегда!
Без тестов - каждое обновление composer-зависимостей будет требовать полное регрессионное тестирование всего проекта.
Без тестов - проведение рефакторинга так же потребует проведения регрессионного тестирования.

Но тесты нужны не только для проверки функционала.
Их можно и нужно использовать для получения метрик качества кода: code-coverage.png

Composer ​

Много лет назад, это был просто пакетный менеджер, но сейчас Composer - полноценный помощник.

Команды и плагины, которые следят и проверяют вместо Вас:

  • composer normalize --diff - Плагин помогает стандартизировать структуру файла composer.json. С флагом "--dry-run" - делает только проверку
  • composer bump - Команда прописывает в composer.json установленную версию пакета, это упрощает проведение Code Review. С флагом "--dry-run" - делает только проверку
  • composer validate - Проверяет схему composer.json и синхронизацию с composer.lock
  • vendor/bin/composer-dependency-analyser - Инструмент помогает выявлять скрытые зависимости в проекте. Подсказывает, что используются зависимости, которые установлены не на прямую в composer.json, но требует настройки
  • composer outdated --strict --sort-by-age - Команда выводит список всех устаревших пакетов. Это помогает поддерживать зависимости в актуальном состоянии

Помогаторы ​

Editorconfig ​

EditorConfig — Одни Настройки для всех Редакторов/IDE - статья старая, но всё еще актуальная. А добавить файл с общими настройками редактора - простая задача.

В одном из проектов, где я принимал участие, ТехЛид пошел ещё дальше: сделал экспорт настроек из PHPStorm (там очень много всего) и запушил ".editorconfig" в Git. С тех пор наш код стал однообразен до безобразия. 😃

В проекте-примере я использовал базовый .editorconfig на весь проект.

PHPStorm ​

Эти плагины существенно ускоряют написание кода и, одновременно, уменьшают количество опечаток:

  • deep-assoc-completion - автодополнение ключей массивов
  • PHP Annotations - Подсказки для аннотаций и атрибутов
  • Makefile - Подсветка синтаксиса и запуск команд
  • Taskfile - Подсветка синтаксиса и запуск команд
  • Markdown - Я сторонник Docs-as-Code. Этот плагин - упрощенный WYSIWYG
  • .ignore - Подсветка синтаксиса для .gitignore и подобных файлов
  • Developer Tools - Куча мелких утилит, например, Base64 декодер.
  • Rector Support - Запуск Rector
  • Docker - У меня всё крутиться в Докере и этот плагин удобный интерфейс для работы с запущенными контейнерами

PS ​

Полный список команд с запуском проверок можно посмотреть в composer.json

Полезные ссылки:

А какие вы используете инструменты для проверки качества вашего кода?

Знаю, что есть разработчики предпочитающие использовать VSCode, приглашаю их поделиться в комментах своими подборками плагинов и практиками работы с PHP-проектами.