Routing w Drupal – jak działa system tras

System tras w Drupal to fundament, na którym opiera się cały mechanizm obsługi adresów URL, kontrolerów i stron w serwisie. Zrozumienie routing’u pozwala nie tylko poprawnie tworzyć własne moduły, ale też skutecznie diagnozować błędy, optymalizować wydajność i budować rozbudowane aplikacje. Poznanie zasad działania tras to krok w stronę pełnego wykorzystania możliwości frameworka, na którym zbudowany jest Drupal.

Podstawy systemu tras w Drupal

Od hook_menu do systemu routingu

W starszych wersjach Drupala (do 7) głównym narzędziem do definiowania stron był hook_menu. W Drupal 8 i nowszych zastąpił go nowoczesny system routingu oparty na komponentach Symfony. Każda trasa jest teraz opisana w pliku YAML, co wprowadza większą spójność, przejrzystość i lepszą integrację z resztą frameworka.

Routing jest dziś ściśle powiązany z koncepcją kontrolerów, parametrów i uprawnień. Gdy użytkownik wywołuje konkretny adres URL, Drupal dopasowuje go do zarejestrowanej trasy, sprawdza wymogi (np. dostęp, format żądania) i wywołuje przypisany kontroler lub callback. To odejście od wcześniejszego, monolitycznego podejścia hook_menu, na rzecz architektury zorientowanej na klasy i metody.

Kluczowe pojęcia: url, ścieżka, trasa

W codziennej pracy pojęcia „URL”, „ścieżka” i „trasa” bywają używane zamiennie, ale w Drupal mają konkretne znaczenie techniczne:

• URL – pełny adres internetowy widoczny w przeglądarce, wraz z domeną, protokołem i parametrami zapytania.
• Ścieżka – część URL po domenie, np. node/1, user/login, admin/content.
• Trasa – wewnętrzna definicja w systemie Drupala, powiązana z określoną ścieżką lub wzorcem ścieżki, zawierająca informacje o tym, co ma się stać po wywołaniu danego adresu.

Routing decyduje, która trasa zostanie dopasowana do danej ścieżki. Następnie, na podstawie konfiguracji trasy, Drupal uruchamia logikę aplikacji – np. wyświetla stronę, uruchamia formularz lub zwraca dane w formacie JSON.

Rola Symfony Routing Component

Drupal wykorzystuje Symfony Routing Component jako fundament swojego systemu tras. Oznacza to, że wiele mechanizmów, takich jak dopasowywanie ścieżki z parametrami, obsługa prefixów, wymagania typów, opiera się na sprawdzonym, szeroko stosowanym rozwiązaniu znanym także z innych frameworków PHP.

W praktyce oznacza to, że:

• składnia definicji tras jest zbliżona do tej, którą znają programiści Symfony,
• można wykorzystywać złożone wzorce ścieżek (np. z parametrami, ograniczeniami, opcjami),
• system jest rozszerzalny i dobrze integruje się z innymi komponentami, takimi jak event dispatcher czy dependency injection.

Wczytywanie i magazynowanie tras

Trasy są wczytywane z kilku źródeł:

• plików YAML modułów i motywów,
• tras generowanych dynamicznie (np. poprzez route subscriberów),
• tras pochodzących z podsystemów, takich jak Entity API, Views czy lokalizacja.

Po zebraniu wszystkich definicji, Drupal kompiluje je do postaci zoptymalizowanej i przechowuje w cache. Dzięki temu dopasowywanie tras jest bardzo szybkie podczas obsługi żądań HTTP. Zmiany w plikach routingu wymagają zazwyczaj wyczyszczenia cache, aby system ponownie odczytał i przetworzył nowe konfiguracje.

Definiowanie tras w plikach routing.yml

Struktura pliku routing.yml w module

Każdy moduł, który chce zarejestrować własne trasy, musi utworzyć plik o nazwie nazwa_modulu.routing.yml. W tym pliku umieszcza się definicje tras w formacie YAML, gdzie kluczem głównym jest identyfikator trasy, a pod nim znajdują się właściwości opisujące daną trasę.

Przykładowa struktura pojedynczej trasy obejmuje:

• identyfikator (np. my_module.example),
• path – ścieżkę URL, np. /example/page,
• defaults – tablicę ustawień domyślnych (np. kontroler, tytuł strony),
• requirements – warunki dostępu (np. uprawnienia, rola użytkownika, metoda HTTP),
• options – dodatkowe opcje, np. parametry dla menu, ścieżek kanonicznych czy cache.

Prawidłowe wcięcia i składnia YAML są krytyczne. Błąd formatowania może spowodować, że cały plik routing.yml zostanie zignorowany lub generować trudne do zdiagnozowania błędy podczas instalacji modułu.

Najważniejsze klucze: path, defaults, requirements

Trzy najistotniejsze części definicji trasy to path, defaults oraz requirements. Od ich zrozumienia zależy właściwe mapowanie żądań na logikę aplikacji.

• path określa, pod jaką ścieżką dostępna będzie trasa. Może zawierać stałe fragmenty oraz parametry w nawiasach klamrowych, np. /article/{node}.
• defaults zawiera ustawienia domyślne:
  • _controller – wskazuje metodę klasy kontrolera, która będzie wywołana,
  • _title lub _title_callback – definiuje tytuł strony w interfejsie,
  • inne klucze używane przez konkretne podsystemy (np. formy, render arrays).
• requirements określa warunki, jakie muszą zostać spełnione:
  • _permission – wymagane uprawnienie (np. access content),
  • _role – wymagana rola użytkownika,
  • _access lub _custom_access – odwołanie do metody sprawdzającej dostęp,
  • _method – dopuszczalne metody HTTP (GET, POST itd.).

Parametry w trasach i ich walidacja

Parametry w ścieżkach umożliwiają tworzenie dynamicznych tras, np. /blog/{id}, /user/{user}. Dzięki nim można obsługiwać wiele zasobów jedną definicją trasy, przekazując różne wartości do kontrolera.

W systemie Drupala parametry mogą być:

• prostymi wartościami (np. liczby, ciągi znaków),
• bezpośrednio mapowane na obiekty encji (np. {node}, {user}),
• wzbogacone o ograniczenia typów, np. wymagające formatu liczbowego,
• podlegające automatycznej konwersji przez tzw. param converters.

Walidacja parametrów odbywa się poprzez sekcję requirements, np. przy użyciu wyrażeń regularnych, lub poprzez własne metody dostępowe. Pozwala to wymusić, by trasa była dopasowywana wyłącznie wtedy, gdy parametr ma odpowiedni format czy spełnia określone warunki biznesowe.

Opcje trasy i rozszerzenia

Sekcja options w definicji trasy umożliwia bardziej zaawansowaną konfigurację. Można tam określić np.:

• parametry dotyczące cache (np. schematy kontekstu),
• powiązania z systemem menu i breadcrumbs,
• flagi dla tras administracyjnych (ułatwiające stosowanie motywów czy ochronę dostępu),
• dodatkowe metadane wykorzystywane przez inne moduły.

Dzięki options twórcy modułów mogą opisywać specyficzne właściwości trasy bez konieczności tworzenia złożonych rozszerzeń w kodzie PHP. To ułatwia współpracę między modułami i pozwala na bardziej deklaratywny styl programowania.

Kontrolery, formularze i inne celowe typy tras

Trasa prowadząca do kontrolera

Najczęstszym scenariuszem jest trasa, która wskazuje na metodę kontrolera. W defaults ustawiamy wtedy klucz _controller w postaci nazwa_klasy::metoda. Kontroler zwraca strukturę renderującą (render array) lub odpowiedź HTTP, którą Drupal przekształca w finalny HTML.

Taki mechanizm umożliwia:

• rozdzielenie logiki biznesowej od routingu,
• wstrzykiwanie zależności przez kontener usług (dependency injection),
• łatwe testowanie poszczególnych metod kontrolera,
• ponowne wykorzystanie tej samej logiki w wielu trasach.

Kontrolery są centralnym elementem w architekturze MVC, którą Drupal adaptuje na swoje potrzeby. W połączeniu z routingiem budują elastyczną, modularną strukturę całej aplikacji.

Trasy formularzy: _form i Form API

Oprócz klasycznych kontrolerów, Drupal udostępnia specjalny typ trasy kierujący do klasy formularza. W takim przypadku w defaults używamy klucza _form, wskazując klasę implementującą FormBase lub inny wariant Form API.

