Обмен правилами PHPCS между проектами и командами

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

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

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

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

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

Действительно, эти типы инструментов перекрываются: PHP-CS-Fixer имеет возможности linting с использованием функции --dry-run. PHPCS имеет инструмент phpcbf CLI, который автоматически исправляет нарушения PHPCS sniff. Тем не менее, 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, нам теперь нужно установить пакет Composer Installer:

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

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

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

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

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

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

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

mkdir Bitpress
touch Bitpress/ruleset.xml

Мы создали набор правил в Part 1 этой серии, поэтому добавьте следующее содержимое в набор правил.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

The Зависимость установщика компоновщика запрашивает разрешение на выполнение кода, чтобы она могла обнаруживать и устанавливать найденные стандарты в пакетах 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
...
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 будет lint файлы в приложении / и тестах / и должен выводить некоторые предупреждения о длине строки. Не стесняйтесь настраивать эти пути по своему вкусу.

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