Standardy kodowania WordPressa dla PHP

WordPress Coding Standards (WPCS) to zestaw reguł PHP_CodeSniffer (PHPCS) służących do sprawdzania kodu w projektach WordPress. Pomaga poprawić jakość kodu i zachować podstawowe konwencje kodowania stosowane w WordPressie.

Pracujesz w zespole lub po prostu chcesz poprawić jakość kodu? W takim przypadku warto zadbać o stosowanie jednego standardu kodowania. Jeśli w zespole pracuje więcej niż jedna osoba, trudno obyć się bez narzędzi do kontroli jakości kodu. Narzędzie służące do automatycznej kontroli zgodności ze standardem kodowania nazywa się linterem i istnieje dla praktycznie każdego języka programowania.

Lint, czyli linter, to narzędzie do statycznej analizy kodu, które służy do wykrywania błędów programistycznych, bugów, błędów stylistycznych oraz podejrzanych konstrukcji.

Wikipedia

Przykładowo, dla Pythona jest to Pylint, dla PHP — PHP_CodeSniffer, a dla JavaScriptu — ESLint lub JSHint.

Standardy kodowania WordPressa obejmują zarówno proste zasady dotyczące spacji i pustych linii, jak i bardziej zaawansowane reguły związane z bezpieczeństwem, cache’owaniem i innymi aspektami kodu.

Jak zainstalować WPCS?

Wystarczy użyć composer:

composer require wp-coding-standards/wpcs --dev

Po dodaniu dowolnych pakietów przeznaczonych dla PHP_CodeSniffer należy dodać je do zakresu działania PHPCS. Najlepszym rozwiązaniem jest pakiet, który automatycznie dodaje wszystkie pakiety znajdujące się w katalogu vendor do zakresu PHPCS.

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

Teraz możesz łatwo sprawdzić plik i automatycznie poprawić wykryte problemy:

vendor/bin/phpcs --standard=WordPress path/to/some/file.php
vendor/bin/phpcbf --standard=WordPress path/to/some/file.php

Jak skonfigurować PHPStorm?

PHPStorm -> Settings -> Languages & Frameworks -> PHP -> CLI Interpreter i wybierz aktualnie używaną wersję PHP.

Następnie przejdź do:

PHPStorm -> Settings -> Languages & Frameworks -> PHP -> Quality Tools -> PHP_CodeSniffer -> Configuration

i kliknij przycisk „…”.

Uzupełnij pole PHP_CodeSniffer path:

path/to/vendor/squizlabs/php_codesniffer/bin/phpcs

oraz pole Path to phpcbf:

path/to/vendor/squizlabs/php_codesniffer/bin/phpcbf

Kliknij przycisk Validate i upewnij się, że ścieżki są poprawne.

Następnie przejdź do:

PHPStorm -> Settings -> Editor -> Inspection -> Quality Tools -> PHP_CodeSniffer

W sekcji walidacji zaznacz:

Show sniff name

Na liście Coding Standard zobaczysz następujące pakiety: WordPress, WordPress-Core, WordPress-Docs, WordPress-Extra. Wybierz WordPress i zapisz ustawienia.

Jeśli naruszysz standardy kodowania, odpowiednie linie w edytorze zostaną podkreślone. Po najechaniu kursorem na podkreśloną linię zobaczysz informacje o wykrytym błędzie.

Przykład:

phpcs: WordPress.Security.NonceVerification.Missing: Processing form data without nonce verification.

WordPress.Security.NonceVerification.Missing — nazwa reguły (sniff), a Processing form data without nonce verification. — opis błędu.

Jak ignorować niektóre reguły?

Czasami kodu nie da się w pełni dostosować do WPCS. Przykładowo:

global $wpdb;
$id       = 15;
$my_query = $wpdb->get_results( 'SELECT name FROM my_table WHERE id=' . $id );

W tym przykładzie pojawia się kilka ostrzeżeń:

• WordPress.DB.PreparedSQL.NotPrepared
• WordPress.DB.DirectDatabaseQuery.NoCaching
• WordPress.DB.DirectDatabaseQuery.DirectQuery

Surowe dane mogą stanowić potencjalny backdoor XSS. Możemy rozwiązać ten problem za pomocą $wpdb->prepare. Cache’owanie niektórych zapytań również może pozytywnie wpłynąć na wydajność, ale co zrobić w przypadku bezpośredniego zapytania?

Właściwym rozwiązaniem jest dodanie reguły ignorowania, ale bardzo ważne jest zrozumienie, dlaczego to robimy. Jeśli dodasz regułę ignorowania, możesz traktować ją jako podpis programisty informujący, że dana linia kodu została celowo napisana w taki sposób.

global $wpdb;
$id       = 15;
$my_query = wp_cache_get( 'my_query' );
if ( ! $my_query ) {
	$my_query = $wpdb->get_results( // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
		$wpdb->prepare( 'SELECT name FROM my_table WHERE id=%d', $id )
	);
	wp_cache_set( 'my_query', $my_query );
}

phpcs:ignore — ignoruje regułę dla następnej linii kodu. Dobrą praktyką jest używanie phpcs:ignore wraz z opisem konkretnej reguły, np. phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery. W ten sposób ignorujemy tylko jedną regułę naszego standardu kodowania.