Tego typu trasy są idealne dla:

• formularzy konfiguracji modułów,
• formularzy administracyjnych,
• formularzy złożonych interfejsów użytkownika (np. kreatory, konfiguratory, panele).

Routing i formularze są ze sobą ściśle połączone: trasa określa, jak dotrzeć do danego formularza, a klasa formularza definiuje logikę walidacji, zapisu i prezentacji. W zależności od potrzeb możemy łączyć je z określonymi uprawnieniami, aby np. tylko administrator mógł otworzyć dany ekran konfiguracyjny.

Trasy dla encji i widoków (Views)

System Entity API automatycznie generuje wiele tras dla encji, takich jak node, user czy taxonomy term. Obejmuje to m.in. trasy kanoniczne (strona encji), trasy edycji, usuwania i inne operacje. Twórcy własnych typów encji mogą konfigurować, jakie trasy mają być generowane i jak mają wyglądać.

Podobnie moduł Views tworzy trasy odpowiadające poszczególnym wyświetleniom (displays). Jeśli zdefiniujemy w widoku wyświetlenie typu „Page”, to w konfiguracji widoku ustawiamy ścieżkę, a Views zarejestruje odpowiednią trasę. Dzięki temu wiele elementów routingu może być definiowanych z poziomu interfejsu, bez pisania plików YAML.

Specjalne typy tras i odpowiedzi

Drupal obsługuje różne typy odpowiedzi powiązane z trasami:

• klasyczne strony HTML (render arrays),
• odpowiedzi JSON, używane np. w Web Services,
• strumienie plików, przekierowania, odpowiedzi błędów,
• odpowiedzi asynchroniczne (np. AJAX) oparte na Form API.

Odpowiedni dobór kontrolera, formularza lub innego mechanizmu pozwala wykorzystać routing również w API, integracjach z aplikacjami zewnętrznymi czy niestandardowych interfejsach. Trasy stają się uniwersalnym punktem wejścia do wszystkich funkcjonalności witryny.

Bezpieczeństwo, dostęp i konteksty w routingu

Uprawnienia i role w requirements

Kontrola dostępu do tras jest kluczowa z punktu widzenia bezpieczeństwa. W sekcji requirements można określić, jakie uprawnienia lub role są wymagane, aby użytkownik mógł odwiedzić dany adres. Standardowo korzysta się z klucza _permission, ale dostępne są także inne mechanizmy.

Przykłady zastosowań:

• udostępnianie paneli administracyjnych tylko użytkownikom z określoną rolą,
• ograniczanie dostępu do danych tylko dla zalogowanych,
• wyświetlanie stron wrażliwych (np. raportów) wyłącznie dla wybranych grup.

Staranna konfiguracja uprawnień w trasach pomaga unikać przypadkowego ujawnienia danych, nadmiarowych funkcji administracyjnych czy luk wynikających z przeoczeń w kontrolerach.

Custom access: logika w kodzie PHP

Niektóre przypadki wymagają bardziej złożonej logiki niż proste sprawdzenie uprawnienia. W takich sytuacjach stosuje się custom access, czyli metodę w kontrolerze lub serwisie, która decyduje, czy dostęp powinien zostać przyznany.

Metoda access może brać pod uwagę m.in.:

• stan encji (np. czy jest opublikowana),
• relację użytkownika do zasobu (np. autorstwo treści),
• parametry przekazane w ścieżce,
• aktualny czas, konfigurację czy inne warunki biznesowe.

Zwracając odpowiedni obiekt AccessResult, możemy nie tylko przyznać lub odmówić dostępu, ale także powiązać wynik z systemem cache, co ma znaczenie dla wydajności strony.

Konteksty i cache a routing

System cache w Drupalu jest ściśle powiązany z routingiem i dostępem. Wynik kontroli dostępu, a także generowana odpowiedź, mogą zależeć od różnych kontekstów, takich jak aktualny użytkownik, język, ścieżka czy format odpowiedzi.

Dzięki kontekstom cache Drupal potrafi przechowywać różne wersje tej samej strony dla odmiennych warunków (np. innego użytkownika czy języka), jednocześnie minimalizując liczbę koniecznych obliczeń. Trasy mogą określać, od jakich kontekstów zależą, co daje dużą kontrolę nad równowagą między wydajnością a personalizacją.

