techart / php-tooling
Набор инструментов для поддержки PHP-проектов
Requires (Dev)
- php: ^8.1
- dealerdirect/phpcodesniffer-composer-installer: ^1.0
- phpunit/phpunit: ^10.3
- sirbrillig/phpcs-variable-analysis: ^2.11
- squizlabs/php_codesniffer: ^3.7
README
Когда несколько программистов работают на одном большом проекте, возникают проблемы – у каждого программиста свой стиль написания кода, свое понимание того как нужно реализовывать различные участки программы. Из-за того что все пишут так как они этого хотят, другим разработчикам сложно быстро вовлечься в процесс работы в новом для них проекте.
Даже когда программист пытается следовать, общим для компании, правилам написания (https://webtech.techart.ru/code-style-php/), то всё равно играет человеческий фактор и где-то обязательно будет не соблюдение правил.
Чтобы оптимизировать этот процесс, был создан пакет php-tooling (https://packagist.org/packages/techart/php-tooling), который включает в себя функционал линтера. Линтер анализирует код проекта и показывает ошибки и предупреждения в тех местах проекта, которые не соответствуют заданым правилам.
Результат работы линтера выглядит так:
Установка
Пакет php-tooling должен существовать отдельно от вашего основного вендора на сайте. Установить его можно с помощью следующей команды:
vcomposer create-project techart/php-tooling
Данная команда по текущему пути создаст папку с названием пакета и склонирует туда его файлы, а так же применит автоматически composer install. (Не забываем добавить папку vendor этого пакета в .gitignore).
Если php-tooling уже существует, то будет достаточно собрать vendor-пакеты с помощью vcomposer install
Пути установки
Bitrix
В bitrix проектах пакет нужно ставить в папку local.
TAO3
В tao3 проектах пакет нужно ставить в корневую папку проекта.
Использование
Bitrix
В bitrix проектах обычно по умолчанию ставится наш пакет bitrix.tao (https://packagist.org/packages/techart/bitrix.tao). Данный пакет имеет специальную cli команду:
vphp cli.php php_lint_run
Эта команда запустит процесс анализа кода от папки www.
Про функционал cli-команд можно почитать тут: https://webtech.techart.ru/bitrix-tao/cli/.
TAO3
Для tao3 проектов существует специальная artisan-команда:
vphp artisan php-lint:run
Про artisan команды можно почитать в официальной документации Laravel: https://laravel.com/docs/9.x/artisan
Остальные проекты
Нужно из папки php-tooling выполнить следующую команду:
vphp ./vendor/bin/phpcs <Путь начала сканирования> --colors
Необходимость вызова команды непосредственно из папки обусловлено тем, что в ином месте вызова будут использоваться стандартные правила линтера.
Правила линтера
В папке php-tooling содержится файл phpcs.xml. Он был создан на основе правил PSR12 (https://www.php-fig.org/psr/psr-12/), это грубо говоря расширенный PSR2, которому мы следуем(почти). В этом файле добавляются правила и исключения. Править этот файл лично крайне не рекомендуется (по крайней мере для стандартных проектов на bitrix и tao3), он должен быть общим для всех, поэтому если есть необходимость добавления какого-то исключения или правила, то следует сообщить об этом вышестоящему по должности, как правило - тимлиду.
Исключения
Для bitrtx проектов обычное дело видеть файлы типа .section.php, в которых объявляется массив, но не используется в рамках этого файла. Линтер соответственно об этом скажет. Чтобы избежать таких ситуаций, существует функционал исключения: Для игнорирования строчки пишем над строчкой следующее:
// phpcs:ignore
Данный комментарий скажет линтеру игнорировать следующую строку.
Для исключения целого файла есть следующая команда:
// phpcs:ignoreFile
Пишется в начало файла.
Эти команды существуют только для безвыходных ситуаций. Какие-то спорные ошибки или ситуации стоит обсуждать и в процессе дополнять файл правил.
Использование линтера в gitlab-ci
Эта часть находится в стадии разработки На данный момент можно создать задачу для gitlab-ci в таком виде:
php_lint_test:
stage: test
variables:
CODE_SNIFFER_PATH: <Путь до php-tooling>
tags:
- docker
- php81 // Тег php-ранера, который используется на проекте
- techart
script:
- |
cd $CODE_SNIFFER_PATH && pwd
composer install
php ./vendor/bin/phpcs ../ --colors
Если линтер найдёт ошибки, процесс выкладки остановится с ошибкой.
PHPUnit тестирование
Подробнейшая документация по написанию unit тестов тут: https://docs.phpunit.de/en/10.3/writing-tests-for-phpunit.html#asserting-return-values
Скрипт для запуска всех тестов из папки /tests/: composer phpunit:run