Bartłomiej Romanek

W dzisiejszym wpisie chciałbym opowiedzieć, czym jest Code Sniffer oraz jak korzystać z tego świetnego narzędzia wspomagającego tworzenie czystego, zgodnego ze standardami kodu tworząc aplikacje w środowisku PHP.

Kilka słów wstępu

Code sniffery to zbiór narzędzi, które skanują kod źródłowy programu (analiza statyczna kodu, czyli analiza kodu bez jego kompilacji oraz uruchomienia) i dostarczają użytkownikowi cennych informacji na temat jego struktury. Jednym z najpopularniejszych snifferów kodu dla języka PHP jest PHP Code Sniffer. Narzędzie to można pobrać z oficjalnego repozytorium projektu (https://github.com/squizlabs/PHP_CodeSniffer), ale lepiej wykorzystać do tego Composera :)

Korzystanie z narzędzia za pomocą wiersza poleceń

Tworzymy najpierw nowy projekt i pobieramy narzędzie za pomocą Composera:

composer require --dev "squizlabs/php_codesniffer"

Następnie dodajemy w katalogu src (zakładamy, że tutaj znajdują się pliki źródłowe) plik MyClass.php, w którym (o zgrozo!) umieszczamy poniższą treść:

<?php namespace Example; class my_class { function Mutiply($arg1, $arg2) { return $arg1 * $arg2; } }

Powyższy kod jest tragiczny :) ale zakładamy, że tego nie zauważyliśmy. Teraz sprawdzamy wymienionym wyżej narzędziem, czy pliki znajdujące się w projekcie są poprawnie sformatowane w kontekście standardu PSR-2:

.\vendor\bin\phpcs --standard=PSR2 ./src

W wyniku otrzymujemy raport zawierający listę błędów, które powinniśmy poprawić w naszym kodzie:

FILE: C:\Program Files (x86)\Ampps\www\pcs\src\MyClass.php ---------------------------------------------------------------------- FOUND 6 ERRORS AFFECTING 3 LINES ---------------------------------------------------------------------- 5 | ERROR | [ ] Class name "my_class" is not in PascalCase format 5 | ERROR | [x] Opening brace of a class must be on the line after | | the definition 6 | ERROR | [ ] Method name "my_class::Mutiply" is not in camel caps | | format 6 | ERROR | [ ] Visibility must be declared on method "Mutiply" 6 | ERROR | [x] Opening brace should be on a new line 9 | ERROR | [x] Expected 1 newline at end of file; 0 found ---------------------------------------------------------------------- PHPCBF CAN FIX THE 3 MARKED SNIFF VIOLATIONS AUTOMATICALLY ---------------------------------------------------------------------- Time: 103ms; Memory: 4Mb

Liczby w pierwszej kolumnie wskazują na numer wiersza, w którym został znaleziony błąd. Błędy oznaczone za pomocą [x] mogą zostać automatycznie naprawione.

Aby za każdym razem nie wpisywać polecenia z całą listą argumentów, możemy stworzyć plik konfiguracyjny z ustawieniami (tzw. ruleset). W głównym katalogu dodajemy plik phpcs.xml z poniższą zawartością:

<?xml version="1.0"?> <ruleset name="PHP_CodeSniffer"> <rule ref="PSR2"/> <file>src</file> <arg name="encoding" value="utf-8"/> </ruleset>

Teraz wywołując narzędzie bez żadnego dodatkowego argumentu, konfiguracja zostanie załadowana z pliku konfiguracyjnego. Dzieje się tak dlatego, że ustawienia są szukane w określonych plikach na dysku - jednym z nich jest plik phpcs.xml.

Korzystanie z narzędzia z poziomu PhpStorm

Korzystanie z narzędzia w naszym ulubionym IDE :) jest bardzo przyjemne i posiada dodatkową zaletę - pozwala na kontrolę tworzonego przez nas kodu w czasie rzeczywistym. Aby włączyć sniffer w PhpStorm, przechodzimy w ustawieniach pod ścieżkę:

Settings > Languages & Frameworks > PHP > Quality Tools > Code Sniffer > [...]

W PHP Code Sniffer path wskazujemy ścieżkę do pliku phpcs.bat z katalogu vendor/bin i klikamy na przycisk Validate. Jeżeli ścieżka jest poprawna, pojawi się zielony komunikat:

Teraz musimy skonfigurować wybrany zestaw reguł. Przechodzimy w ustawieniach pod ścieżkę:

Settings > Editor > Inspections > PHP > Quality Tools > PHP Code Sniffer validation

Zaznaczamy pole wyboru PHP Code Sniffer validation oraz w sekcji Coding Standards klikamy na przycisk Refresh. Teraz została załadowana lista dostępnych standardów i możemy wybrać zestaw PSR-2. Zapisujemy ustawienia i przechodzimy do wcześniej przygotowanego pliku MyClass.php. Po chwili niepoprawne fragmenty kodu zostaną podkreślone, a po najechaniu możemy sprawdzić szczegóły:

Dlaczego warto korzystać z narzędzia

Zachęcam każdego do korzystania z tego typu narzędzi. Myślę, że programistów z doświadczeniem nie trzeba przekonywać dlaczego, ale osoby, które dopiero zaczynają przygodę z kodem powinny pamiętać przede wszystkim o tym, że code sniffer:

• zapobiega pomyłkom - w pośpiechu łatwo o pomyłkę. Zdarza mi się to stosunkowo często. Jeżeli włączymy narzędzie w IDE, to pomyłka jest widoczna natychmiastowo;
• oszczędza czas - ze względu na to, że to narzędzie automatyczne - nie trzeba angażować innych osób, np. programistów z zespołu. Dzięki zadbaniu o code style jeszcze przed wypchaniem zmian na serwer podczas przeprowadzania code review programiści mogą skupić się na merytoryce kodu;
• code sniffer jest obiektywny - jeżeli zastanawiasz się, czy wykorzystana przez Ciebie składnia jest zgodna z wybranym stylem kodowania, to narzędzie odpowie na to pytanie jednoznacznie.