Za pomocą kodów php z laravelem

Począwszy od Laravel 9, doskonały Laravel Pint jest dostarczany w pakiecie z nową instalacją Laravel. Uwielbiam Pinta, a dla większości ludzi wystarczy używać go do formatowania w stylu kodu. Przed Laravel Pint wolałem kombinację PHP CS Fixer i PHP Codesniffer - oba są doskonałe w tandemie i oferują unikalne reguły, które mogą pomóc w egzekwowaniu stylu kodu.

Styl długości linii jest jednym z przykładów, w którym PHP Codesniffer może uzupełniać narzędzia takie jak PHP CS Fixer, i możemy użyć obu, aby pomóc programistom trzymać się spójnego stylu kodu. Jeśli używasz PSR-12, sekcja Linie zawiera następujące informacje o długości linii:

NIE MOŻE być sztywnego limitu długości linii.

Miękki limit długości linii MUSI wynosić 120 znaków. Linie NIE POWINNY być dłuższe niż 80 znaków

; linie dłuższe niż te POWINNY być podzielone na wiele kolejnych wierszy o długości nie większej niż 80 znaków każda.

Nasze narzędzia CI mogą egzekwować zarówno miękkie, jak i twarde ograniczenia długości linii, ale sposób, w jaki interpretuję PSR-12, jest taki, że PHP Codesniffer powinien nas ostrzegać i nie zwracać żadnych błędów dla linii > długości 80. Omówimy to w dalszej części artykułu.

Popracujmy nad skonfigurowaniem PHP Codesniffer w nowym projekcie Laravel, a następnie w kolejnych samouczkach nauczymy się, jak stworzyć niestandardowy standard PHP Codesniffer, który możemy udostępnić we wszystkich naszych projektach.

Po drodze pokażę ci kilka ustawień konfiguracyjnych, które lubię ustawiać, aby jak najlepiej wykorzystać PHP Codesniffer podczas programowania.

Konfiguracja

Pierwszą rzeczą, którą zrobimy, jest stworzenie przykładowego projektu, abyś mógł zobaczyć, jak włączyć PHP Codesniffer z Laravelem od zera:

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

Flaga git zainstaluje nową aplikację Laravel, zainicjuje git i zatwierdzi wszystko do kontroli wersji. To pozostawia nam czystą kartę, aby zobaczyć zmiany, które wprowadzamy podczas tego samouczka.

Następnie zainstalujmy PHP Codesniffer jako zależność programistyczną:

composer require --dev squizlabs/php_codesniffer

Uwaga: W chwili pisania wymagane polecenie instaluje wersję ^3.7, ale twoja wersja może się nieznacznie różnić, co nie stanowi problemu.

Jeśli uruchomisz phpcs z wiersza poleceń, zobaczysz, że chce on określić ścieżkę:

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

Run "phpcs --help" for usage information

Nie martw się, mamy zamiar dodać plik konfiguracyjny, aby określić, które ścieżki PHPCS powinny zawierać (i wykluczać), ale jeśli uruchomisz go z domyślnym zestawem reguł (Pear), otrzymasz kilka błędów z domyślną instalacją 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
--------------------------------------------------------------------------------

Jeśli sprawdzisz kod zakończenia, zobaczysz, że błędy powodują wyjście PHPCS z kodem niezerowym:

$ echo $?
2

Chcę być jasny: te błędy nie wynikają z tego, że nasz kod ma złe formatowanie (wręcz przeciwnie), ale dlatego, że używamy domyślnego standardu PEAR, którego Laravel nie przestrzega po wyjęciu z pudełka.

Przyjrzyjmy się użyciu innego standardu i utworzeniu pliku konfiguracyjnego.

Poznawanie narzędzi wiersza poleceń

Zanim dodamy plik konfiguracyjny do naszego projektu, zobaczmy, jak ta sama konfiguracja będzie wyglądać przy użyciu wiersza poleceń. Wiemy, że nie chcemy używać standardu PEAR, więc najpierw uruchom nasze polecenie PHPCS z wbudowanym standardem PSR-12:

vendor/bin/phpcs --standard=PSR12 app

Jeśli przyjrzysz się uważnie wynikowi, zauważysz, że standard PSR12 dla PHP Codesniffer chce naprawić pewne odstępy wokół połączonych ciągów:

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 oznacza, że możemy naprawić te sniffy automatycznie (nie wszystkie sniffy PHP Codsniffer są automatycznie naprawialne) za pomocą kosza phpcbf, który jest dostarczany z Codesniffer. Dojdziemy do tego za chwilę.

