Formularze w Drupal – system Form API w praktyce

Formularze to serce pracy z danymi w Drupal. Od prostych kontaktów, przez rejestrację użytkowników, po skomplikowane kreatory – wszystko opiera się na jednym, spójnym mechanizmie: **Form API**. Dzięki niemu tworzenie i modyfikowanie formularzy jest przewidywalne, rozszerzalne oraz bezpieczne. Zamiast ręcznie sklejać HTML, developer opisuje strukturę formularza w tablicach PHP, a resztą zajmuje się **silnik Drupal**. Pozwala to skupić się na logice biznesowej, walidacji i integracjach, a nie na niskopoziomowych szczegółach.

Czym jest Form API i dlaczego jest tak ważne

Filozofia budowania formularzy w Drupal

Formularze w Drupal nie są traktowane jako przypadkowe fragmenty HTML, lecz jako struktury opisane przez rozbudowane tablice asocjacyjne PHP. Każdy element formularza to zagnieżdżona tablica z kluczami opisującymi typ pola, etykietę, domyślną wartość, walidację, renderowanie i zachowanie po przesłaniu. Taki sposób definiowania sprzyja konsekwentnej pracy nad projektem, szczególnie gdy w grę wchodzi większy zespół i rozbudowany serwis.

Kluczowe jest to, że programista nie musi ręcznie generować HTML ani dbać o niskopoziomowe szczegóły. Struktura formularza jest przekazywana do mechanizmu renderującego, który odpowiednio zamienia ją na znaczniki, integruje z motywem graficznym, a także obsługuje **tokeny bezpieczeństwa** i przekierowania. To pozwala oddzielić warstwę logiki od prezentacji. Z perspektywy utrzymania projektu i refaktoryzacji jest to rozwiązanie znacznie bardziej skalowalne niż mieszanie PHP z HTML w wielu miejscach.

Dodatkowo Form API jest ściśle zintegrowane z innymi mechanizmami Drupala: systemem uprawnień, cache, tłumaczeniami oraz systemem hooków. Dzięki temu można na przykład globalnie modyfikować formularze dostarczane przez rdzeń lub inne moduły – bez edycji ich kodu źródłowego. To jedna z najmocniejszych stron platformy: **przewidywalne rozszerzanie** istniejących funkcji bez łamania kompatybilności.

Główne zalety Form API

Form API zapewnia szereg zalet, które są szczególnie odczuwalne w średnich i dużych projektach. Po pierwsze, formularze stają się **deklaratywne** – określasz, co chcesz uzyskać, a nie jak ma wyglądać każdy znacznik. W efekcie ten sam formularz może być inaczej stylowany w zależności od motywu, a nawet inaczej renderowany w aplikacji mobilnej korzystającej z tego samego backendu.

Po drugie, Form API integruje się z mechanizmami bezpieczeństwa. Pola wrażliwe mogą być łatwo oznaczone jako wymagające specjalnych uprawnień, a tokeny CSRF są nakładane automatycznie, o ile korzystasz z przewidzianych przez Drupal mechanizmów. Wiele typowych błędów, które w klasycznych aplikacjach PHP trzeba ręcznie wychwytywać, w Drupal zostaje ograniczonych już na poziomie samego API formularzy.

Po trzecie, spójność. Niezależnie od tego, czy formularz pochodzi z modułu rdzeniowego (np. konfiguracja witryny), czy z autorskiej funkcjonalności, jego struktura i zachowanie są przewidywalne. To ogromna przewaga podczas rozbudowy serwisu – programista, który zna Form API, jest w stanie szybko odnaleźć się w nawet obcym kodzie modułu i go dostosować. Wreszcie, Form API wspiera **wielojęzyczność**, co ma znaczenie w serwisach o zasięgu międzynarodowym: etykiety i komunikaty błędów łatwo podlegają tłumaczeniom.

Ewolucja Form API między wersjami Drupal

Od Drupal 7 do Drupal 10 Form API zachowało swoją ideę, ale zmienił się styl tworzenia formularzy. W starszych wersjach dominowały funkcje proceduralne i hooki, natomiast od Drupal 8 w górę zalecany jest styl obiektowy, z klasami formularzy dziedziczącymi z FormBase i pokrewnych klas. Ta zmiana była częścią większej transformacji ekosystemu, opartej na komponentach Symfony i wzorcach programowania obiektowego.

