Обмін правилами 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 має можливості лінування за допомогою функції --dry-run. PHPCS має інструмент phpcbf CLI, який автоматично виправляє порушення нюхання PHPCS. Однак 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 Installer:

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

Інсталятор композитора також вимагає, щоб ви визначили властивість типу за допомогою стандарту phpcodesniffer. Плагін Composer Installer шукає набори правил, використовуючи властивість 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, тому мені потрібно створити папку в моєму проекті, в якій буде розміщено набір правил:Ми створили набір правил у Частина 1 цієї серії, тому додайте наступний вміст до набору правил.xml, замінивши значення на те, що ви назвали своїм набором правил:

mkdir Bitpress
touch Bitpress/ruleset.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.

У нас є все необхідне, щоб почати користуватися нашим користувацьким набором правил! Після того, як ви опублікуєте свій композиторський пакет, ви можете вимагати його як залежність --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
...
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 буде лінтувати файли в додатку / і тести / і повинен вивести деякі попередження про довжину рядка. Сміливо налаштовуйте ці шляхи на свій смак.

Підведення підсумків

Під час нашого бурхливого туру по правилах PHPCS ми опублікували пакет композитора, що містить спеціальний набір правил, яким ми можемо поділитися в нашій організації. Якщо ви хочете послідовного розміщення в кількох проектах, сподіваємось, цей підхід може стати в нагоді.