Najpierw zobaczmy kilka innych flag poleceń, których wolę używać. Gdy zaczniesz używać PHP Codesniffer w rozwoju i CI, zauważyłem, że pełna nazwa sniffa nie jest widoczna. Możesz dostosować ten wąch, zignorować go w określonej linii itp.

Aby zawsze widzieć pełny wąchan w wierszu poleceń, możesz użyć flagi "-s":

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

Oto przykład tego, jak wygląda wyjście z pełnym wąchaniem

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

:Możesz zobaczyć PSR12. Operatory.OperatorSpacing.NoSpaceBefore sniff znalezione w powyższym przykładzie. Jeśli chcemy zignorować to wąchanie w pliku Kernel.php, możemy dodać to do pliku app/Console/Kernel.php wokół linii 28:

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

Jeśli ponownie uruchomimy polecenie - tym razem dla pliku Kernel.php - widzimy, że reguła NoSpaceAfter jest wyłączona dla tej linii, ale nadal otrzymujemy błąd NoSpaceBefore:

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

Możemy wyłączyć wiele reguł dla danego zestawu wierszy, oddzielając przecinki w następujący sposób:

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

Na koniec cofnijmy wszystkie zmiany wprowadzone w pliku app/Console/Kernel.php. Odkryjesz, że te dwie reguły, których używaliśmy jako przykładu, bezpośrednio kolidują z Laravel Pint, który oczekuje spacji przed i po.

Najpierw automatycznie naprawmy powyższe węszenie za pomocą 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
----------------------------------------------------------------------------------------------

Po uruchomieniu tego uruchom Laravel Pint, aby zobaczyć, że robi odwrotnie niż to, co PHP Codesniffer naprawił automatycznie:

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

Aby móc używać obu narzędzi podczas programowania i w środowiskach CI, musimy wybrać styl i wymusić go za pomocą jednego narzędzia i wyłączyć go z drugiego. Wolę automatyczne poprawki od Pinta, więc wyłączam konkurencyjny Sniff w PHP Codesniffer.

Plik

konfiguracyjny Rozwiążmy konflikt między Pint i Codesniffer przez utworzenie pliku konfiguracyjnego. W aplikacji zazwyczaj tworzę plik phpcs.xml, ale jeśli planujesz pozwolić innym używać twojej aplikacji jako punktu wyjścia, możesz rozważyć użycie phpcs.xml.dist. Stwórzmy go jako 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>

Widać, że dodałem nasz argument -s do config, więc wszystkie raporty pokazują kody wąchania. Kierujemy również aplikacje i katalogi testowe, ale możesz skonfigurować inne katalogi w projekcie, które chcesz sprawdzić w Codesniffer.

Wyłączyliśmy wąchanie odstępów między operatorami, więc Pint powinien być zadowolony, a PHP Codesniffer zignoruje teraz te reguły.

Dostosowaliśmy również regułę długości linii, używając języka PSR-12 jako naszego przewodnika po limicie linii i maksymalnej wartości. Te węszenie zgłasza się jako ostrzeżenia, więc po uruchomieniu tego narzędzia w CI należy upewnić się, że ostrzeżenia są pomijane lub że CI nadal przechodzi z ostrzeżeniami. Ostrzeżenia mają na celu pomóc programiście naprawić długości linii w rozwoju.

Wreszcie, wąchanie NotCamelCaps jest wykluczone w folderze testów, ponieważ lubię pisać testy PHPUnit z wężem case:

/* @test */
public function it_does_something_awesome()

Teraz możemy uruchomić phpcs bez żadnych argumentów, a on odbierze nasz plik konfiguracyjny. Powinny być wyświetlane tylko ostrzeżenia o długości linii i wielokrotnym importowaniu.

vendor/bin/phpcs

Innym naruszeniem, które zauważysz, jest sniff MultipleImport, który wynika z tej linii, na przykład:

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

Możesz wyłączyć ten sniff, jeśli chcesz, lub możesz go automatycznie naprawić (za pomocą naszego pliku konfiguracyjnego) za pomocą polecenia phpcbf bin:

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

Wnioski

Omówiliśmy sporo terenu, ale powinieneś być w stanie zacząć używać PHP Codesniffer od zera z Laravel. Może to być doskonały dodatek, jeśli chcesz celować w niektóre z konkretnych reguł, których PHP CS Fixer nie wykonuje, a ja wyposażyłem cię w sposób wyłączania sprzecznych reguł lub reguł, które chcesz wyłączyć.