Praca z Drupalem potrafi być niezwykle satysfakcjonująca, ale nawet doświadczeni programiści regularnie trafiają na zaskakujące błędy PHP. Część z nich wynika z samej architektury systemu, inne z nieporozumień dotyczących API Drupala lub nieprawidłowej konfiguracji środowiska. Zamiast tracić godziny na szukanie przyczyn, warto poznać najczęstsze problemy, zrozumieć, skąd się biorą, i mieć pod ręką gotowe strategie ich naprawy. Ten artykuł omawia typowe pułapki oraz dobre praktyki, które pomogą utrzymać kod stabilny, bezpieczny i łatwy w utrzymaniu.
Błędy krytyczne i fatal error w Drupal
Klasyczny fatal error: wywołanie funkcji na null
Jednym z najbardziej frustrujących błędów PHP w projektach Drupal jest fatal error typu:
Call to a member function … on null lub Call to a member function … on bool
Najczęściej przyczyna leży w założeniu, że jakiś obiekt lub tablica zawsze istnieje, podczas gdy w praktyce może zostać zwrócone null lub false. W Drupal dzieje się tak szczególnie często przy:
- Ładowaniu encji (node, user, taxonomy_term), które nie istnieją lub zostały usunięte
- Pracy z serwisami kontenera, gdy nazwa serwisu jest błędna lub został on wyłączony
- Operowaniu na polach encji, które nie są zdefiniowane we wszystkich bundle
Aby uniknąć takich błędów, należy zawsze stosować defensywną logikę. Zanim użyjesz metody na obiekcie, sprawdź, czy obiekt faktycznie istnieje:
$node = \Drupal:entityTypeManager()->getStorage('node')->load($nid);
if (!$node) {
// Logowanie błędu, przekierowanie, komunikat.
return;
}
$title = $node->label();
W module własnym warto dodać dodatkowe logowanie przy użyciu serwisu logger.channel, co pozwoli łatwiej śledzić sytuacje, w których brak danych powoduje krytyczne błędy PHP.
Fatal error przy brakujących klasach i autoloadingu
Inny częsty problem to błędy typu Class not found lub Interface not found, związane z autoloaderem Composera i systemem wtyczek Drupala. Dzieje się tak, gdy:
- Plik z klasą ma inną przestrzeń nazw niż zadeklarowana w kodzie
- Struktura katalogów nie odpowiada przestrzeni nazwy (PSR-4)
- Moduł został przeniesiony między custom a contrib bez aktualizacji namespace
Rozwiązaniem jest trzymanie się konwencji Drupala oraz standardu PSR-4. Dla modułu custom o nazwie example_module, klasy powinny mieć przestrzeń nazw:
Drupal\example_module\NazwaKatalogu\NazwaKlasy
oraz pliki powinny znajdować się w:
modules/custom/example_module/src/NazwaKatalogu/NazwaKlasy.php
Po każdej zmianie struktury katalogów lub dodaniu nowych klas warto uruchomić:
composer dump-autoload -o
i wyczyścić cache Drupala, aby upewnić się, że autoloader ma aktualne informacje.
Błędy typu memory limit exhausted
Drupal, szczególnie przy ciężkich operacjach na encjach czy migracjach, potrafi szybko zużyć dostępny limit pamięci PHP. Komunikat Allowed memory size of X bytes exhausted pojawia się często podczas:
- Masowego generowania widoków lub raportów
- Migracji danych za pomocą Migrate API
- Procesowania dużej liczby encji w jednym żądaniu
Ocena problemu wymaga rozróżnienia, czy błąd wynika z faktycznie zbyt małego limitu, czy z wycieku pamięci. W pierwszej kolejności warto:
- Zwiększyć ograniczenie memory_limit w php.ini (np. do 512M lub 1G na środowisku developerskim)
- Dostosować ustawienia w .htaccess lub konfiguracji serwera, jeśli globalna zmiana jest niemożliwa
Jeśli błędy nadal się pojawiają, trzeba przyjrzeć się kodowi. Najczęstsze problemy to:
- Przechowywanie całych kolekcji encji w pamięci zamiast przetwarzania strumieniowego
- Używanie nieograniczonych zapytań, które ładują tysiące rekordów jednocześnie
- Brak zwalniania referencji do dużych struktur danych po ich przetworzeniu
W takich przypadkach dobrze jest zastosować batch API Drupala, paginację na poziomie EntityQuery, a także profilowanie pamięci, np. poprzez dodatkowe logowanie użycia memory_get_usage w newralgicznych punktach kodu.
Ukryte błędy i wyłączone raportowanie
Niebezpieczną pułapką jest sytuacja, w której błędy PHP są tłumione na poziomie konfiguracji serwera lub Drupala. Wtedy system może działać nieprzewidywalnie, a jedyny ślad problemu to nagłe przerwy lub uszkodzone dane. W środowisku developerskim powinno się:
- Ustawić raportowanie błędów na pełne (display_errors w PHP, verbose logging w Drupal)
- Korzystać z watchdog (dblog) oraz syslog do analizy błędów
- Regularnie przeglądać raporty Recent log messages w panelu administracyjnym
Na produkcji raportowanie bezpośrednie do przeglądarki powinno być wyłączone, ale logowanie w tle musi pozostać aktywne, w przeciwnym razie analiza incydentów stanie się bardzo trudna.
Ostrzeżenia, notice i błędy typu undefined w kodzie
Undefined index i praca z tablicami renderującymi
Ostrzeżenia PHP typu Undefined index pojawiają się w Drupal wyjątkowo często, bo system intensywnie korzysta z tablic asocjacyjnych jako struktur danych oraz tablic renderujących. Typowe sytuacje to:
- Założenie, że klucz w tablicy zawsze istnieje
- Brak sprawdzenia, czy konfiguracja lub ustawienie zostało zapisane
- Manualne nadpisywanie struktur, które normalnie buduje API Drupala
Zamiast bezpośredniego odwołania $array['key'], warto używać:
- Funkcji isset lub array_key_exists
- Domyślnych wartości w przypadku brakującego klucza
Przykład bezpieczniejszego kodu:
$config = \Drupal:config('example.settings');
$value = $config->get('some_key');
if ($value === null) {
$value = 'domyślna_wartość';
}
W tablicach renderujących trzeba pamiętać o standardach Drupala: np. klucz #type, #theme, #markup, #attributes. Pomyłka w nazwie klucza może spowodować nie tylko błędy PHP, ale też całkowite zignorowanie części struktury przez system renderujący.
Undefined variable i zasięg zmiennych
Błąd Undefined variable pojawia się zwykle przez niedokładność przy refaktoryzacji kodu. Programista usuwa fragment logiki, ale pozostawia użycie zmiennej, która nie jest już wcześniej ustawiana. W kodzie Drupala jest to szczególnie zdradliwe w:
- Callbackach hooków
- Funkcjach pomocniczych wywoływanych warunkowo
- Starym kodzie proceduralnym w motywach (templates.php, preprocess funkcje)
Dobrym nawykiem jest inicjalizowanie zmiennych na początku funkcji bezpieczną wartością (null, pusta tablica, pusty ciąg znaków) oraz korzystanie z wczesnych return przy obsłudze warunków brzegowych. Ułatwia to także statyczną analizę kodu.
Deprecation notice i przestarzałe API
Nowoczesne wersje PHP oraz kolejne wydania Drupala wprowadzają ostrzeżenia typu deprecated, informujące, że dana funkcja, klasa lub metoda będzie w przyszłości usunięta. Ignorowanie tych komunikatów prowadzi do sytuacji, w której aktualizacja rdzenia lub PHP nagle powoduje lawinę poważnych błędów.
W typowym projekcie warto regularnie:
- Uruchamiać stronę z włączonym wyświetlaniem deprecation notice na środowisku testowym
- Korzystać z narzędzi typu drupal-check, phpstan, rector z profilami dla Drupala
- Zastępować przestarzałe wywołania ich zalecanymi odpowiednikami (np. serwisy zamiast statycznych funkcji)
Przykładowo w Drupal 8 i wyżej stopniowo odchodzi się od bezpośredniego użycia globalnej funkcji drupal_set_message na rzecz usług lub nowocześniejszych mechanizmów, a stare hooki są zastępowane pluginami i eventami.
Notice przy pustych polach i encjach
Kolejna kategoria notice w Drupal pojawia się przy pracy z polami encji. Założenie, że dane pole zawsze istnieje i ma wartość, jest błędne w projektach z rozbudowaną konfiguracją treści. Node typu A może mieć inne zestawy pól niż node typu B, a użytkownicy nie zawsze wypełniają wszystkie dostępne pola.
Zawsze należy stosować bezpieczny dostęp:
if ($node->hasField('field_image') && !$node->get('field_image')->isEmpty()) {
$image = $node->get('field_image')->entity;
}
Takie sprawdzenie chroni przed notice i zapobiega wywołaniu metod na pustych kolekcjach. W widokach i templatkach warto też używać warunków Twig, aby nie próbować wypisywać nieistniejących zmiennych.
Typowe błędy w konfiguracji PHP i środowiska dla Drupal
Niewłaściwa wersja PHP a zgodność Drupala
Drupal jest wrażliwy na wersję PHP. Zbyt stare wydanie powoduje brak wsparcia dla nowoczesnych konstrukcji języka, a zbyt nowe: może wywołać deprecation notice lub twarde błędy, jeśli moduły nie zostały jeszcze zaktualizowane. Przykładowo niektóre moduły z czasów Drupal 8 źle znoszą przejście na PHP 8.2 i generują:
- Błędy związane z typami (TypeError)
- Ostrzeżenia o dynamicznych właściwościach
- Problemy z przestarzałymi rozszerzeniami PHP
Przed aktualizacją PHP trzeba zawsze sprawdzić:
- Dokumentację wersji Drupala i zalecany zakres PHP
- Zgodność kluczowych modułów contrib z daną wersją PHP
- Środowisko testowe, na którym można przeprowadzić pełne testy regresji
Dzięki temu unikniesz sytuacji, w której wdrożenie nowego PHP na produkcji blokuje stronę przez krytyczne błędy, które pojawiają się dopiero po połączeniu konkretnej wersji rdzenia, modułu i języka.
Błędna konfiguracja opcache i cache w PHP
Opcache daje dużego kopa wydajności Drupalowi, ale nieprawidłowa konfiguracja prowadzi do trudnych do zdiagnozowania problemów. Często spotykanym objawem jest sytuacja, w której:
- Po wdrożeniu nowego kodu strona nadal korzysta ze starej wersji plików
- Pojawiają się losowe błędy przy częściowych aktualizacjach modułów
- Różne instancje serwera (w klastrze) mają niespójny kod
Należy upewnić się, że:
- Opcache jest skonfigurowany z odpowiednio dużą pamięcią
- Funkcje resetujące cache są używane podczas wdrożeń (np. restart PHP-FPM)
- Nie stosuje się sprzecznych ustawień dla tej samej instancji serwera
Dodatkowo Drupal sam korzysta z własnych mechanizmów cache (render cache, page cache, cache entity). Zdarza się, że programiści mylą te poziomy cache i winą za błędy PHP obarczają system cache, podczas gdy problem wynika w rzeczywistości z niekompatybilnego kodu lub struktury danych po aktualizacji.
Limit czasu wykonywania i długie procesy
Przy intensywnych zadaniach, takich jak masowa aktualizacja encji czy import danych, łatwo wpaść na limit czasu ustawiony przez PHP (max_execution_time) lub serwer WWW. Typowy objaw to:
- Niekompletne migracje
- Niedokończone zadania cron
- Losowe błędy 504 Gateway Timeout
Drupal oferuje mechanizmy batch API oraz cron queue, które pozwalają rozłożyć ciężką pracę na mniejsze porcje. W praktyce często jednak programiści implementują własne skrypty bez korzystania z tych rozwiązań. Lepiej jest:
- Projektować zadania pod kątem powtarzalnego uruchamiania w krótkich interwałach
- Świadomie używać batch API dla operacji wymagających interakcji z użytkownikiem
- Kontrolować limity czasu zarówno po stronie PHP, jak i serwera (Nginx, Apache)
Pomoże to uniknąć sytuacji, w których proces zostaje ubity po stronie serwera, a aplikacja raportuje jedynie enigmatyczny błąd połączenia lub przerwane żądanie.
Rozszerzenia PHP wymagane przez Drupal i moduły
Brakujące lub niekompatybilne rozszerzenia PHP również generują błędy, czasem dopiero w specyficznych fragmentach aplikacji. Np. brak rozszerzenia mbstring lub gd może spowodować błędy przy pracy z tekstem wielobajtowym czy obrazami. Drupal core i wiele modułów wymaga konkretnych rozszerzeń, dlatego:
- Przed instalacją trzeba zweryfikować wymagania w dokumentacji
- Na wszystkich środowiskach (dev, test, prod) powinien być zestandaryzowany zestaw rozszerzeń
- Należy monitorować zmiany wymagań przy aktualizacjach rdzenia i modułów
Rozbieżności między środowiskami są jedną z głównych przyczyn błędów, które reprodukują się tylko na produkcji, a lokalnie wszystko działa poprawnie. Automatyzacja konfiguracji serwerów (np. Ansible, Docker) znacząco redukuje to ryzyko.
Błędy w integracji modułów, hooków i serwisów
Niewłaściwe użycie hooków i konflikt modułów
System hooków jest sercem Drupala, ale też źródłem wielu subtelnych problemów. Moduły mogą wchodzić sobie w drogę, nadpisując te same elementy konfiguracji, zmieniając struktury renderujące lub modyfikując encje w sprzeczny sposób. Typowe symptomy to:
- Błędy PHP pojawiające się tylko po włączeniu określonej kombinacji modułów
- Niespójny wygląd lub brakujące pola na wybranych typach treści
- Nieprzewidywalne zachowanie formularzy i walidacji
Aby ograniczyć ryzyko, warto:
- Nadawać hookom priorytety świadomie, gdy to możliwe
- Deklarować wyraźne zależności między modułami w plikach info.yml
- Dbać o to, by hooki były jak najbardziej idempotentne i nie modyfikowały danych więcej niż raz
Gdy pojawi się błąd, dobrym podejściem jest czasowe wyłączanie modułów, aby zidentyfikować kombinację powodującą problem, a następnie dokładne przejrzenie implementacji odpowiednich hooków (np. hook_entity_presave, hook_form_alter) pod kątem niebezpiecznych założeń oraz braku walidacji danych.
Serwisy w kontenerze i błędy zależności
Drupal opiera się na kontenerze usług (service container), co ułatwia strukturę kodu, ale wprowadza nową kategorię błędów. Najczęściej spotykane problemy to:
- Błędne nazwy serwisów w plikach services.yml
- Niekompatybilne typy argumentów w konstruktorach klas serwisów
- Cykliczne zależności między serwisami prowadzące do błędów przy budowie kontenera
Typowy komunikat błędu może dotyczyć niezdolności do autowire konkretnej klasy lub braku definicji serwisu o danej nazwie. W takich sytuacjach należy:
- Sprawdzić plik modul.services.yml pod kątem literówek i poprawności kluczy
- Zwrócić uwagę na typowanie argumentów w konstruktorach (type hinting zgodny z faktycznym serwisem)
- Korzystać z interfejsów zamiast konkretnych implementacji, gdy to możliwe
Dobrą praktyką jest także ograniczenie logiki w konstruktorach i unikanie ciężkich operacji podczas budowania serwisu. Błędy w tym miejscu mogą blokować całą aplikację.
Błędy w pluginach i anotacjach
Wiele mechanizmów Drupala (blok, field type, views pluginy) jest opartych na pluginach definiowanych poprzez anotacje w docblockach. Literówka w anotacji, brak wymaganego klucza lub niezgodna nazwa plugin ID prowadzą do problemów, które objawiają się często dopiero przy próbie wyświetlenia danego elementu.
Typowe przyczyny błędów to:
- Niewłaściwa przestrzeń nazw klasy pluginu
- Brak wymaganych parametrów w anotacji, np. id, label
- Kolidujące identyfikatory pluginów między modułami
Diagnoza wymaga dokładnego przejrzenia klasy pluginu oraz porównania z oficjalnymi przykładami rdzenia lub dobrze napisanych modułów contrib. Po każdej zmianie anotacji warto wyczyścić cache Drupala, ponieważ metadane pluginów są intensywnie keszowane.
Integracja zewnętrznych bibliotek i błędy Composer
Współczesne projekty Drupal prawie zawsze korzystają z zewnętrznych bibliotek PHP poprzez Composer. Błędy pojawiają się, gdy:
- Biblioteka jest zainstalowana w innej wersji niż oczekuje moduł
- Istnieje konflikt między wymaganiami różnych modułów dla tej samej biblioteki
- Autoloading Composera nie widzi klasy, ponieważ biblioteka nie została właściwie zainstalowana
Rozwiązywanie tych problemów wymaga:
- Analizy sekcji require i require-dev w pliku composer.json
- Uważnego czytania komunikatów composera przy aktualizacjach i instalacjach
- Testowania zmian zależności na środowisku izolowanym przed wdrożeniem na produkcję
Dobrą praktyką jest także utrzymywanie jednego źródła prawdy dla zależności (główny composer.json w projekcie) oraz unikanie ręcznego umieszczania bibliotek w katalogu modules lub libraries bez zarządzania nimi przez Composer, bo utrudnia to aktualizacje i debugowanie błędów PHP powiązanych z wersjami pakietów.
Dobre praktyki zapobiegania błędom PHP w Drupal
Statyczna analiza i standardy kodu
Jednym z najskuteczniejszych sposobów walki z błędami PHP jest wprowadzenie statycznej analizy kodu oraz egzekwowanie standardów. Narzędzia takie jak phpstan, phpcs czy specjalne rozszerzenia drupal-check potrafią wykryć:
- Błędy typów i niezgodne sygnatury metod
- Potencjalne wywołania na null lub nieistniejących polach
- Naruszenia standardów formatowania i struktury kodu
W połączeniu z ciągłą integracją (CI) można zautomatyzować proces weryfikacji, tak aby do głównej gałęzi projektu trafiał tylko kod spełniający wymagania jakościowe. Dzięki temu część najczęstszych błędów w ogóle nie trafi na serwer developerski, nie mówiąc już o produkcji.
Testy jednostkowe, funkcjonalne i behawioralne
Choć pisanie testów bywa postrzegane jako kosztowny dodatek, w dłuższej perspektywie znacząco redukuje liczbę błędów PHP i regresji w systemie. Drupal dostarcza własny framework testowy, a także doskonale współpracuje z PHPUnit oraz Behat. Przydatne są szczególnie:
- Testy jednostkowe dla serwisów i klas bezpośrednio korzystających z PHP
- Testy funkcjonalne sprawdzające formularze, walidacje i przepływy użytkownika
- Testy behawioralne opisujące scenariusze biznesowe w języku zrozumiałym dla zespołu
Dobrze napisana baza testów pozwala bezpieczniej aktualizować zarówno rdzeń Drupala, jak i wersje PHP oraz biblioteki zewnętrzne, bo błędy pojawią się na etapie CI, a nie dopiero u końcowego użytkownika.
Kontrola nad procesem wdrożeń i rollback
Wiele błędów PHP w projektach Drupal ujawnia się dopiero w momencie wdrożenia nowej wersji na produkcję. Powodem jest różnica w danych, obciążeniu oraz konfiguracji środowisk. Aby zminimalizować ryzyko, warto:
- Stosować automatyczne wdrożenia z jasnym procesem build i deploy
- Opracować procedurę szybkiego rollbacku: powrotu do poprzedniej stabilnej wersji
- Wdrożyć monitoring logów oraz narzędzia APM do wychwytywania błędów po wdrożeniu
Bez takiej infrastruktury nawet drobne błędy PHP potrafią zablokować stronę na dłuższy czas, bo diagnoza jest utrudniona, a manualny powrót do poprzedniej wersji kodu bywa czasochłonny i ryzykowny.
Świadome zarządzanie modułami i techniczny dług
Na koniec warto podkreślić, że znaczna część problemów z PHP w Drupal wynika z niekontrolowanego rozrostu modułów oraz gromadzenia technicznego długu. Dodawanie kolejnych rozszerzeń bez analizy jakości kodu i aktywnych maintainerów prowadzi do sytuacji, w której system opiera się na przestarzałych, rzadko aktualizowanych pakietach. To z kolei skutkuje:
- Brakiem wsparcia dla nowych wersji PHP
- Niekompatybilnością z kolejnymi wydaniami rdzenia Drupala
- Zwiększonym ryzykiem błędów krytycznych i problemów z bezpieczeństwem
Dobrym podejściem jest okresowy przegląd zainstalowanych modułów, usuwanie nieużywanych oraz planowanie refaktoryzacji kodu custom. Konsekwentne spłacanie technicznego długu sprawia, że błędy PHP stają się rzadsze, łatwiejsze do zdiagnozowania i mniej dotkliwe dla użytkowników.
Yulia Dovha
Yulia Dovha tworzy treści dla bloga icomSEO: praktyczne poradniki o SEO, reklamie i marketingu internetowym.
