Techniki refaktoryzacji kodu dla programistów WordPress

Sześć technik refaktoryzacji kodu decyduje o tym, czy projekt WordPress pozostaje utrzymywalny po pierwszym roku, czy zamienia się w functions.php, który kolejny freelancer dziedziczy z niepokojem. Ten foliał obejmuje techniki refaktoryzacji kodu, które naprawdę mają znaczenie w praktyce programisty pracującego z motywami blokowymi i wtyczkami PHP.

Kiedy kod WordPress prosi się o refaktoryzację

Plik functions.php przekraczający 400 linii to wiarygodny sygnał ostrzegawczy. Podobnie jak wzorzec bloku, który "tymczasowo" zduplikowano trzy miesiące temu i który dziś istnieje w pięciu lekko odmiennych wersjach w katalogu motywu klienta. Code smell to nie błąd. Strona działa. Klient jest zadowolony. Ale kolejny programista, który dotknie tego kodu, spędzi cztery godziny na zrozumieniu tego, co powinno zająć czterdzieści minut.

Rozpoznanie code smell wymaga wprawy, którą buduje się na konkretnych projektach, nie na lekturze. Warto prowadzić prostą listę sygnałów: funkcja przyjmująca więcej niż cztery argumenty, klasa robiąca za dużo naraz, komentarz tłumaczący dlaczego kod jest "tymczasowo" napisany w ten sposób. Każdy taki sygnał to kandydat do refaktoryzacji przy najbliższej okazji, nie za rok.

W praktyce widać jednak, że koszt refaktoryzacji rośnie gwałtownie im dłużej się ją odkłada. Badanie Stack Overflow z 2024 roku pokazało, że 62 procent programistów wskazuje dług techniczny jako główną codzienną frustrację. W projektach WordPress objawia się to zwykle jako logika warunkowa zagnieżdżona na cztery poziomy wewnątrz funkcji szablonu, albo wywołania register_block_pattern() rozrzucone po trzech różnych plikach bez jasnego właściciela.

Warunek wstępny przed jakąkolwiek techniką: pokrycie testami. Refaktoryzacja bez testów to nie refaktoryzacja, to przepisywanie na wiarę. Dla WordPressa bazę zapewniają WP-CLI i PHPUnit. W motywach blokowych opartych wyłącznie na FSE, gdzie PHP jest minimalne, tę samą rolę pełnią testy end-to-end przez Playwright uruchamiane na lokalnym środowisku Lando lub LocalWP.

Wydzielanie metod: pierwsze narzędzie na warsztacie

Najbardziej uniwersalną techniką refaktoryzacji w PHP dla WordPressa jest wydzielanie metod (Extract Method). Zasada jest prosta: kiedy funkcja robi więcej niż jedną rzecz, dzielimy ją.

Weźmy obsługę uploadu plików we wtyczce. Pierwotna implementacja to dwustuliniowa funkcja, która sprawdza typ MIME, weryfikuje rozmiar pliku, ustala ACL dla S3 i zapisuje metadane załącznika, wszystko po kolei. Wersja po refaktoryzacji definiuje cztery metody: is_valid_mime_type(), is_within_size_limit(), get_s3_acl() oraz write_attachment_meta(). Funkcja zewnętrzna czyta się niemal jak opisana prozą.

W motywach blokowych ta sama zasada dotyczy functions.php. Motyw, który rejestruje style bloków, ładuje skrypty edytora, konfiguruje wsparcie bloków i dodaje własne query vars w jednym haku after_setup_theme, robi zbyt wiele naraz. Rozbicie tego na nazwane, skupione funkcje i dołączenie ich z katalogu /inc/ to nie architektoniczna ekwilibrystyka. To różnica między kodem, który ktoś ogarnie w godzinę, a takim, który wymaga przewodnika.

Marginalia: to podejście sprawdza się od WordPressa 6.4+, gdzie block hooks API wprowadza dodatkowe wzorce rejestracji korzystające na takiej izolacji.

Guard clauses zamiast piętrowych warunków

Zagnieżdżone warunki to druga najczęstsza friction w kodzie PHP dla WordPressa, jaką widać w produkcji. Częsty wzorzec we wtyczkach wygląda tak: funkcja sprawdza uprawnienie, potem typ wpisu, potem wartość meta, i dopiero wtedy wykonuje logikę. Każdy warunek zagnieżdżony jest w poprzednim, tworząc kod w kształcie schodów.

Guard clauses odwracają ten schemat. Każdy warunek, który powstrzymałby wykonanie, staje się wczesnym returnem na górze funkcji. Ścieżka sukcesu ląduje na dole, bez wcięć, czytelna bez śledzenia głębokości nawiasów.

