Poprawa jakości kodu z narzędziem PHP_CodeSniffer

17.03.2021

Kod pisany według standardów pozwala na przyspieszenie tworzenia projektu. Jest łatwiej rozszerzalny i czytelniejszy, dzięki czemu nowe osoby w projekcie mogą się szybciej wdrożyć i dostarczać optymalne rozwiązania. Społeczność PHP stale dąży do poprawy jakości kodu. Na przestrzeni lat powstały narzędzia wspomagające w pisaniu kodu zgodnego ze standardami. W tym tekście przedstawię jedno z nich: PHP_CodeSniffer.

Zapoznam Cię również z modułem Drupala Coder, który zawiera standardy pisania kodu dla Drupala. Można go również wykorzystać przy automatycznej poprawie kodu z użyciem phpcbf.

PHP CodeSniffer

PHP_CodeSniffer pomaga w utrzymaniu czystego, zgodnego ze standardami kodu. Narzędzie składa się z dwóch skryptów:

phpcs - tokenizuje kod PHP, JS oraz CSS i wykrywa odstępstwa od zdefiniowanego standardu pisania kodu,
phpcbf - automatycznie poprawia kod według określonych zasad.

Do poprawnego działania narzędzia wymagany jest PHP w wersji 5.4.0 lub wyższej.

Instalacja

PHP_CodeSniffer możemy zainstalować przy użyciu Composera, cURLa lub Wgeta. Rekomenduję instalację przy użyciu Composera, jednak warto zaznaczyć że istnieje również możliwość instalacji przy użyciu Composera wewnątrz kontenera Dockera, jeśli używasz Dockera, skorzystaj z tej metody instalacji.

Composer

composer global require "squizlabs/php_codesniffer=*"

cURL

curl -OL https://squizlabs.github.io/PHP_CodeSniffer/phpcs.phar
curl -OL https://squizlabs.github.io/PHP_CodeSniffer/phpcbf.phar

Wget

wget https://squizlabs.github.io/PHP_CodeSniffer/phpcs.phar
wget https://squizlabs.github.io/PHP_CodeSniffer/phpcbf.phar

Po pobraniu pakietów możemy je przetestować.

Composer

Możliwe parametry dla skryptu phpcs w narzędziu Composer

Możliwe parametry dla skryptu phpcbf w Composerze

cURL, Wget

php phpcs.phar -h
php phpcbf.phar -h

Użycie

Zarówno skrypt phpcs jak i phpcbf korzysta ze standardu kodowania PEAR. Standard kodowania możemy określić za pomocą parametru -- standard.

Aby przetestować pojedynczy plik, używamy komendy:

$ phpcs filename.php 

$ phpcbf filename.php

Możemy przetestować również cały folder:

$ phpcs /path/to/directory 

$ phpcbf /path/to/directory

Skrypt phpcs poinformuje nas o znalezieniu błędów w standardzie kodowania. Przykładowy wynik:

Przykładowy wynik testu w skrypcie phpcs z błędami w standardzie kodowania

Każdy błąd zaznaczony “x” może być naprawiony automatycznie, przy wykorzystaniu skryptu phpcbf.

Automatyczne naprawianie błędów w standardzie kodowania przy wykorzystaniu skryptu phpcbf

Naprawa pozostałych błędów wymaga interwencji programisty. Zwykle są to błędy takie jak brak poprawnych tagów w komentarzu do klasy.

Coder - moduł Drupala

Moduł Coder dostarcza zestaw zasad programowania stosowanych w Drupalu. Używany razem z PHP_CodeSnifferem pomaga naprawiać błędy w standardzie kodowania.

Instalacja

Moduł instalujemy przy wykorzystaniu Composera: composer require drupal/coder

Użycie

Sprawdzenie standardu kodowania wygląda analogicznie do tego, co robiliśmy wcześniej, wykorzystujemy jedynie parametr --standard, któremu nadajemy wartość “Drupal”.

Sprawdzanie standardu kodowania w module Drupala Coder

Integracja z PHPStorm

Zarówno skrypt PHP_CodeSniffer jak i ruleset z modułu Coder możemy zintegrować z większością popularnych IDE. Dla przykładu wykorzystamy PHPStorm.

phpcs

W pierwszej kolejności musimy podać ścieżkę do skryptu phpcs w PHPStorm. W tym celu przechodzimy do Settings -> Languages and Frameworks -> PHP -> Quality Tools -> PHP_CodeSniffer

Widok ustawień PHP_CodeSniffer w zakładce Quality Tools w PHPStorm

Następnie dodajemy nową konfigurację i w PHP_CodeSniffer path podajemy ścieżkę do skryptu. Poprawność ścieżki możemy przetestować klikając w przycisk Validate.

Dodawanie ścieżki do skryptu phpcs dla PHP_CodeSniffera w PHPStorm

Następnie, aby włączyć walidację kodu i wybrać interesujący nas standard, przechodzimy do Settings -> Editor -> Inspections -> Quality Tools i zaznaczamy opcję PHP_CodeSniffer validation.

Walidacja skryptu phpcs dla PHP_CodeSniffera w PHPStorm

Coder

Aby dodać ruleset z modułu Coder, wybieramy Custom w select liście Coding Standard. W pop-upie dodajemy ścieżkę do pliku ruleset.xml dostarczonego wraz z modułem.

Dodawanie ruleseta z modułu Drupala Coder w PHPStorm

Aby skrypt sprawdzał pliki .module, .install, .theme, należy dodać te rozszerzenia do listy “Check files with extensions”.

Dodawanie rozszerzeń .module, .install, theme do listy Check files with extensions w PHPStorm

Na tym etapie phpcs jest już poprawnie zintegrowany z PHPStormem.

W przypadku złamania którejś z zasad, PHPStorm podkreśli linię, która jest niezgodna ze standardami oraz poda dokładną informację na temat zasady, która została złamana.

Przykład informacji na temat zasady kodowania, która została złamana, w PHPStorm

PHPStorm posiada integrację z PHP Code Beautifier and Fixer, która nie wymaga dodatkowej konfiguracji. Z poziomu IDE możemy poprawić automatycznie wszystkie błędy w pliku, które wcześniej naprawialiśmy za pomocą tego skryptu w terminalu. Aby to zrobić, znajdujemy dowolny błąd w pliku i klikamy na lub używamy skrótu Alt+Enter.

Poprawianie błędnego elementu kodu w PHPStorm przy pomocy PHP Code Beautifier and Fixer

Podsumowanie

Zarówno PHP_CodeSniffer jak i moduł Coder usprawniają pracę programistów w trakcie usług PHP developmentu w naszej agencji. Kod pisany w sposób zgodny ze standardami jest łatwiejszy w utrzymaniu i rozwijaniu. Nowe osoby dołączające do projektu szybciej się wdrożą. Natomiast w przypadku przeniesienia projektu do nowego zespołu, proces implementacji również zajmie mniej czasu. W Droptica PHP_CodeSniffer i moduł Coder to standard używany przez każdego programistę.