Jeśli potrzebujesz zignorować daną regułę dla kilku linii kodu, możesz użyć phpcs:disable, ale nie zapomnij ponownie włączyć tej reguły po zakończeniu fragmentu kodu:

//phpcs:disable WordPress.DB.DirectDatabaseQuery.DirectQuery
$my_query = $wpdb->get_results(
	$wpdb->prepare(
		'SELECT name FROM my_table WHERE id=%d',
		$id
	)
);
//phpcs:enable WordPress.DB.DirectDatabaseQuery.DirectQuery

Własny standard kodowania oparty na WPCS

Moim zdaniem w przypadku średnich i większych projektów warto stworzyć własny standard kodowania. Jest to bardzo proste — wystarczy utworzyć plik phpcs.xml:

<?xml version="1.0"?>
<ruleset name="AwesomeCS">
	<description>Custom coding standards.</description>
	<rule ref="WordPress"/>
</ruleset>

Tworzymy standard kodowania AwesomeCS oparty na standardach kodowania WordPressa.

Argumenty

Do konfiguracji możesz przekazywać argumenty z poziomu CLI. Przykładowo argument extensions pozwala ograniczyć działanie narzędzia wyłącznie do plików PHP:

<ruleset name="AwesomeCS">
	<!-- ... -->	
	<arg value="ps"/>
	<arg name="colors"/>
	<arg name="parallel" value="100"/>
	<arg name="extensions" value="php"/>
	<arg name="cache" value=".phpcs.cache"/>
	<!-- ... -->
</ruleset>

• ps pozwala wyświetlać wyniki sprawdzania w czasie rzeczywistym;
• colors dodaje kolorowanie wyników;
• parallel sprawdza pliki w osobnych procesach. Niestety funkcja ta opiera się na bibliotece PCNTL i nie działa w systemach innych niż Unix (Windows). Może jednak znacząco przyspieszyć działanie w GitHub Actions;
• extensions określa rozszerzenia plików, które mają być sprawdzane;
• cache zapewnia znaczne przyspieszenie przy ponownym sprawdzaniu kodu.

Wykluczanie plików i katalogów

Dodaj listę wzorców plików i katalogów, których phpcs nie powinien sprawdzać.