W praktyce oznacza to, że w nowszych wersjach Drupala formularz jest klasą z metodami buildForm, validateForm, submitForm. Logika rozłożona jest czytelniej i łatwiej ją testować. Pomimo różnic implementacyjnych, główne koncepcje Form API pozostają jednak te same: struktura jako tablica elementów, centralne renderowanie, ujednolicona walidacja i system **callbacków**. Dzięki temu wiedza wypracowana w jednej wersji łatwo przekłada się na kolejne.

Podstawy pracy z Form API na przykładach

Najprostszy formularz – budowa i ścieżka

Podstawowy formularz w Drupal składa się z kilku stałych elementów: definicji trasy (route), klasy formularza oraz metod obsługujących budowę, walidację i obsługę wyników. Całość zaczyna się zwykle od dodania wpisu do pliku routingowego modułu, który wskazuje na określoną klasę formularza. Dzięki temu pod wybranym adresem URL uruchamiana jest logika Form API zamiast statycznego widoku.

Następnie definiuje się klasę formularza. W nowszych wersjach Drupala najczęściej dziedziczy ona po FormBase lub ConfigFormBase, jeśli ma służyć do zapisu konfiguracji. W metodzie buildForm tworzona jest tablica $form, która opisuje cały formularz: pola tekstowe, listy wyboru, przyciski. Zwrócenie tej tablicy sprawia, że system renderujący Drupala generuje odpowiedni HTML oraz automatycznie dodaje ukryte pola wymagane do śledzenia stanu i ochrony przed podszywaniem się pod użytkownika.

Najprostszy formularz może zawierać jedno pole tekstowe z etykietą i przyciskiem submit. Mimo tak prostej struktury korzysta on już z całej infrastruktury Form API: posiada identyfikator, stan, możliwości rozszerzenia przez inne moduły, a jego przesłanie może zostać przechwycone przez dedykowane callbacki. To dobra baza do dalszego rozwijania logiki, np. zapisu danych do bazy czy wywołania zewnętrznego API.

Elementy formularza i właściwości pól

Każdy element formularza w Form API opisuje się jako podtablicę, której klucz jest identyfikatorem pola. W jej wnętrzu określa się co najmniej typ (type), tytuł (title) i domyślną wartość (default_value). Typy pól są liczne: od zwykłego textfield, textarea, przez select, checkbox i radios, aż po wyspecjalizowane elementy jak entity_autocomplete czy managed_file. To, jakie typy są dostępne, zależy także od modułów zainstalowanych w systemie.

Właściwości takie jak required, description, maxlength czy placeholder pozwalają precyzyjniej kontrolować zachowanie formularza oraz doświadczenie użytkownika. Dzięki spójnej strukturze wszystkie pola korzystają z tych samych kluczy konfiguracyjnych, więc raz nauczona składnia działa w wielu kontekstach. Dodatkowo Form API umożliwia definiowanie atrybutów HTML (np. data-*), klas CSS oraz warunkowego wyświetlania poszczególnych elementów, co przydaje się w bardziej zaawansowanych przypadkach.

Ważnym aspektem jest integracja z systemem tłumaczeń Drupala. Etykiety, opisy i komunikaty walidacyjne mogą być przygotowane pod tłumaczenia za pomocą funkcji translacyjnych. To zapewnia, że ten sam **formularz wielojęzyczny** prezentuje poprawne teksty w języku użytkownika, bez konieczności duplikowania logiki. W dużych serwisach jest to nieodzowne, bo znacznie upraszcza utrzymanie wielojęzycznych interfejsów.

Obsługa wysyłki: validate i submit

Formularz w Drupal ma zazwyczaj co najmniej dwa etapy przetwarzania po kliknięciu przycisku: walidację oraz obsługę złożenia. W metodzie validateForm wykonywana jest weryfikacja danych pod kątem poprawności biznesowej – np. sprawdzenie, czy adres e-mail jest z unikalnej domeny albo czy użytkownik nie przekracza jakiegoś limitu. Jeśli coś jest nieprawidłowe, dodaje się komunikat błędu powiązany z konkretnym polem lub całym formularzem, co blokuje dalsze przetwarzanie.

Jeśli wszystkie warunki zostaną spełnione, wywoływana jest metoda submitForm. Tu umieszcza się logikę, która ma zostać wykonana po poprawnym przesłaniu: zapis do bazy, utworzenie encji, wysłanie maila lub wywołanie zewnętrznego **API integracyjnego**. Architektura Form API pozwala też na definiowanie dodatkowych callbacków walidacyjnych i submit dla konkretnych przycisków. Można więc łatwo obsłużyć różne scenariusze w zależności od tego, czy użytkownik kliknął Zapisz, Zastosuj filtr czy Eksportuj.

