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