Dzielenie się zasadami PHPCS w różnych projektach i zespołach

PHPCS to narzędzie interfejsu wiersza polecenia typu open source, które wykrywa naruszenia stylu kodu zdefiniowanego standardu kodowania, a także zapewnia automatyczne poprawki dla reguł możliwych do naprawienia. Chcę Cię przekonać, że nawet jeśli używasz bezpośrednio Pint lub PHP-CS-Fixer, powinieneś rozważyć dodanie PHPCS do swojego repertuaru.

Definiowanie reguł PHPCS w wielu projektach w środowisku zespołowym jest żmudne, a dryf reguł musi się zdarzyć między projektami. Prawdopodobnie będziesz chciał egzekwować spójne reguły w swoich projektach bez większego zastanowienia i wysiłku.

Na końcu tego samouczka dowiesz się, jak utworzyć zestaw reguł organizacji, którego możesz użyć do szybkiego lintowania wszystkich projektów PHP.

W części 1 tej serii nauczyłeś się, jak < href = "https://laravel-news.com/php-codesniffer-with-laravel" > Użyj PHP Codesniffer z projektami Laravel. Ten samouczek przeniesie zestaw reguł, który utworzyliśmy w projekcie Laravel, do dedykowanego pakietu Composer.

Kontekst

Możesz zapytać: "dlaczego miałbym używać PHPCS, skoro mamy Laravel Pint i PHP CS Fixer?" Zamiast traktować te narzędzia jako konkurencję, rozważ je jako narzędzia uzupełniające, z których każde zapewnia unikalne, cenne sugestie i poprawki stylu kodu. PHPCS jest linterem, a PHP-CS-Fixer jest fixerem.

Rzeczywiście, tego typu narzędzia nakładają się na siebie: PHP-CS-Fixer ma możliwości lintingu za pomocą funkcji --dry-run. PHPCS ma narzędzie phpcbf CLI, które automatycznie naprawia naruszenia PHPCS. Jednak phpcbf nie naprawia każdej dostępnej reguły.

Na przykład można skonfigurować PHPCS do wykrywania i zgłaszania naruszeń długości linii; jednak PHPCS nie może automatycznie naprawić tych naruszeń, ponieważ narzędzie nie może określić, w jaki sposób chcesz podzielić długie linie:

Zrzut ekranu ilustruje konfigurację długości linii, która ostrzega, gdy linia przekracza 120 znaków i ostrzega o liniach, które przekraczają 80 znaków, ale nadal mieszczą się w maksymalnym progu 120 znaków. Może to być przydatne, aby utrzymać kod w dobrej kondycji i poprawić takie rzeczy, jak długość linii.

Pierwsze kroki Musimy utworzyć

nowy pakiet PHP-Composer, aby utworzyć niestandardowy zestaw reguł, którego można ponownie używać we wszystkich projektach. PHPCS musi jednak wiedzieć o tych zestawach reguł, więc użyjemy pakietu < href = "https://github.com/PHPCSStandards/composer-installer" > Composer Installer, który ułatwia instalację standardów kodowania za pomocą Composera.

Zanim do tego dojdziemy, utwórzmy pakiet i zainicjujmy Git i Composer:

mkdir phpcs
cd phpcs
git init
composer init

Po uruchomieniu init composer poprosi Cię o zdefiniowanie takich rzeczy, jak nazwa pakietu. Przynajmniej wypełnij nazwę pakietu, opcjonalnie opis i zakończ monity. Będziemy wymagać zależności ręcznie, więc nie martw się o ich interaktywną instalację.

Aby ułatwić wykrywanie standardów PHPCS z pakietów kompozytora, musimy teraz zainstalować pakiet Composer Installer:

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

Instalator kompozytora wymaga również zdefiniowania właściwości type za pomocą phpcodesniffer-standard. Wtyczka Composer Installer wyszukuje zestawy reguł przy użyciu właściwości type we wszystkich pakietach Composer zainstalowanych w projekcie.