Istotne jest też zarządzanie przekierowaniami po wysłaniu formularza. W Drupalu można określić, dokąd ma zostać przekierowany użytkownik po sukcesie, ustawić komunikaty typu status (np. Dane zapisane poprawnie) oraz zadecydować, jakie dane formularza powinny zostać zachowane w stanie, a jakie wyczyszczone. Dzięki temu użytkownik ma poczucie spójnego przepływu, a programista kontroluje pełną ścieżkę interakcji.

Najczęstsze błędy początkujących

Osoby zaczynające pracę z Form API często próbują traktować formularz jako zwykły HTML i ręcznie dodawać znaczniki, co omija główne zalety systemu. Typowym błędem jest też bezpośredni odczyt danych z $_POST zamiast korzystania z obiektu FormStateInterface, który zapewnia bezpieczny i ustandaryzowany dostęp do wartości pól. W efekcie takie podejście prowadzi do kodu trudnego w utrzymaniu i niespójnego z resztą ekosystemu.

Innym problemem bywa pomijanie walidacji po stronie serwera. Nawet jeśli zastosujemy rozbudowaną walidację po stronie klienta (JavaScript), nie można polegać wyłącznie na niej, gdyż dane mogą zostać zmodyfikowane przed wysłaniem. Form API daje gotowy mechanizm dodawania błędów walidacyjnych; korzystanie z niego jest obowiązkowe, jeśli chcemy zachować kontrolę nad integralnością danych. Brak konsekwencji w dodawaniu komunikatów błędów obniża również komfort użytkownika, który nie wie, co zrobił nie tak.

Kłopotliwe może być także mieszanie logiki biznesowej w metodzie buildForm. Nowicjusze czasem ładują tam zbyt wiele operacji, które powinny znajdować się w metodach walidacyjnych lub submit. Efektem jest niepotrzebne komplikowanie procesu renderowania, wydłużone czasy odpowiedzi oraz trudności z testowaniem. Lepszym podejściem jest trzymanie się rozdziału odpowiedzialności: budowa formularza w jednej metodzie, sprawdzanie poprawności w drugiej, a obsługa zapisu danych w kolejnej.

Zaawansowane techniki: AJAX, stan i alterowanie formularzy

Dynamiczne formularze z AJAX

Jedną z kluczowych możliwości Form API jest obsługa dynamicznych formularzy z wykorzystaniem AJAX. Zamiast przeładowywać całą stronę przy każdej zmianie, można zdefiniować callback, który zostanie wywołany po zmianie wartości konkretnego pola. Fragment formularza zostanie wówczas ponownie wyrenderowany i wymieniony bez pełnego odświeżania. To szczególnie przydatne przy wybieraniu zależnych opcji, filtrowaniu list czy budowaniu rozbudowanych kreatorów.

Aby skorzystać z AJAX, w konfiguracji elementu formularza dodaje się odpowiednią sekcję, w której określa się event (np. change, click), callback oraz selektor elementu, który ma zostać podmieniony. W callbacku budowany jest fragment formularza, a Drupal zajmuje się resztą: generuje odpowiedź JSON zawierającą zaktualizowany HTML i skrypt, który go wstawi we właściwe miejsce. Dzięki temu nawet skomplikowane zależności mogą być zarządzane centralnie, bez pisania nadmiarowego JavaScriptu.

Dynamiczne zachowania formularzy mogą wymagać także korzystania ze stanu elementów (states), który pozwala sterować tym, czy pole jest widoczne, wymagane lub aktywne w zależności od wartości innych pól. States można łączyć z AJAX, budując w pełni interaktywne formularze, które reagują na decyzje użytkownika. Wszystko to pozostaje jednak w ramach ujednoliconej struktury Form API, co ułatwia debugowanie i utrzymanie.

Praca ze stanem formularza (FormStateInterface)

FormStateInterface jest centralnym elementem odpowiedzialnym za przechowywanie stanu formularza: zawartości pól, błędów walidacyjnych, informacji o tym, który przycisk został wciśnięty, oraz danych pomocniczych używanych w poszczególnych krokach przetwarzania. Zamiast bezpośrednio odczytywać wartości z superglobali, stosuje się metody getValue, getValues i powiązane. To nie tylko zwiększa bezpieczeństwo, ale także ułatwia testowanie funkcji formularza.

