Konfiguracja WordPressa dla programistów: lokalnie, lint i bloki

Pięciominutowa instalacja daje działającą stronę. Nie daje stanowiska programisty. W 2026 solidna konfiguracja WordPressa to lokalny stos, który da się odtworzyć, pipeline lintu zgodny z core, bezpieczny debug bez błędów na froncie oraz tooling bloków, który buduje te same assety, które testujesz.

Ten przewodnik to checklista, której używamy przy nowym repozytorium motywu lub wtyczki: typ środowiska, wp-env, @wordpress/scripts, stałe debug oraz cienka warstwa hardeningu w wp-config.php i mu-plugins. Na projektach dla klientów z Warszawy i Trójmiasta ten sam .wp-env.json w gicie kończy spory “u mnie działa”.

#Lokalne środowisko z wp-env

Ręczne instalacje Apache i PHP rozjeżdżają się. Jedna maszyna ma PHP 8.2, druga jeszcze 8.1, a buildy bloków padają dopiero na CI. Oficjalna ścieżka to wp-env: kontenery Docker z WordPressem, MySQL i opcjonalnymi narzędziami, sterowane z .wp-env.json w korzeniu projektu.

Instalacja raz globalnie albo jako zależność projektu:

npm install --save-dev @wordpress/env
npx wp-env start

Minimalna konfiguracja dla rozwijanej wtyczki:

{
  "core": "WordPress/WordPress#6.7",
  "plugins": [ "." ],
  "config": {
    "WP_DEBUG": true,
    "WP_DEBUG_LOG": true,
    "WP_DEBUG_DISPLAY": false,
    "SCRIPT_DEBUG": true
  }
}

Dlaczego to wygrywa z generycznym stosem przy pracy nad wtyczkami:

• Wersja core jest pinowana w gicie, więc “działa u mnie” przestaje być argumentem.
• wp-env run cli daje WP-CLI w tych samych kontenerach, które widzi przeglądarka.
• Testy i skrypty e2e w @wordpress/scripts zakładają ten układ.

Połącz to z dokumentacją środowiska edytora bloków, gdy potrzebujesz notatek o Node, create-block i zalecanych rozszerzeniach edytora.

Przy klasycznych motywach PHP możesz trzymać hostowy PHP do jednorazowych skryptów, ale samą stronę trzymaj w wp-env, żeby media, cron i rewrite zachowywały się jak na stagingu.

Przydatne komendy dnia:

npx wp-env run cli wp plugin list
npx wp-env run cli wp cache flush
npx wp-env logs
npx wp-env stop

Własną domenę mapuj w hosts tylko gdy projekt wymaga cookie lub SSO, których localhost psuje. W przeciwnym razie domyślny URL wystarczy i upraszcza certyfikaty.

Gdy ktoś klonuje repo, onboarding ma mieć trzy linie: zainstaluj Docker, npm install, npx wp-env start. Dłuższa instrukcja zwykle oznacza, że środowisko uciekło w nieudokumentowane pakiety hosta.

Na projektach WooCommerce z polskimi bramkami (Przelewy24, PayU) lokalny stack musi umieć odtwarzać callbacki webhooków. Zamiast ręcznie podmieniać URL w panelu bramki, trzymaj osobny wpis w .wp-env.json z pluginami płatności i mapowaniem portów, a w ticketach opisuj, który endpoint CI odtwarza. To ta sama dyscyplina co pinowanie wersji core: mniej zgadywania przy regresji koszyka.

#Typ środowiska i dyscyplina wp-config

Od WordPress 5.5 WP_ENVIRONMENT_TYPE jest przełącznikiem, który powinna czytać każda wtyczka. Zdefiniuj go wcześnie w wp-config.php:

define( 'WP_ENVIRONMENT_TYPE', 'local' ); // local | development | staging | production

Potem rozgałęziaj zachowanie bez własnych stałych:

if ( wp_get_environment_type() === 'production' ) {
	// Cache włączony, gadatliwe logi wyłączone.
} else {
	define( 'SCRIPT_DEBUG', true );
}

Stałe hardeningu w każdym boilerplate produkcyjnym:

define( 'DISALLOW_FILE_EDIT', true );
define( 'FORCE_SSL_ADMIN', true );
define( 'WP_POST_REVISIONS', 5 );
define( 'AUTOMATIC_UPDATER_DISABLED', true ); // gdy deploy sam aktualizuje core

DISALLOW_FILE_MODS włączaj tylko gdy całe drzewo jest niemutowalne, a aktualizacje wchodzą przez CI. Na hostingu zarządzanym, który nadal łata wtyczki z dashboardu, ta stała będzie walczyć z hostem.

Klucze i sole nie są ozdobą. Po kompromitacji je rotuj; każda sesja kończy się od razu. Rotację trzymaj w runbooku wdrożeń, nie na karteczce.

W praktyce agencji w Polsce staging często siedzi na osobnej subdomenie z Basic Auth. Ustaw tam WP_ENVIRONMENT_TYPE na staging, nie local, żeby wtyczki pocztowe i cache nie zachowywały się jak na laptopie developera. Produkcja dostaje production dopiero w pipeline deployu, nigdy przez ręczną edycję pliku na serwerze “na chwilę”.

#Linting z @wordpress/scripts

Linting to sposób, by zostać zgodnym z Gutenbergem bez zapamiętywania każdej reguły ESLint. Pakiet @wordpress/scripts owija webpack, Babel, ESLint, Stylelint, Jest i Playwright za znanymi skryptami npm.

Typowa powierzchnia package.json dla wtyczki blokowej:

{
  "scripts": {
    "start": "wp-scripts start",
    "build": "wp-scripts build",
    "lint:js": "wp-scripts lint-js",
    "lint:css": "wp-scripts lint-css",
    "lint:pkg-json": "wp-scripts lint-pkg-json",
    "format": "wp-scripts format",
    "packages-update": "wp-scripts packages-update"
  }
}

Uruchamiaj npm run lint:js w CI na każdym pull request. Formatuj Prettierem przez wp-scripts format, żeby diff dotyczył logiki, nie cudzysłowów.

PHP nadal potrzebuje własnej bramki. Zainstaluj WordPress Coding Standards (WPCS) przez Composer i odpal PHPCS na motywach i wtyczkach. Nie oczekuj, że @wordpress/scripts to zastąpi; obejmuje połowę JS i CSS.

Praktyczna kolejność CI, która łapie większość regresji:

1. composer phpcs (albo własny wrapper PHPCS)
2. npm run lint:js i npm run lint:css
3. npm run build, żeby zepsuty webpack padł przed review
4. Opcjonalnie: wp-env start, potem PHPUnit wtyczki albo Playwright ze skryptów

Ignoruj wygenerowany build/ w review gita, chyba że projekt świadomie commit’tuje skompilowane assety na host bez Node. Preferuj build w CI albo na deployu. EditorConfig plus domyślny Prettier z pakietu scripts usuwa wojny o wcięcia z pull requestów.

Jeśli legacy motyw nadal serwuje skrypty admina z ery jQuery, wprowadź @wordpress/scripts najpierw dla nowych bloków zamiast przepisywać każde enqueue pierwszego dnia. Mieszane stosy są w porządku; mieszane reguły nie. Jedna konfiguracja ESLint na katalog pakietu.

Gdy klient prosi o “mały widget” w Elementorze, a jednocześnie budujesz bloki pod Gutenberg, trzymaj lint w osobnych pakietach npm: jeden katalog blocks/, drugi legacy-admin/. Wspólny root z jednym .eslintrc na dwa światy kończy się wyjątkami i wyłączonymi regułami, które potem wracają jako regresje w review.

#Debugowanie bez wycieku błędów

Nigdy nie pokazuj błędów PHP odwiedzającym. Loguj je.

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true ); // domyślnie wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Lepiej: skieruj WP_DEBUG_LOG poza document root i zablokuj HTTP do ewentualnego debug.log w wp-content. Na produkcji zostawiaj WP_DEBUG na false, chyba że jesteś w środku incydentu. SAVEQUERIES włączaj tylko na krótkie sesje profilowania; kosztuje pamięć i nie powinien zostawać na noc.

Uzupełnij stałe narzędziami, które pokazują co się stało:

• Query Monitor na hooki, HTTP i wolne zapytania w admin barze
• Xdebug podpięty do kontenera PHP wp-env, gdy potrzebujesz krokowania
• DevTools przeglądarki z SCRIPT_DEBUG, żeby ładować niemainifikowane skrypty core przy konflikcie

Gdy staging pokazuje biały ekran, sprawdź debug.log, log hosta i wp-env logs (lokalnie) zanim dołożysz kolejną wtyczkę “debug”. Większość awarii produkcyjnych z misconfigu to jeden fatal w logu, nie brakująca funkcja.

Odtwórz błąd na wyrzutkowym wp-env z tym samym zestawem wtyczek, zanim ruszysz stałe na produkcji. Jeśli problem widać tylko przy object cache albo CDN, zapisz to w tickecie; lokalny Docker nie wymyśli Redis, dopóki nie dodasz go do konfiguracji env.

#Tooling bloków w 2026

Interaktywne bloki nie są już bocznym projektem. Domyślna ścieżka:

1. Szkieletuj przez npx @wordpress/create-block my-block --variant dynamic (albo static, zależnie od strategii renderu)
2. Rozwijaj na wp-env, żeby rejestracja block.json trafiała w prawdziwy admin
3. Używaj npm start do watch i npm run build do assetów produkcyjnych
4. Rejestruj blok z PHP przez register_block_type( __DIR__ . '/build' ), gdy metadata siedzi w block.json

Trzymaj skrypty edytora i frontu osobno w block.json, żeby nie wysyłać Reacta edytora każdemu odwiedzającemu. Preferuj viewScript / viewStyle dla interakcji frontu zamiast jednego worka.

W motywach, które nadal enqueue’ują klasyczne assety, migruj nowe interaktywne kawałki do bloków przyrostowo. Hybrydowy motyw może wysyłać patterny i kilka custom bloków, a resztę szablonów zostawić w PHP. To normalne w 2026; pełny rewrite Site Editora to decyzja produktowa, nie wymóg toolingu.

Gdy zależności dryfują, npx wp-scripts packages-update odświeża pakiety @wordpress/* w toolchainie scripts. Pinuj majory w package-lock.json i review’uj lockfile w PR tak samo jak aktualizacje Composer.

#Cienkie czyszczenie core przez mu-plugin

Nie potrzebujesz wtyczki “wyłącz wszystko” z katalogu. Mały must-use trzyma reguły w kontroli wersji:

<?php
/**
 * Plugin Name: Lean core
 */

remove_action( 'wp_head', 'print_emoji_detection_script', 7 );
remove_action( 'wp_print_styles', 'print_emoji_styles' );
remove_action( 'wp_head', 'wp_generator' );
add_filter( 'xmlrpc_enabled', '__return_false' );

XML-RPC wyłączaj tylko gdy wiesz, że żaden zdalny klient go nie potrzebuje. Skrypty emoji wyłączaj, gdy kontrolujesz ikony marki i chcesz mniej requestów na froncie. RSS zostaw na stronach contentowych; wizytówki mogą wyłączyć feedy świadomym hookiem, nie losowym snippem z forum.

#Lista kontrolna przed launch

Zanim strona klienta pójdzie na żywo:

1. WP_ENVIRONMENT_TYPE to production.
2. DISALLOW_FILE_EDIT jest true; SSL admin jest wymuszony.
3. Rewizje są ograniczone; wyświetlanie debuga wyłączone.
4. Lokal i CI startują z tego samego .wp-env.json i przechodzą lint oraz build @wordpress/scripts.
5. Assety bloków to buildy produkcyjne, nie leftover z trybu watch.
6. Sole są unikalne; debug.log nie jest dostępny po HTTP.

Konfiguracja WordPressa odtwarzalna z gita jest warta więcej niż sam sprytny wp-config.php. Parity lokalna, bramki lintu i uczciwe logowanie to to, co powstrzymuje pracę blokową i klasyczny PHP przed wzajemnym podgryzaniem.

Potrzebujesz przeglądu istniejącego stosu albo nowej wtyczki blokowej? Porozmawiaj z programistą WordPress w WPPoland.