Ostatecznie plik composer.json powinien wyglądać mniej więcej tak: Mamy wszystko, czego potrzebujemy, aby zdefiniować nasz

{
    "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
        }
    }
}

pakiet Composer, a wszystko, co musimy zrobić, aby to działało, to zdefiniować nasz zestaw reguł.

Definiowanie zestawu reguł

Nasz pakiet Composer będzie zawierał nasz zestaw reguł.xml plik, który zainstalujemy we wszystkich naszych projektach. Nazwałem mój zestaw reguł Bitpress, więc muszę utworzyć folder w moim projekcie, który będzie zawierał ruleset:Stworzyliśmy zestaw reguł w Część 1 tej serii, więc dodaj następującą zawartość do ruleset.xml, zastępując wartości dla tego, co nazwałeś swoim zestawem reguł:

mkdir Bitpress
touch Bitpress/ruleset.xml

Nasz zestaw reguł

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

nie będzie zawierał żadnych niestandardowych sniffów, ale zdefiniujemy naszą preferowaną konfigurację w oparciu o wbudowany zestaw reguł PSR12.

Mamy wszystko, czego potrzebujemy, aby zacząć korzystać z naszego niestandardowego zestawu reguł! Po opublikowaniu pakietu composer można go wymagać jako zależności --dev.

Konfigurowanie zestawu reguł w projekcie Po opublikowaniu pakietu jako pakietu Composer, możesz zainstalować go w projekcie

w następujący sposób:

composer require --dev bitpressio/phpcs

Zależność Composer Installer poprosi o pozwolenie na wykonanie kodu, aby mógł wykryć i zainstalować znalezione standardy w pakietach Composera. Wybierz y, aby włączyć wtyczkę:

W tym momencie zainstalowaliśmy nasz niestandardowy zestaw reguł i możemy to zweryfikować za pomocą następującego polecenia:

vendor/bin/phpcs -i
The installed coding standards are
MySource, PEAR, PSR1, PSR2, PSR12, Squiz, Zend,
Bitpress and VariableAnalysis

Flaga --show-info może pokazać nam więcej informacji:

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

Na koniec możemy ustawić nasz zestaw reguł jako domyślny za pomocą następujących elementów:

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

Możemy sprawić, że każdy programista ręcznie ustawi nasze zestawy reguł jako domyślne; jednak za pomocą composer.json możemy go automatycznie wyzwolić za pomocą następujących czynności:

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

Jeśli ponownie uruchomimy nasze polecenie, nasz zestaw reguł powinien być teraz domyślny:

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

Jesteśmy prawie gotowi, ale mamy kilka drobnych poprawek do wprowadzenia, aby zakończyć naszą instalację.

Definiowanie konfiguracji zestawu reguł projektu

Mamy zainstalowany i ustawiony nasz zestaw reguł jako domyślny standard. Jeśli jednak uruchomimy phpcs, otrzymamy następujący komunikat:

vendor/bin/phpcs
ERROR: You must supply at least one file or directory to process.
Run "phpcs --help" for usage information

Chociaż nasz zestaw reguł jest domyślny, nadal musimy zapewnić konfigurację, aby poinstruować PHPCS, które pliki i foldery mają lintować. Stwórzmy phpcs.xml w katalogu głównym projektu:

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

Jeśli uruchomisz phpcs w swoim projekcie (przetestowałem to w nowej aplikacji Laravel), PHPCS będzie lint pliki w app/ i testach / i powinien wygenerować ostrzeżenia o długości linii. Możesz skonfigurować te ścieżki według własnych upodobań.

Podsumowanie

Podczas naszej szalonej wycieczki po zestawach reguł PHPCS opublikowaliśmy pakiet kompozytora zawierający niestandardowy zestaw reguł, który możemy udostępnić w całej naszej organizacji. Jeśli chcesz spójnego linowania w wielu projektach, miejmy nadzieję, że to podejście może się przydać.