// Przed: schody zguby
function handle_submission( $post_id ) {
    if ( current_user_can( 'edit_posts' ) ) {
        if ( get_post_type( $post_id ) === 'project' ) {
            if ( get_post_meta( $post_id, '_status', true ) === 'pending' ) {
                // właściwa logika tutaj
            }
        }
    }
}

// Po: guard clauses
function handle_submission( $post_id ) {
    if ( ! current_user_can( 'edit_posts' ) ) return;
    if ( get_post_type( $post_id ) !== 'project' ) return;
    if ( get_post_meta( $post_id, '_status', true ) !== 'pending' ) return;

    // właściwa logika tutaj
}

Wersja po refaktoryzacji jest krótsza, a co ważniejsze, każdy warunek da się przeczytać, zrozumieć i zmienić niezależnie od pozostałych. Gdy logika biznesowa się zmieni (a zmieni się na pewno), poprawka jest chirurgicznie precyzyjna.

DRY w blokach Gutenberga: koniec z duplikowaniem szablonów

Zasada DRY (Don't Repeat Yourself) to najczęściej łamana zasada refaktoryzacji przy budowie motywów blokowych. Kiedy freelancer WordPress buduje stronę dla klienta, biblioteka wzorców zwykle rośnie organicznie: tu sekcja hero, tam sekcja z opiniami. Do trzeciego miesiąca aktywnego rozwoju nierzadko istnieje pięć wariantów sekcji hero z markupem identycznym w 80 procentach, każdy lekko dostosowany do innej części strony.

Podejście refaktoryzacyjne polega na zidentyfikowaniu wspólnej struktury, wydzieleniu jej do jednego kanonicznego wzorca, a potem wykorzystaniu wariantów wzorca bloku lub Global Styles do obsługi różnic wizualnych. Właśnie to ułatwia na poziomie narzędzi wtyczka Create Block Theme: czyni jawną granicę między "motywem w budowie" a "motywem gotowym do eksportu i ponownego użycia".

Dla PHP wtyczek odpowiednikiem jest wydzielenie wspólnych metod do klasy nadrzędnej. Jeśli dwie klasy dodatków definiują metodę set_settings(), która czyta z tego samego klucza opcji, ta metoda należy do wspólnej klasy abstrakcyjnej. Gdy klucz opcji się zmienia, poprawka dzieje się raz.

Pomiń tę refaktoryzację, jeśli zduplikowane wzorce służą naprawdę różnym kontekstom redakcyjnym, które będą ewoluować niezależnie od siebie. Wymuszony DRY tworzy sprzężenie gorsze niż pierwotna duplikacja. Test jest prosty: czy oba duplikaty logicznie zmieniałyby się razem? Jeśli tak, wydziel. Jeśli nie, zostaw osobno.

Refaktoryzacja szablonów FSE: od monolitu do template parts

System Full Site Editing wprowadził strukturalną okazję do refaktoryzacji, z której wielu twórców motywów blokowych wciąż nie korzysta w pełni. Plik templates/single.html zawierający pełny markup nagłówka, nawigacji, obszaru treści, paska bocznego i stopki w jednym pliku to odpowiednik monolitycznej funkcji w świecie FSE. Działa. Ale nie da się go utrzymać na stronie z dwunastoma różnymi typami wpisów.

Ścieżką refaktoryzacji są template parts. Przenieś nagłówek do parts/header.html, stopkę do parts/footer.html, i odwołuj się do nich przez <!-- wp:template-part {"slug":"header"} /--> w każdym szablonie, który ich potrzebuje. Gdy klient zmienia strukturę nawigacji, zmiana dzieje się w jednym pliku i propaguje się wszędzie.

To nie teoria. Dokumentacja WordPress o template parts opisuje ten sam wzorzec podziału szablonów na poziomie oficjalnej specyfikacji motywów blokowych, co potwierdza, że to podejście jest rekomendowaną praktyką, a nie improwizacją pojedynczego zespołu.

Notatka z terenu, kiedy NIE refaktoryzować szablonów: jeśli strona ma dziesięć szablonów lekko się różniących, a klient często edytuje je bezpośrednio w Site Editorze, agresywne wydzielanie do template parts może wprowadzić zamieszanie. Interfejs Site Editora dla template parts się poprawia, ale wciąż ma friction wokół odkrywalności. Dla klientów nietechnicznych mniej ruchomych części to często słuszny wybór, nawet jeśli architektonicznie mniej elegancki.

Funkcyjne metody PHP zamiast pętli foreach

Wbudowane funkcje tablicowe PHP (array_map, array_filter, array_reduce) są niedocenione w kodzie wtyczek WordPress. Eliminują jawne pętle foreach i zmienne pomocnicze, dając kod, który wyraża zamiar, a nie mechanikę.

Częsty wzorzec w WordPressie: iterowanie po tablicy obiektów wpisów, żeby wyliczyć wartość, budując akumulator wewnątrz pętli. Odpowiednik funkcyjny używa array_map do przekształcenia każdego wpisu i array_reduce do policzenia wartości końcowej. Rezultat to mniej linii, a co ważniejsze, brak mutowalnego stanu wewnątrz pętli.

Ta technika pasuje, gdy operacja to rzeczywiście transformacja albo redukcja. Nie pasuje do operacji z efektami ubocznymi (zapis do bazy, wywołania API), które wymagają obsługi błędów dla każdego elementu osobno. W takich przypadkach jawna pętla z czytelnymi granicami błędów jest właściwym wyborem.

Warto też pamiętać o czytelności dla kolejnego programisty. array_reduce z długim callbackiem anonimowym bywa trudniejsze do zrozumienia niż prosta pętla foreach z nazwaną zmienną akumulatora. Zasada jest prosta: jeśli funkcyjny zapis wymaga komentarza tłumaczącego, co robi, klasyczna pętla może być lepszym wyborem dla zespołu, który przejmie kod po tobie.

theme.json jako refaktoryzacja tokenów projektowych

Szósta technika jest specyficzna dla motywów blokowych i stanowi inny rodzaj refaktoryzacji: przeniesienie zaszytych na sztywno wartości z CSS i PHP do theme.json jako nazwanych tokenów projektowych.

Motyw, który definiuje color: #1a1a2e w sześciu różnych regułach CSS, albo zaszywa ten sam stos fontów zarówno w style.css, jak i w arkuszu stylów edytora, ma problem z utrzymaniem. Gdy kolor marki się zmienia, programista szuka wartości hex. Gdy zmienia się font, zmienia się w dwóch albo więcej miejscach.

theme.json rozwiązuje to, czyniąc decyzje projektowe jawnymi i nazwanymi. Wpis palety kolorów "slug": "primary" staje się var(--wp--preset--color--primary) w CSS. Zmień wartość hex w theme.json, a każdy blok korzystający z presetu koloru zaktualizuje się automatycznie, zarówno na froncie, jak i w Site Editorze.

Ta sama zasada dotyczy skali odstępów, rozmiarów fontów i niestandardowych wymiarów układu. Refaktoryzacja motywu pod kątem konsekwentnego użycia tokenów theme.json nie jest efektowną pracą. Zajmuje czas. W praktyce widać na stronach, gdzie to zrobiono, że kolejna iteracja projektowa jest wyraźnie szybsza, a rozjazd stylów między edytorem a frontem znacząco maleje.

Kiedy refaktoryzacja tylko szkodzi

Kolofon tego artykułu: nie każdy projekt korzysta na agresywnej refaktoryzacji. Trzy sytuacje, w których warto zachować powściągliwość.

Pierwsza: strona klienta z terminem dostawy za dwa tygodnie. Refaktoryzacja wprowadza ryzyko. Wydaj funkcję, udokumentuj dług, zaplanuj porządki na później.

Druga: kod, którego jeszcze w pełni nie rozumiesz. Refaktoryzacja wymaga modelu tego, co kod robi. Jeśli ten model jest niepełny, wersja po refaktoryzacji może usunąć zachowanie, które wydawało się przypadkowe, a w rzeczywistości było nośne.

Trzecia: kod, który zostanie całkowicie wymieniony w ciągu pół roku. Dane McKinsey z 2024 roku na temat systematycznej refaktoryzacji pokazują tempo ukończenia wyższe o 40 do 50 procent w porównaniu z podejściem doraźnym. Ta przewaga zakłada jednak, że refaktoryzowany kod będzie dalej utrzymywany. Jeśli kod jest tymczasowy, inwestycja się nie zwraca.

Test przed refaktoryzacją jakiegokolwiek kodu WordPress: czy potrafisz w jednym zdaniu opisać, co ten kod dziś robi? Jeśli nie, przeczytaj, zanim zaczniesz przepisywać.

W praktyce warsztatowej te sześć technik rzadko stosuje się osobno. Projekt, który dojrzewa przez rok pracy z jednym klientem, zwykle przechodzi przez wszystkie po kolei: najpierw guard clauses porządkują najbardziej bolesne funkcje, potem wydzielanie metod rozbija monolityczne pliki, a dopiero na końcu przychodzi czas na tokeny theme.json i template parts. Kolejność ma znaczenie, bo każda technika buduje na czytelności uzyskanej poprzednią.