<ruleset name="AwesomeCS">
	<!-- ... -->
	<exclude-pattern>\.github/*</exclude-pattern>
	<exclude-pattern>vendor/*</exclude-pattern>
	<exclude-pattern>node_modues/*</exclude-pattern>
	<exclude-pattern>\.idea/*</exclude-pattern>
	<exclude-pattern>assets/*</exclude-pattern>
	<!-- ... -->
</ruleset>

Krótka składnia tablic

Szczerze mówiąc, krótka składnia tablic jest dla mnie niewygodna i przestarzała, ale jest wymagana przez standard kodowania WordPressa. Zaktualizujmy ją:

<ruleset name="AwesomeCS">
	<!-- ... -->
	<!-- Allow short array syntax -->
	<rule ref="Generic.Arrays.DisallowShortArraySyntax.Found">
		<severity>0</severity>
	</rule>
	<rule ref="Generic.Arrays.DisallowLongArraySyntax.Found"/>
	<!-- ... -->
</ruleset>

To tylko przykład tego, jak dodać własne reguły do standardu kodowania.

Nazewnictwo zgodne z PSR-4

Preferuję korzystanie z autoloadu Composera, dlatego zaktualizujmy standard kodowania, aby obsługiwał nazewnictwo zgodne z PSR-4:

<ruleset name="AwesomeCS">
	<!-- ... -->
	<rule ref="WordPress">
		<!-- PSR4 -->
		<exclude name="WordPress.Files.FileName.InvalidClassFileName"/>
		<exclude name="WordPress.Files.FileName.NotHyphenatedLowercase"/>
	</rule>
	<!-- ... -->
</ruleset>

Złożoność cyklomatyczna

Złożoność cyklomatyczna to metryka programistyczna używana do określania złożoności programu. Jest ilościową miarą liczby liniowo niezależnych ścieżek przebiegu przez kod źródłowy programu.

Wikipedia

Ta metryka pomaga kontrolować złożoność kodu oraz tworzyć prostsze funkcje i metody.

<ruleset name="AwesomeCS">
	<!-- ... -->
	<rule ref="Generic.Metrics.CyclomaticComplexity">
		<properties>
			<property name="complexity" value="4"/>
			<property name="absoluteComplexity" value="5"/>
		</properties>
	</rule>
	<!-- ... -->
</ruleset>

• Jeśli złożoność cyklomatyczna jest większa niż 4, zobaczysz ostrzeżenie.
• Jeśli złożoność cyklomatyczna jest większa niż 5, zobaczysz błąd.

Poziom zagnieżdżenia

<ruleset name="AwesomeCS">
	<!-- ... -->
	<rule ref="Generic.Metrics.NestingLevel">
		<properties>
			<property name="absoluteNestingLevel" value="1"/>
		</properties>
	</rule>
	<!-- ... -->
</ruleset>

Jeśli poziom zagnieżdżenia jest większy niż 1, zobaczysz błąd.

Przykładowo poniższy kod spowoduje błąd w standardzie kodowania:

function awesome_function( $items ) {
	if ( is_array( $items ) {
		foreach( $items as $item ) {
			// ...
		}
	}
}

Ten kod wymaga refaktoryzacji i zastosowania wcześniejszego wyjścia z metody/funkcji:

function awesome_function( $items ) {
	if ( ! is_array( $items ) {
		return false;
	}
	foreach( $items as $item ) {
		// ...
	}
}

PHPCompatibility

Świetny standard kodowania PHPCompatibility, który pozwala określić minimalną obsługiwaną wersję PHP, a następnie sprawdza kod za pomocą phpcs i wykrywa problemy związane z kompatybilnością z tą wersją. Jest to naprawdę bardzo przydatna biblioteka w przypadku publicznych wtyczek, które muszą obsługiwać szeroki zakres wersji, na przykład od PHP 5.6 do PHP 7.4. Wystarczy uruchomić testy na PHP 7.4, a biblioteka pomoże znaleźć problemy z kompatybilnością z PHP 5.6.

Zainstalujmy tę bibliotekę i zaktualizujmy konfigurację:

composer require phpcompatibility/php-compatibility --dev

<ruleset name="AwesomeCS">
	<!-- ... -->
	<config name="testVersion" value="5.6-"/>
	<rule ref="PHPCompatibility"/>
	<!-- ... -->
</ruleset>

Dzięki temu możesz sprawdzać kompatybilność z wersjami PHP od 5.6 aż do wersji, na której sprawdzasz pliki.

Dodanie własnej konfiguracji do PHPStorm

File → Settings → Editor → Inspection → Quality Tools → PHP_CodeSniffer

Na liście Coding standard wybierz Custom i wskaż ścieżkę do naszego pliku phpcs.xml.

Pełna konfiguracja

<?xml version="1.0"?>
<ruleset name="CS">
	<description>Custom coding standards.</description>
	<config name="testVersion" value="5.6-"/>
	<exclude-pattern>\.codeception/*</exclude-pattern>
	<exclude-pattern>\.github/*</exclude-pattern>
	<exclude-pattern>vendor/*</exclude-pattern>
	<exclude-pattern>node_modues/*</exclude-pattern>
	<exclude-pattern>\.idea/*</exclude-pattern>
	<exclude-pattern>assets/*</exclude-pattern>

	<arg value="ps"/>
	<arg name="colors"/>
	<arg name="parallel" value="100"/>
	<arg name="extensions" value="php"/>
	<arg name="cache" value=".phpcs.cache"/>

	<rule ref="WordPress">
		<!-- PSR4 -->
		<exclude name="WordPress.Files.FileName.InvalidClassFileName"/>
		<exclude name="WordPress.Files.FileName.NotHyphenatedLowercase"/>
	</rule>

	<rule ref="PHPCompatibility"/>

	<rule ref="Generic.Metrics.CyclomaticComplexity">
		<properties>
			<property name="complexity" value="3"/>
			<property name="absoluteComplexity" value="5"/>
		</properties>
	</rule>

	<rule ref="Generic.Metrics.NestingLevel">
		<properties>
			<property name="absoluteNestingLevel" value="3"/>
		</properties>
	</rule>

	<!-- Allow short array syntax -->
	<rule ref="Generic.Arrays.DisallowShortArraySyntax.Found">
		<severity>0</severity>
	</rule>
	<rule ref="Generic.Arrays.DisallowLongArraySyntax.Found"/>
</ruleset>

Skrypty Composera

Dodaj skrypty umożliwiające uruchamianie standardu kodowania za pomocą skryptów Composera. Wystarczy dodać do pliku composer.json następujący kod:

{
...
  "scripts": {
    "cs": "phpcs --standard=.phpcs.xml .",
    "cbf": "phpcbf --standard=.phpcs.xml .",
    ...
  }
...
}

Teraz możesz po prostu uruchomić sprawdzanie standardu kodowania oraz narzędzie do formatowania i automatycznego poprawiania kodu:

composer cs
composer cbf

Standard kodowania w GitHub Actions

Utwórz w swoim projekcie plik .github/workflows/php.yml:

name: My GH Actions

on: push

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2

    - name: Install dependencies
      run: composer install --prefer-dist --no-progress --no-suggest

    - name: Run CS
      run: vendor/bin/phpcs --standard=phpcs.xml .

Po wykonaniu push akcja zostanie uruchomiona, a Twój kod zostanie sprawdzony pod kątem zgodności ze standardami kodowania. Wyniki będziesz mógł zobaczyć bezpośrednio na GitHubie.

Jeśli po przeczytaniu tak szczegółowego artykułu nadal nie wdrożysz w swoim projekcie weryfikacji standardów kodowania, przyjdę do Ciebie we śnie i skopię Ci tyłek. 😄

Co dalej? Możesz przeczytać jak tworzyć własne reguły (sniffs) dla PHP_CodeSniffer.

Oryginalny artykuł można przeczytać tutaj