Використання PHP Codesniffer з Laravel

Станом на Laravel 9, чудовий Laravel Pint поставляється в комплекті з новою установкою Laravel. Я люблю Pint, і для більшості людей достатньо використовувати його для всього форматування в стилі коду. До Laravel Pint я віддав перевагу поєднанню PHP CS Fixer і PHP Codesniffer — обидва вони чудові в тандемі та пропонують унікальні правила, які можуть допомогти забезпечити дотримання стилю коду.

Стиль довжини рядка є одним із прикладів того, де PHP Codesniffer може доповнювати такі інструменти, як PHP CS Fixer, і ми можемо використовувати обидва, щоб допомогти розробникам дотримуватися послідовного стилю коду. Якщо використовується PSR-12, розділ "Лінії" містить таку інформацію про довжину лінії:

НЕ ПОВИННО бути жорсткого обмеження довжини лінії.

М'яке обмеження довжини рядка ПОВИННО становити 120 символів.

Рядки НЕ ПОВИННІ бути довшими за 80 символів; рядки, довші за цей, ПОВИННІ бути розділені на кілька наступних рядків не більше 80 символів кожен.

Наші інструменти CI можуть застосовувати як м'які, так і жорсткі межі довжини лінії, але спосіб, яким я інтерпретую PSR-12, полягає в тому, що PHP Codesniffer повинен попереджати нас і не повертати жодних помилок для рядків довжиною > 80. Про це ми і поговоримо далі в статті.

Давайте попрацюємо над налаштуванням PHP Codesniffer у новому проекті Laravel, а потім у наступних підручниках ми дізнаємося, як створити власний стандарт PHP Codesniffer, яким ми можемо поділитися у всіх наших проектах.

По дорозі я покажу вам деякі налаштування конфігурації, які я люблю встановлювати, щоб отримати максимальну віддачу від PHP Codesniffer під час розробки.

Налаштування Перше,

що ми зробимо, це створимо приклад проекту, щоб ви могли побачити, як включити PHP Codesniffer з Laravel з нуля:

laravel new phpcs-part-1 --git
cd phpcs-part-1

Прапор git встановить нову програму Laravel, ініціалізує git і зобов'яже все контролювати версію. Це залишає нам чистий шифер, щоб побачити зміни, які ми вносимо під час цього підручника.

Далі давайте встановимо PHP Codesniffer як залежність від розробки:

composer require --dev squizlabs/php_codesniffer

Примітка: На момент написання статті необхідна команда встановлює версію ^3.7, але ваша версія може трохи відрізнятися, що не викликає занепокоєння. Якщо ви запустите

phpcs з командного рядка, ви побачите, що він хоче, щоб ви вказали шлях:

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

Run "phpcs --help" for usage information

Не хвилюйтеся, ми збираємося додати файл конфігурації, щоб вказати, які шляхи PHPCS повинен включати (і виключити), але якщо ви запустите його з набором правил за замовчуванням (Pear), ви отримаєте купу помилок з установкою Laravel за замовчуванням:

$ vendor/bin/phpcs -v app
Registering sniffs in the PEAR standard... DONE (28 sniffs registered)
....
FILE: /Users/paul/code/sandbox/phpcs-part-1/app/Providers/AppServiceProvider.php
--------------------------------------------------------------------------------
FOUND 2 ERRORS AFFECTING 2 LINES
--------------------------------------------------------------------------------
 2 | ERROR | Missing file doc comment
 7 | ERROR | Missing doc comment for class AppServiceProvider
--------------------------------------------------------------------------------

Якщо ви перевірите вихідний код, ви побачите помилки, через які PHPCS виходить з ненульовим кодом:

$ echo $?
2

я хочу бути зрозумілим: ці помилки не тому, що наш код має погане форматування (зовсім навпаки), а тому, що ми використовуємо стандарт PEAR за замовчуванням, якого Laravel не дотримується з коробки.

Давайте розглянемо використання іншого стандарту і створення конфігураційного файлу. Вивчення інструментів командного рядка

Перш ніж ми додамо файл конфігурації до нашого проекту, давайте подивимося, як буде виглядати така ж конфігурація за допомогою командного рядка. Ми знаємо, що не хочемо використовувати стандарт PEAR, тому давайте спочатку запустимо нашу команду PHPCS із вбудованим стандартом PSR-12:

