Pisze Pan kod dla WordPress, a kolega prosi, by „usunąć spacje i wcięcia" podczas każdego code review? Albo strona pada po aktualizacji wtyczki, a błędu w logach nie sposób znaleźć, bo kod napisano bez żadnego standardu?

Znajomy obrazek dla każdego, kto rozwija WordPressa w zespole. Różne nawyki formatowania, jedni stosują warunki Yoda, drudzy nie, a escapowanie danych wyjściowych miejscami jest nieobecne.

PHP CodeSniffer rozwiązuje to automatycznie: sprawdza kod pod kątem zgodności ze standardami kodowania WordPress bezpośrednio w edytorze, podświetla naruszenia i potrafi je poprawić jedną komendą. Dalej, konfiguracja od zera w PhpStorm 2026.

💡 Szybki przegląd:

• Proszę zainstalować PHP CodeSniffer i WordPress Coding Standards przez Composera, w projekcie lub globalnie
• Proszę wskazać ścieżkę do phpcs w konfiguracji i dodać standard WordPress
• Proszę skonfigurować zdalny interpreter PHP, jeśli pracuje Pan przez Vagrant, Docker lub SSH
• Proszę włączyć inspekcję PHP CodeSniffer Validation w PhpStorm, błędy zostaną podświetlone na bieżąco
• Proszę skonfigurować autoformatowanie przez PHP Code Beautifier and Fixer, aby poprawiać kod jedną komendą

Wideo krok po kroku po angielsku (te same kroki co w tekście):

Krok 1: proszę skonfigurować zdalny interpreter PHP

Jeśli rozwija Pan na lokalnym PHP (XAMPP, MAMP, Local, wbudowanym serwerze), proszę pominąć ten krok. Dla Vagrant, Docker lub serwera zdalnego przez SSH interpreter trzeba wskazać jawnie.

Proszę otworzyć Settings → PHP (Ctrl+Alt+S), kliknąć […] obok CLI Interpreter i wybrać SSH Credentials lub Docker Compose.

Proszę wypełnić:

• adres IP hosta, ten sam co dla strony (ping example.dev podpowie)
• vagrant dla nazwy użytkownika i hasła (jeśli Vagrant)
• /usr/bin/php, ścieżkę do pliku wykonywalnego PHP na serwerze

Proszę zapisać i wybrać utworzony interpreter z listy:

PhpStorm będzie używał właśnie tego PHP do uruchamiania CodeSniffera i innych narzędzi jakości kodu.

Krok 2: proszę zainstalować PHP CodeSniffer przez Composera

Najpewniejszy sposób to dodać PHPCS jako zależność projektu. Proszę dodać w composer.json:

1
{
2
  "require-dev": {
3
    "squizlabs/php_codesniffer": "^3.10"
4
  }
5
}

Następnie composer install. PhpStorm automatycznie wykryje phpcs i phpcbf w vendor/bin, nie będzie trzeba ręcznie wpisywać ścieżek.

Dla instalacji globalnej (jeśli potrzebuje Pan we wszystkich projektach naraz):

1
composer global require "squizlabs/php_codesniffer=*"

Proszę sprawdzić: plik wykonywalny phpcs powinien znajdować się w ~/.composer/vendor/bin/ (Linux/Mac) lub %APPDATA%/Composer/vendor/bin/ (Windows).

Krok 3: instalacja WordPress Coding Standards

WPCS to zestaw reguł (sniffs) dla PHPCS, który sprawdza zgodność właśnie ze standardami WordPress: escapowanie danych wyjściowych, warunki Yoda, prefiksy funkcji i wszystko inne z WordPress Coding Standards Handbook.

Przez Composer w projekcie:

1
composer require --dev wp-coding-standards/wpcs:"^3.0"

Lub globalnie (stara, sprawdzona metoda):

1
composer create-project wp-coding-standards/wpcs:dev-master --no-dev

Proszę upewnić się, że standard pojawił się w ~/.composer/wpcs/ lub vendor/wp-coding-standards/wpcs/.

Krok 4: konfiguracja ścieżki do standardu w PHPCS