W stanie można przechowywać również dane tymczasowe, które są potrzebne jedynie w trakcie życia formularza, np. bieżący krok kreatora, tymczasowe identyfikatory plików czy wyniki pośrednich obliczeń. Dzięki temu logika obsługi jest **kapsułkowana** w obrębie jednego obiektu, a nie rozproszona po różnych globalnych tablicach. Ma to ogromne znaczenie przy budowie wieloetapowych formularzy, gdzie poszczególne kroki muszą pamiętać o wyborach użytkownika z poprzednich ekranów.

FormStateInterface dostarcza także metody do zarządzania przekierowaniami, komunikatami oraz flagami, które pozwalają wpływać na dalszy przebieg przetwarzania. Wywołując odpowiednie funkcje, można np. zatrzymać przebudowę formularza, wymusić powrót do innego kroku czy zmienić miejsce, do którego trafi użytkownik po zakończeniu interakcji. Świadome korzystanie z tych mechanizmów jest jednym z wyznaczników dojrzałego korzystania z Form API.

Alterowanie istniejących formularzy (hook_form_alter)

Jedną z najpotężniejszych funkcji Drupala jest możliwość modyfikowania istniejących formularzy przy pomocy hook_form_alter i pokrewnych mechanizmów. Pozwala to na dodanie nowych pól, zmianę etykiet, ukrycie zbędnych elementów czy podpięcie dodatkowej walidacji – bez edycji kodu modułu, który formularz pierwotnie dostarczył. To fundament modułowej architektury Drupala i główny powód, dla którego platforma jest tak elastyczna.

Hook_form_alter przyjmuje tablicę formularza oraz nazwę form_id, co pozwala warunkowo reagować tylko na wybrane formularze. W jego wnętrzu można modyfikować strukturę elementów, dodawać własne callbacki walidacyjne i submit oraz wpływać na sposób renderowania. Dzięki temu administrator serwisu lub programista wdrożeniowy może dostosować standardowe formularze (np. edycję węzłów, profile użytkowników) do specyficznych potrzeb projektu, nie zrywając przy tym kompatybilności z rdzeniem.

Istnieją też bardziej wyspecjalizowane warianty, takie jak hook_form_FORM_ID_alter, które odnoszą się do konkretnego formularza, oraz mechanizmy oparte na usługach i eventach w nowszych wersjach Drupala. Niezależnie od sposobu, sedno pozostaje to samo: formularze są otwarte na modyfikacje w sposób przewidywalny i kontrolowany. To umożliwia budowę rozbudowanych systemów z wieloma niezależnymi modułami, które wspólnie wpływają na ten sam formularz, nie wchodząc sobie w drogę.

Formularze wieloetapowe i kreatory

Wielokrokowe formularze (tzw. wizardy) to częsty wymóg w bardziej zaawansowanych aplikacjach, np. przy składaniu złożonych zamówień, konfiguracji produktów czy przeprowadzaniu użytkownika przez proces rejestracji z wieloma opcjami. Form API oferuje kilka wzorców, które ułatwiają tworzenie takich rozwiązań. Bazują one na łączeniu stanu formularza, przekazywaniu ukrytych danych między krokami oraz odpowiednim sterowaniu przebudową.

Typowy kreator wykorzystuje specjalne przyciski Nawiguj dalej/Wstecz, które mają własne callbacki submit i, w zależności od decyzji użytkownika, aktualizują bieżący krok w stanie formularza. Metoda buildForm buduje strukturę pól na podstawie aktualnego kroku, więc po każdej zmianie zostaje on przebudowany i zaprezentowany użytkownikowi w nowej formie, ale z zachowaniem już wprowadzonych danych. Walidacja może być wykonywana częściowo na poszczególnych krokach lub zbiorczo na końcu, w zależności od wymagań projektu.

Warto pamiętać, że wieloetapowe formularze bardzo zyskują na integracji z AJAX i states, ponieważ pozwala to minimalizować przeładowania i ułatwia użytkownikowi orientację w procesie. Dzięki Form API te złożone zachowania nie wymagają jednak tworzenia osobnych kontrolerów dla każdego kroku – wszystko skupia się w jednej klasie formularza, co znacząco poprawia czytelność i utrzymanie kodu, zwłaszcza w rozbudowanych wdrożeniach biznesowych.