Najczęstsze błędy bezpieczeństwa związane z trasami

Przy projektowaniu tras warto unikać kilku typowych błędów:

• brak żadnych requirements, co udostępnia stronę wszystkim,
• wykorzystanie zbyt ogólnych uprawnień (np. access content) do wrażliwych funkcji,
• brak custom access tam, gdzie bezpieczeństwo zależy od parametrów,
• ignorowanie wpływu tras na cache i potencjalne ujawnienie danych w pamięci podręcznej.

Świadome używanie sekcji requirements i metod dostępowych jest tak samo ważne, jak poprawne napisanie kontrolera. Błędna konfiguracja routingu może zniweczyć zabezpieczenia zaimplementowane na poziomie logiki aplikacji.

Zaawansowane techniki pracy z routingiem

Param converters i automatyczne ładowanie encji

Param converters to mechanizm, który zamienia wartości parametrów ścieżki na obiekty PHP, najczęściej encje. Jeśli w ścieżce użyjemy {node}, a w definicji trasy zadeklarujemy odpowiedni typ, Drupal automatycznie załaduje obiekt Node dla danego identyfikatora lub aliasu.

Korzyści z używania param converters:

• mniej kodu w kontrolerach (brak ręcznego ładowania encji),
• spójna obsługa błędu 404 w przypadku braku encji,
• łatwiejsze testowanie i czytelniejszy kod,
• możliwość rejestrowania własnych converterów dla specyficznych typów danych.

Param converters integrują się z systemem bezpieczeństwa i cache, co sprawia, że są ważną częścią zaawansowanego korzystania z tras.

Route subscribers i modyfikowanie istniejących tras

Często potrzebne jest zmodyfikowanie tras zdefiniowanych przez inne moduły – np. zmiana uprawnień, ścieżek czy kontrolerów. Do tego celu służą route subscribers, czyli klasy nasłuchujące na zdarzenie generowania kolekcji tras.

Za ich pomocą można:

• zmienić wymagania dostępu istniejącej trasy,
• podmienić kontroler lub formularz,
• dodać dodatkowe opcje do trasy,
• warunkowo usuwać lub wyłączać trasy w określonych sytuacjach.

Dzięki takim rozszerzeniom routing staje się plastyczny i podatny na modyfikacje bez konieczności ingerencji w kod źródłowy innych modułów.

Local tasks, local actions i menu a routing

System menu w Drupal 8+ jest zbudowany na szczycie routingu. Local tasks (zakładki), local actions (akcje kontekstowe) i linki menu odwołują się do tras zamiast do „gołych” ścieżek. To oznacza, że:

• dodanie zakładki zazwyczaj polega na wskazaniu identyfikatora trasy nadrzędnej i podrzędnej,
• zmiana ścieżki trasy nie wymaga modyfikowania wszystkich miejsc, gdzie występują linki – odwołania są po identyfikatorach,
• menu i breadcrumbs mogą lepiej reagować na zmiany w systemie tras.

Rozumienie relacji między trasami a menu jest szczególnie istotne przy budowaniu rozbudowanych paneli administracyjnych, gdzie wiele ekranów musi być spójnie połączonych za pomocą zakładek i nawigacji.

Debugowanie i narzędzia developerskie

Praca z routingiem bywa trudna, dlatego warto korzystać z narzędzi wspierających debugowanie. Najczęstsze techniki to:

• użycie Drush lub konsoli do wylistowania tras i sprawdzania szczegółów ich konfiguracji,
• włączenie trybu debug w usługach odpowiedzialnych za routing,
• monitorowanie logów watchdog i PHP w poszukiwaniu błędów YAML czy kolizji identyfikatorów,
• wykorzystanie narzędzi deweloperskich przeglądarki do analizy nagłówków odpowiedzi i kodów statusu.

System tras jest jednym z najbardziej krytycznych elementów aplikacji Drupal. Dobre zrozumienie jego działania, narzędzi i pułapek pozwala budować stabilne, bezpieczne i łatwo rozszerzalne serwisy, w pełni wykorzystujące potencjał frameworka i możliwości, jakie daje nowoczesny routing oparty na komponentach Symfony.