vendor/bin/phpcs --standard=PSR12 app

Якщо ви уважно подивитеся на вихід, ви помітите, що стандарт PSR12 для PHP Codesniffer хоче виправити деякі інтервали навколо об'єднаних рядків:

FILE: /Users/paul/code/sandbox/phpcs-part-1/app/Console/Kernel.php
----------------------------------------------------------------------
FOUND 2 ERRORS AFFECTING 1 LINE
----------------------------------------------------------------------
 28 | ERROR | [x] Expected at least 1 space before "."; 0 found
 28 | ERROR | [x] Expected at least 1 space after "."; 0 found
----------------------------------------------------------------------
PHPCBF CAN FIX THE 2 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------

X означає, що ми можемо автоматично виправляти ці нюхання (не всі нюхачі PHP Codsniffer автоматично можна виправити) за допомогою урни phpcbf, яка поставляється з Codesniffer. Ми дійдемо до цього за секунду.

Для початку давайте подивимося на кілька інших командних прапорців, які я вважаю за краще використовувати. Як тільки ви почнете використовувати PHP Codesniffer в розробці та CI, я помічаю, що повна назва нюхача не очевидна. Можливо, ви захочете налаштувати цей нюх, проігнорувати його на певному рядку тощо.

Щоб завжди бачити повний нюх у командному рядку, ви можете використовувати прапорець '-s':

vendor/bin/phpcs -s --standard=PSR12 app

Ось приклад того, як виглядає вихід з повним нюхом:

FILE: /Users/paul/code/sandbox/phpcs-part-1/app/Console/Kernel.php
----------------------------------------------------------------------------------------------------------------
FOUND 2 ERRORS AFFECTING 1 LINE
----------------------------------------------------------------------------------------------------------------
 28 | ERROR | [x] Expected at least 1 space before "."; 0 found
    |       |     (PSR12.Operators.OperatorSpacing.NoSpaceBefore)
 28 | ERROR | [x] Expected at least 1 space after "."; 0 found
    |       |     (PSR12.Operators.OperatorSpacing.NoSpaceAfter)
----------------------------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 2 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------------------------------------------------

Ви можете побачити PSR12. Operators.OperatorSpacing.NoSpaceBefore нюхати можна знайти в наведеному вище прикладі. Якщо ми хочемо проігнорувати цей нюх у файлі ядра.php ми можемо додати це до файлу програми / консолі / ядра.php приблизно в рядку 28: Якщо ми повторно запустимо команду - цього разу для файлу

// phpcs:disable PSR12.Operators.OperatorSpacing.NoSpaceAfter
$this->load(__DIR__.'/Commands');
// phpcs:enable

ядра.php - ми можемо побачити, що правило NoSpaceAfter вимкнено для цього рядка, але ми все одно отримуємо помилку NoSpacePre:

vendor/bin/phpcs -s --standard=PSR12 app/Console/Kernel.php
FILE: /Users/paul/code/sandbox/phpcs-part-1/app/Console/Kernel.php
----------------------------------------------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------------------------------------------------
 29 | ERROR | [x] Expected at least 1 space before "."; 0 found
    |       |     (PSR12.Operators.OperatorSpacing.NoSpaceBefore)
----------------------------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------------------------------------------------

Ми можемо вимкнути кілька правил для заданого набору рядків, розділивши комами нюхачі таким чином:

// phpcs:disable PSR12.Operators.OperatorSpacing.NoSpaceAfter, PSR12.Operators.OperatorSpacing.NoSpaceBefore
$this->load(__DIR__.'/Commands');
// phpcs:enable

Нарешті, давайте повернемо всі зміни, внесені до файлу програми/консолі/ядра.php Ви виявите, що ці два правила, які ми використовували як приклад, прямо суперечать Ларавелю Пінту, який очікує пробіли до і після.

По-перше, давайте автоматично виправимо вищезазначені нюхання за допомогою phpcbf:

vendor/bin/phpcbf --standard=PSR12 app

