Совместное использование правил PHPCS между проектами и командами

Я хочу убедить вас, что даже если вы используете Pint или PHP-CS-Fixer напрямую, вам всё равно следует подумать о добавлении PHPCS в свой репертуар.

Определение правил PHPCS для нескольких проектов в команде утомительно, и между проектами обязательно произойдёт дрейф правил. Скорее всего, вы захотите внедрить единые правила в своих проектах, не задумываясь и не прилагая особых усилий.

В конце руководства вы узнаете, как создать набор правил, которые можно использовать для быстрой проверки ваших PHP-проектов.

В первой части серии Laravel: Используем PHP Codesniffer вы узнали как использовать PHP Codesniffer с Laravel проектами. В этом руководстве мы переместим набор правил, созданный в Laravel проекте в специальный пакет Composer.

Предпосылки

Вы можете спросить: Зачем использовать PHPCS, если есть Laravel Pint и PHP CS Fixer? Вместо того, чтобы рассматривать эти инструменты как конкурентов, рассматривайте их как дополняющие друг друга, каждый из которых предлагает уникальные ценные предложения и исправления по стилю кода. PHPCS — это линтер, а PHP CS Fixer — это фиксер.

На самом деле эти типы инструментов пересекаются: PHP CS Fixer имеет возможность линтинга при запуске ключом --dry-run. В PHPCS есть phpcbf — инструмент cli автоматически исправляющий нарушения стиля кода. Однако phpcbf исправляет не каждое правило.

Например, вы можете настроить PHPCS для обнаружения и сообщения о нарушениях длинны строки. Однако PHPCS не может автоматически исправить эти нарушения, поскольку инструмент не может определить, как вы хоте ли бы разбить длинные строки:

На скриншоте показана конфигурация длинны строки предупреждающая, когда длинна строки превышает 120 символов, и предупреждает о строках с длинной превышающей 80 символов, но всё ещё находящихся в пределах максимального порога в 120 символов. Это может быть полезно для поддержания работоспособности вашего кода и устранения таких вещей, как длина строки.

Начинаем

Нам нужно создать новый PHP пакет Composer для создания собственного набора правил, который можно будет использовать во всех своих проектах. Однако PHPCS необходимо знать об этих наборах правил, поэтому мы будем использовать пакет Composer Installer упрощающий установку стандартов кодирования через Composer.

Прежде чем начать давайте создадим пакет и инициализируем Git и Composer:

mkdir phpcs
cd phpcs
git init
composer init

Как только вы запустите composer init, Composer предложит вам задать такие вещи, как имя вашего пакета. По крайней мере, задайте имя пакета, необязательное описание, и далее используйте подсказки. Требуемые зависимости мы укажем в ручную, поэтому можно их не заполнять.

Для упрощения обнаружения PHPCS стандартов из пакетов composer нужно установить пакет PHP Codesniffer Composer Installer:

composer require --dev dealerdirect/phpcodesniffer-composer-installer

Установщик composer потребует, чтобы вы определили свойство type со значением phpcodesniffer-standard. Плагин Composer Installer ищет наборы правил, используя свойство type во всех установленных пакетах Composer вашего проекта.

В итоге ваш файл composer.json должен выглядеть примерно так:

{
    "name": "bitpressio/phpcs",
    "type": "phpcodesniffer-standard",
    "authors": [
        {
            "name": "Paul Redmond",
            "email": "paulrredmond@gmail.com"
        }
    ],
    "require-dev": {
        "dealerdirect/phpcodesniffer-composer-installer": "^1.0"
    },
    "config": {
        "allow-plugins": {
            "dealerdirect/phpcodesniffer-composer-installer": true
        }
    }
}

У нас есть всё необходимое для определения нашего пакета Composer, и всё, что нам нужно сделать, чтобы он заработал, — определить наш набор правил.

Определяем набор правил

Наш пакет Composer будет содержать файл ruleset.xml, который мы установим во всех наших проектах. Я назвал свой набор правил Bitpress, поэтому нужно создать папку для набора правил:

mkdir Bitpress
touch Bitpress/ruleset.xml

Мы создали набор правил в Первой части, поэтому добавьте следующее содержимое в releset.xml, заменив значения своим набором правил:

<?xml version="1.0"?>
<!-- @see https://pear.php.net/manual/en/package.php.php-codesniffer.annotated-ruleset.php -->
<ruleset name="Bitpress PHPCS Rules">

    <description>PHPCS ruleset for Bitpress</description>

    <!-- Use colors in output -->
    <arg name="colors"/>

    <!-- Show progress of the run -->
    <arg value="p"/>

    <!-- Show sniff codes in all reports -->
    <arg value="s"/>

    <!-- Our base rule: set to PSR12 -->
    <rule ref="PSR12">
        <exclude name="PSR12.Traits.UseDeclaration.MultipleImport" />
        <exclude name="PSR12.Operators.OperatorSpacing.NoSpaceBefore" />
        <exclude name="PSR12.Operators.OperatorSpacing.NoSpaceAfter" />
    </rule>

    <rule ref="Generic.Files.LineLength">
        <properties>
            <property name="lineLimit" value="80"/>
            <property name="absoluteLineLimit" value="120"/>
        </properties>
    </rule>

    <rule ref="PSR1.Methods.CamelCapsMethodName.NotCamelCaps">
        <exclude-pattern>tests/</exclude-pattern>
    </rule>

    <exclude-pattern>*/.phpstorm.meta.php</exclude-pattern>
    <exclude-pattern>*/_ide_helper.php</exclude-pattern>
    <exclude-pattern>*/*.blade.php</exclude-pattern>
    <exclude-pattern>*/autoload.php</exclude-pattern>
    <exclude-pattern>*/vendor/*</exclude-pattern>

</ruleset>

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

У нас есть всё необходимо для использования собственного набора правил! Как только вы опубликуете пакет Composer, вы можете установить его как --dev зависимость.

Настройка набора правил в проекте

Как только ваш пакет будет опубликован, как пакет Composer, вы можете установить его в проекте следующим образом:

composer require --dev bitpressio/phpcs

Зависимость Composer Installer запросит разрешение на выполнение кода для обнаружения и установки найденных стандартов в пакетах Composer. Выберите y для включения плагина:

Мы установили собственный набор правил и можем проверить это с помощью следующей команды:

vendor/bin/phpcs -i

The installed coding standards are
MySource, PEAR, PSR1, PSR2, PSR12, Squiz, Zend,
Bitpress and VariableAnalysis

Флаг --show-info может показать больше информации:

vendor/bin/phpcs --config-show

Using config file: /Users/paul/code/sandbox/bitpress-phpcs/vendor/squizlabs/php_codesniffer/CodeSniffer.conf

installed_paths: ../../bitpressio/phpcs,../../sirbrillig/phpcs-variable-analysis

Наконец, мы можем сделать наш набор правил набором по умолчанию следующей командой:

vendor/bin/phpcs --config-set default_standard Bitpress

Мы могли бы оставить так, чтобы каждый разработчик вручную устанавливал наш набор правил по умолчанию. Однако используя composer.json, мы можем сделать это автоматически следующим образом:

"scripts": {
    "post-package-install": "vendor/bin/phpcs --config-set default_standard Bitpress"
}

Если мы перезапустим vendor/bin/phpcs --config-show, то увидим следующее:

vendor/bin/phpcs --config-show
...
default_standard: Bitpress

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

Определение конфигурации набора правил проекта

Наш набор правил установлен в качестве стандарта по умолчанию. Однако запустив phpcs мы получим следующее сообщение:

vendor/bin/phpcs
ERROR: You must supply at least one file or directory to process.

Run "phpcs --help" for usage information

Хотя наш набор правил установлен по умолчанию, всё равно нужно предоставить конфигурацию для PHPCS с указанием какие файлы и папки следует анализировать. Создадим phpcs.xml в корне проекта:

<?xml version="1.0"?>
<!-- @see https://pear.php.net/manual/en/package.php.php-codesniffer.annotated-ruleset.php -->
<ruleset name="My App">
    <file>app</file>
    <file>tests</file>

    <rule ref="Bitpress"></rule>
</ruleset>

Если вы запустите phpcs в своём проекте (я проверял это в новом Laravel приложении), PHPCS будет анализировать файлы в app/ и tests/ и выводить предупреждения о длине строки. Настраивайте пути по своему желанию.

Заключение

В нашем бурном туре по наборам правил PHPCS мы опубликовали пакет composer, содержащий пользовательский набор правил, которым мы можем поделиться в нашей организации. Если вам нужен согласованный линтинг для нескольких проектов, надеюсь, этот подход вам пригодится.