Proszę przejść do katalogu z phpcs i wskazać, gdzie znajdują się zainstalowane standardy:

1
cd ~/.composer/vendor/bin
2
phpcs --config-set installed_paths ~/.composer/wpcs

Proszę sprawdzić, czy WordPress pojawił się na liście dostępnych standardów:

1
phpcs -i

Na wyjściu powinny pojawić się cztery standardy: WordPress, WordPress-Core, WordPress-Docs i WordPress-Extra.

Krok 5: dodanie phpcs do PATH

Proszę otworzyć ~/.bash_profile (lub ~/.zshrc dla ZSH) i dodać linię:

1
PATH=$PATH:~/.composer/vendor/bin

Proszę przeładować terminal lub wykonać source ~/.bash_profile. Od teraz polecenie phpcs jest dostępne z dowolnego katalogu.

Proszę sprawdzić na dowolnym pliku motywu lub wtyczki:

1
cd wp-content/themes/your-theme
2
phpcs --standard=WordPress functions.php

Poprawne wyjście wygląda następująco:

Błędy dzielą się na dwa poziomy: ERROR dla twardych naruszeń i WARNING dla zaleceń. Każda linia zawiera numer reguły i opis problemu.

Krok 6: konfiguracja PHP CodeSniffer w PhpStorm

Proszę otworzyć Settings → PHP → Quality Tools → PHP_CodeSniffer (Ctrl+Alt+S).

Jeśli instalacja odbywała się przez Composer w projekcie, PhpStorm automatycznie wykryje phpcs z vendor/bin. Jeśli globalnie, proszę kliknąć […] obok Configuration i wskazać ścieżkę do pliku wykonywalnego: ~/.composer/vendor/bin/phpcs.

Proszę wybrać interpreter PHP z listy, ten sam, który był konfigurowany w kroku 1.

Krok 7: włączenie inspekcji PHP CodeSniffer Validation

Proszę przejść do Settings → Editor → Inspections, rozwinąć PHP → Quality Tools i zaznaczyć pole PHP_CodeSniffer validation.

Z listy rozwijanej Coding standard proszę wybrać WordPress. Proszę zapisać ustawienia.

Od tego momentu PhpStorm sprawdza otwarty plik PHP na bieżąco. Naruszenia są podświetlane falistym podkreśleniem, jak zwykłe błędy IDE. Po najechaniu kursorem pojawia się okienko z opisem: co jest nie tak i jak to poprawić.

Krok 8: proszę sprawdzić działanie

Proszę utworzyć lub otworzyć dowolny plik PHP motywu i napisać celowo niestandardowy kod:

1
if(true){echo 'Пробелы? Не, не слышал';}

PhpStorm podkreśli wiersz: brakuje spacji po if, wokół nawiasów klamrowych i wewnątrz warunku. Po najechaniu kursorem zobaczą Państwo tekst błędu i numer reguły WordPress.

Krok 9: proszę skonfigurować autokorektę przez PHP Code Beautifier and Fixer

Nie trzeba poprawiać każdego naruszenia ręcznie. PHP Code Beautifier and Fixer (phpcbf) jest instalowany razem z PHPCS i potrafi automatycznie poprawiać kod zgodnie z wybranym standardem.

Proszę otworzyć Settings → PHP → Quality Tools, w sekcji External Formatters wybrać PHP Code Beautifier and Fixer. Teraz przy wywołaniu Code → Reformat Code (Ctrl+Alt+L / Cmd+Option+L) PhpStorm nie tylko wyrówna wcięcia swoim formatowaniem, ale także zastosuje reguły WordPress przez phpcbf.

Dodatkowo proszę skonfigurować styl kodu WordPress dla wbudowanego formatera: Settings → Editor → Code Style → PHP → Set From → Predefined Style → WordPress. Dzięki temu oba narzędzia działają w tym samym kierunku i nie kolidują ze sobą.

Krok 10: co robić dla nowych projektów

Dla każdego nowego projektu WordPress wystarczy powtórzyć krok 1 (interpreter, jeśli zdalny), krok 6 (wskazać phpcs w ustawieniach) i krok 7 (włączyć inspekcję). Jeśli używają Państwo Composera w projekcie, kroki 2-4 zamyka jedna linijka composer require --dev wp-coding-standards/wpcs.