PHPCBF RESULT SUMMARY
----------------------------------------------------------------------------------------------
FILE                                                                          FIXED  REMAINING
----------------------------------------------------------------------------------------------
/Users/paul/code/sandbox/phpcs-part-1/app/Models/User.php                     1      0
/Users/paul/code/sandbox/phpcs-part-1/app/Http/Controllers/Controller.php     1      0
/Users/paul/code/sandbox/phpcs-part-1/app/Console/Kernel.php                  2      0
----------------------------------------------------------------------------------------------
A TOTAL OF 4 ERRORS WERE FIXED IN 3 FILES
----------------------------------------------------------------------------------------------

Після запуску давайте запустимо Laravel Pint, щоб побачити, як він робить зворотний бік того, що PHP Codesniffer виправив автоматично:

$ vendor/bin/pint
  FIXED  54 files,    1 style issue fixed
  ✓ app/Console/Kernel.php   concat_space

Щоб ми могли використовувати обидва інструменти під час розробки та в середовищах CI, нам потрібно вибрати стиль і застосувати його одним інструментом і відключити від іншого. Я віддаю перевагу автоматичним виправленням з Pint, тому відключаю конкуруючий Sniff в PHP Codesniffer.

Файл конфігурації

Давайте вирішимо конфлікт між Pint і Codesniffer шляхом створення конфігураційного файлу. У програмі я зазвичай створюю файл phpcs.xml, але якщо ви плануєте дозволити іншим використовувати вашу програму як відправну точку, ви можете розглянути можливість використання phpcs.xml.dist. Давайте створимо його як phpcs.xml:

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

    <description>PHPCS ruleset for Example app.</description>

    <file>tests</file>
    <file>app</file>

    <!-- 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.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>

</ruleset>

Ви можете побачити, що я додав наш аргумент -s до конфігурації, тому всі звіти показують коди нюху. Ми також націлюємося на програми та тестуємо каталоги, але не соромтеся налаштовувати інші каталоги у вашому проекті, які ви хочете перевірити Codesniffer.

Ми відключили інтервали між операторами, тому Pint повинен бути щасливий, і PHP Codesniffer тепер проігнорує ці правила.

Ми також налаштували правило довжини лінії, використовуючи мову в PSR-12 як наш посібник для обмеження лінії та максимального значення. Ці нюхачі повідомляють як попередження, тому, коли ви запускаєте цей інструмент у CI, ви захочете переконатися, що або попередження придушені, або що CI все ще проходить з попередженнями. Попередження покликані допомогти вам, розробнику, виправити довжину ліній в розробці.

Нарешті, нюхання NotCamelCaps виключено в папці тестів, тому що мені подобається писати тести PHPUnit зі зміїним корпусом:

/* @test */
public function it_does_something_awesome()

Тепер ми можемо запускати phpcs без будь-яких аргументів, і він підбере наш файл конфігурації. Ви повинні бачити лише попередження про довжину рядка та кілька імпортів.

vendor/bin/phpcs

Ще одним порушенням, яке ви помітите, є MultipleImport sniff, який пов'язаний з цим рядком, наприклад:

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
    // ...
}

Не соромтеся відключити цей нюх, якщо хочете, або ви можете автоматично виправити його (за допомогою нашого файлу конфігурації) за допомогою бін командного рядка phpcbf:

vendor/bin/phpcbf
.........F..........F.. 23 / 23 (100%)

PHPCBF RESULT SUMMARY
----------------------------------------------------------------------------------------------
FILE                                                                          FIXED  REMAINING
----------------------------------------------------------------------------------------------
/Users/paul/code/sandbox/phpcs-part-1/app/Models/User.php                     1      0
/Users/paul/code/sandbox/phpcs-part-1/app/Http/Controllers/Controller.php     1      0
----------------------------------------------------------------------------------------------
A TOTAL OF 2 ERRORS WERE FIXED IN 2 FILES
----------------------------------------------------------------------------------------------

Висновок

Ми охопили зовсім небагато землі, але ви повинні мати можливість почати використовувати PHP Codesniffer з нуля з Laravel. Це може бути відмінним доповненням, якщо ви хочете орієнтуватися на деякі конкретні правила, які PHP CS Fixer не виконує, і я надав вам можливість вимкнути суперечливі правила або правила, які ви хочете відключити.