⁉️🤔 Często zadawane pytania

Jaka jest różnica między WordPress, WordPress-Core, WordPress-Docs i WordPress-Extra?

WordPress, podstawowy zestaw wszystkich reguł oprócz dokumentowania. WordPress-Core, tylko reguły z oficjalnego podręcznika kodowania (wcięcia, nazewnictwo, warunki Yoda). WordPress-Extra dodaje kontrole bezpieczeństwa: eskejpowanie wyjścia, walidację danych wejściowych. WordPress-Docs sprawdza standardy dokumentowania kodu (PHPDoc). W praktyce należy stosować WordPress, który zawiera Core i Extra.

PhpStorm nie widzi phpcs po instalacji. Co robić?

Proszę sprawdzić, czy folder vendor/bin (lub ~/.composer/vendor/bin) jest dodany do PATH i zawiera plik wykonywalny phpcs. W PhpStorm należy otworzyć Settings → PHP → Quality Tools → PHP_CodeSniffer, kliknąć […] i ręcznie wskazać ścieżkę do phpcs. Po zmianie interpretera lub ponownej instalacji zależności może być potrzebne zresetowanie konfiguracji, przycisk Reset w tym samym oknie.

Czy można używać PHPCS bez Composera, po prostu pobierając archiwum phar?

Tak, ale nie zalecamy. Przy instalacji przez Composer PhpStorm automatycznie wykrywa zarówno phpcs, jak i phpcbf oraz wszystkie zarejestrowane standardy. Z archiwum phar trzeba ręcznie podawać ścieżki i osobno śledzić aktualizacje. W pracy zespołowej zależność Composer w composer.json ustala wersję, dzięki czemu wszyscy deweloperzy mają ten sam zestaw reguł.

Jak wykluczyć konkretne pliki lub foldery ze sprawdzania?

Należy utworzyć phpcs.xml w katalogu głównym projektu. Można w nim wykluczyć katalogi (<exclude-pattern>vendor/*</exclude-pattern>), określić standard i zmienić severity poszczególnych reguł. PhpStorm automatycznie wykryje ten plik, jeśli znajduje się w katalogu głównym projektu i nazywa się phpcs.xml lub phpcs.xml.dist.

Dlaczego PHPCS zgłasza błąd przy wp_redirect() bez exit?

Standard WordPress wymaga exit lub wp_die() po każdym przekierowaniu: wp_redirect() tylko ustawia nagłówek, ale nie zatrzymuje wykonywania skryptu. Bez exit kod po przekierowaniu będzie dalej wykonywany, a to luka w bezpieczeństwie. Prawidłowo: wp_redirect( home_url() ); exit;.

Co robić, gdy baza kodu jest już duża, a standardy dopiero się wdraża

Uruchamianie PHPCS na projekcie z tysiącami naruszeń to pewny sposób, by zdemotywować zespół. Proszę zacząć od małych kroków: poprawić błędy krytyczne (error, nie warning) przez phpcbf, a następnie stopniowo obniżać próg. Proszę dodać phpcs.xml z wyjątkami dla legacy-kodu i włączać nowe reguły po jednej na miesiąc.

Oto plan wdrożenia krok po kroku na żywym projekcie:

• Proszę uruchomić phpcs --standard=WordPress --report=summary, aby zobaczyć całkowitą liczbę błędów.
• Proszę poprawić autofixem wszystko, co się da: phpcbf --standard=WordPress .
• Pozostałe błędy proszę rozdzielić według severity, najpierw krytyczne.
• Proszę dodać sprawdzanie w CI (GitHub Actions, GitLab CI): niech build pada przy nowych violations w pull requeście.

Proszę zacząć od bezpłatnego composer require --dev wp-coding-standards/wpcs w jednym projekcie. Po tygodniu zespół przyzwyczai się do podświetlania, po miesiącu, do czystego kodu. A jaki standard kodowania Państwo stosują, proszę napisać w komentarzach.