Struktura plików Drupala – co znajduje się w poszczególnych katalogach

Struktura plików w systemie Drupal potrafi na początku onieśmielać rozbudowaną hierarchią katalogów i dużą liczbą plików. Dobra znajomość tej struktury jest jednak kluczem do sprawnego tworzenia motywów, modułów oraz bezpiecznego zarządzania aktualizacjami. Zrozumienie, które foldery są przeznaczone na kod rdzenia, a które na własne rozszerzenia, pozwala uniknąć nadpisania zmian przy aktualizacji i ułatwia przenoszenie projektu między środowiskami. Poniżej znajduje się szczegółowy przewodnik po najważniejszych katalogach instalacji Drupala.

Główna struktura katalogów Drupala

Najważniejsze katalogi w katalogu głównym

Po świeżej instalacji Drupala w katalogu głównym projektu zobaczysz kilka kluczowych folderów: core, modules, themes, profiles, sites oraz pliki takie jak index.php, autoload.php czy composer.json. Każdy z tych elementów pełni odrębną rolę w architekturze systemu.

Katalog core zawiera cały kod rdzenia Drupala – wszystkie mechanizmy odpowiedzialne za routing, system wtyczek, konfigurację, obsługę encji, translacje i warstwę bazodanową. Nie należy w nim modyfikować żadnych plików, ponieważ przy aktualizacji rdzenia wszystkie lokalne zmiany zostałyby nadpisane. Z punktu widzenia programisty, katalog ten jest obszarem tylko do odczytu.

Katalog modules w katalogu głównym jest przeznaczony przede wszystkim dla modułów udostępnianych jako część projektu, np. gdy tworzysz dystrybucję lub repozytorium zawierające gotowy pakiet funkcjonalności. W nowszych wersjach Drupala rekomenduje się jednak trzymanie własnych modułów w sites/default/modules lub w dodatkowych ścieżkach zarządzanych przez Composer, oddzielając je od kodu rdzenia.

Katalog themes pełni analogiczną funkcję dla motywów. Można w nim umieszczać zarówno motywy pobrane z serwisu Drupal.org, jak i własne. Praktyka produkcyjna sprowadza się często do przechowywania motywów w strukturze powiązanej z Composerem, ale mechanizm rozpoznawania motywów pozostaje ten sam: Drupal skanuje katalogi themes oraz themes w strukturze sites, szukając plików .info.yml.

Katalog profiles gromadzi tzw. profile instalacyjne. Są to pakiety konfiguracji i rozszerzeń, które pozwalają przeprowadzić instalację Drupala od razu z prekonfigurowanym zestawem modułów, typów zawartości i ustawień. W praktyce wykorzystuje się je przy tworzeniu rozbudowanych dystrybucji lub produktów opartych o Drupal, które mają być powtarzalnie wdrażane w wielu instancjach.

Rola plików w katalogu głównym

W katalogu głównym obok folderów znajdują się także pliki, które spajają działanie całego systemu. Plik index.php pełni rolę głównego punktu wejścia aplikacji – każde żądanie HTTP w typowej konfiguracji serwera kierowane jest właśnie do niego, a następnie Drupal uruchamia własny mechanizm bootstrappingu, przekazuje żądanie do warstwy routingu i zwraca odpowiedź.

Plik autoload.php obsługuje mechanizm automatycznego ładowania klas PHP, oparty na standardzie PSR-4 i konfiguracji Composer. Dzięki temu nie ma potrzeby ręcznie dołączać każdego pliku z klasą; wystarczy przestrzegać konwencji nazw przestrzeni i struktury katalogów.

Plik composer.json definiuje zależności całego projektu – zarówno rdzenia Drupala, jak i modułów czy bibliotek zewnętrznych. W praktyce większość współczesnych instalacji Drupala opiera się na zarządzaniu kodem właśnie przez Composer, co oznacza, że wiele katalogów (np. vendor) jest generowanych automatycznie i nie powinno być ręcznie modyfikowanych.

Dodatkowe pliki, takie jak robots.txt, .htaccess (lub odpowiednie reguły serwera Nginx), zapewniają właściwą komunikację z wyszukiwarkami, ustawienia przepisywania adresów URL oraz minimalne zabezpieczenia dostępu do wrażliwych katalogów, jak sites czy pliki tymczasowe.

Katalog vendor i biblioteki zewnętrzne

Katalog vendor jest tworzony przez Composer i przechowuje biblioteki zewnętrzne, od których zależy Drupal i używane moduły. Znajdziemy tam framework Symfony, komponenty Guzzle, narzędzia testowe i wiele innych pakietów PHP. Struktura tego katalogu jest ściśle związana z plikiem composer.json i plikiem composer.lock.

Kluczowym aspektem jest fakt, że katalog vendor nie jest miejscem na ręczne dodawanie własnego kodu. Wszystkie zmiany w tym obszarze powinny być realizowane przez Composer, aby zachować spójność wersji, możliwość odtwarzania środowiska oraz bezpieczeństwo aktualizacji. W praktyce oznacza to, że jeśli potrzebujesz nowej biblioteki, dodajesz ją przez composer require, a nie kopiujesz ręcznie do vendor.

Współpraca między katalogiem vendor a katalogiem core opiera się na autoloaderze – Drupal wykorzystuje klasy z vendor podobnie jak własne, traktując je jako część spójnego ekosystemu. Dobra znajomość tego podziału ułatwia rozumienie, skąd pochodzą poszczególne klasy PHP i jak rozwiązywać ewentualne konflikty wersji.

Katalog core – serce systemu Drupal

Struktura wewnętrzna katalogu core

Katalog core zawiera wszystkie elementy stanowiące fundament działania Drupala. Wewnątrz znajdziesz m.in. podkatalogi lib, modules, themes, includes, misc, assets oraz config. W nowoczesnych wersjach Drupala kod jest uporządkowany w przestrzenie nazw i katalogi zgodnie z PSR-4, co znacząco ułatwia odnajdywanie klas i serwisów.

Podkatalog core/modules gromadzi moduły rdzeniowe, takie jak Node, User, System, Field, Views czy Block. Każdy z nich ma własną strukturę plików: plik .info.yml z metadanymi modułu, pliki .module, .install, a także katalogi src na klasy PHP, templates na szablony Twig oraz config/install na domyślne konfiguracje. Dzięki temu moduły rdzeniowe są zorganizowane dokładnie tak samo, jak moduły tworzone przez społeczność.

Podkatalog core/themes zawiera motywy dołączone do rdzenia, np. Bartik czy Claro, które służą jako referencja dobrych praktyk przy tworzeniu własnych motywów. Struktura tych motywów pokazuje, jak organizować pliki .info.yml, pliki Twig, zasoby CSS i JavaScript oraz konfigurację bibliotek.

Mechanizmy systemowe ukryte w core

W katalogu core znajdują się również kluczowe mechanizmy systemowe, m.in. obsługa eventów, pluginów, kontener zależności (service container), system uprawnień, obsługa cache oraz system konfiguracji. Zazwyczaj kod ten jest rozmieszczony w przestrzeniach nazw DrupalCore i ich podprzestrzeniach, co można prześledzić w katalogu core/lib.

Podkatalog core/lib/Drupal/Core zawiera serca wielu podsystemów: klas odpowiedzialnych za routing, kontrolery, form API, system renderowania, mechanizmy queue, lock, cron i inne. Znajomość tych miejsc jest kluczowa dla programistów piszących zaawansowane moduły, ponieważ pozwala korzystać z istniejących usług zamiast implementować własne rozwiązania od zera.

Ważną częścią katalogu core jest też obszar odpowiedzialny za testy. Rdzeń Drupala dostarcza bogaty zestaw testów jednostkowych i funkcjonalnych, które są umieszczone w odpowiednich katalogach testowych. Analiza tych testów pomaga zrozumieć, jak oczekiwane jest działanie poszczególnych klas i serwisów oraz jak pisać własne testy w projektach opartych na Drupal.

Aktualizacje rdzenia a modyfikacje w core

Jedną z najistotniejszych zasad pracy z Drupala jest zakaz modyfikowania plików w katalogu core. Każda aktualizacja rdzenia – czy to za pomocą Composer, czy ręcznie – nadpisuje zawartość tego katalogu. Oznacza to, że wszystkie własne zmiany wprowadzone bezpośrednio w plikach core zostałyby utracone, a proces migracji mógłby stać się nieprzewidywalny.

Jeśli potrzebujesz zmienić zachowanie którejś z funkcji rdzeniowych, stosuj mechanizmy przewidziane przez Drupal: system hooków, pluginów, serwisy w kontenerze, event subscriberów czy rozszerzanie klas przez dziedziczenie. Wszystkie te techniki pozwalają bardzo głęboko modyfikować logikę Drupala bez dotykania kodu w katalogu core.

Zrozumienie, że katalog core jest traktowany jako zewnętrzna zależność, podobnie jak biblioteki w vendor, pomaga utrzymać projekt w stanie, który jest łatwy do aktualizacji i przenoszenia. To kluczowy element profesjonalnego podejścia do administracji i rozwoju serwisów opartych na Drupal.

Katalog sites – konfiguracja, pliki i multisite

Struktura sites/default i plik settings.php

Katalog sites to miejsce, gdzie przechowywane są ustawienia konkretnych instalacji oraz dane specyficzne dla danego środowiska. Najczęściej wykorzystywany jest podkatalog sites/default, zawierający plik settings.php, a czasem także files i services.yml. To tu definiuje się połączenie z bazą danych, prefiksy tabel, ścieżki do katalogów z plikami oraz parametry specyficzne dla danego serwera.

Plik settings.php jest jednym z najważniejszych plików konfiguracyjnych w całym projekcie Drupal. Zawiera tablicę ustawień, m.in. $databases z danymi dostępowymi do bazy, $settings z konfiguracją katalogów plików, poziomem logowania błędów czy kluczami używanymi do hashowania. Często w tym pliku umieszcza się także warunkowe instrukcje rozpoznające środowisko (dev, stage, prod) i ustawiające odpowiednie wartości konfiguracyjne.

Obok settings.php możesz spotkać plik settings.local.php, który służy do przechowywania konfiguracji specyficznej dla środowiska lokalnego programisty. Jest on zwykle wyłączony z systemu kontroli wersji, aby każdy członek zespołu mógł posiadać własne ustawienia, np. inną bazę danych czy włączone szczegółowe logowanie błędów. W settings.php dodaje się wówczas warunkowe dołączanie tego pliku.

Katalog sites/* i mechanizm multisite

Jedną z silnych stron Drupala jest możliwość tworzenia instalacji multisite, czyli wielu stron opartych na jednym kodzie źródłowym. Mechanizm ten wykorzystuje strukturę katalogu sites. Zamiast używać wyłącznie sites/default, można tworzyć dodatkowe katalogi, np. sites/example.com, sites/subdomena.example.com czy sites/klient1, każdy z własnym settings.php i katalogiem files.

Podczas obsługi żądania HTTP Drupal analizuje adres domeny oraz ścieżkę i na tej podstawie decyduje, którego katalogu w sites użyć. Pozwala to uruchomić wiele niezależnych serwisów korzystających z tej samej bazy kodu rdzenia i modułów, ale posiadających własną bazę danych, konfigurację oraz pliki przesyłane przez użytkowników. To potężne narzędzie podczas wdrażania rozwiązań dla wielu marek lub klientów na tej samej infrastrukturze.

Struktura każdego katalogu w sites (poza default) jest bardzo podobna: zawiera własny plik settings.php, opcjonalny services.yml oraz katalog files. Dzięki temu każda strona w konfiguracji multisite ma własne, odseparowane pliki użytkowników, co ułatwia zarządzanie uprawnieniami, backupem i migracjami między serwerami.

Katalog files – pliki przesyłane i generowane

W obrębie sites/default (lub odpowiedniego katalogu w konfiguracji multisite) znajduje się katalog files. To tam trafiają wszystkie pliki przesyłane przez użytkowników – obrazy, dokumenty, załączniki – oraz pliki generowane przez system, m.in. kopie stylów obrazów, cache CSS/JS, prywatne pliki konfiguracyjne i raporty.

Katalog files może mieć charakter publiczny lub prywatny. Ścieżkę do katalogu publicznego i prywatnego definiuje się w konfiguracji Drupala, a informacje o nich są przechowywane w settings.php oraz w konfiguracji system.file. Katalog publiczny jest zazwyczaj dostępny bezpośrednio z poziomu serwera webowego, natomiast katalog prywatny jest chroniony przez warstwę PHP, co pozwala lepiej kontrolować dostęp do wrażliwych plików.

Ważnym elementem pracy z katalogiem files jest odpowiednie ustawienie uprawnień systemowych (chmod, właściciel katalogu), aby Drupal mógł zapisywać nowe pliki, a jednocześnie nie narażać systemu na nieautoryzowane modyfikacje. Błędne uprawnienia w tym miejscu są częstą przyczyną problemów z aktualizacjami, wgrywaniem obrazów czy generowaniem cache.

Własne moduły i motywy w strukturze sites

Drupal pozwala umieszczać własne rozszerzenia nie tylko w głównych katalogach modules i themes, ale także w strukturze sites. Typowa praktyka to tworzenie katalogów sites/default/modules/custom oraz sites/default/themes/custom, gdzie umieszczane są moduły i motywy napisane specjalnie dla danego projektu.

Takie podejście ma kilka zalet: wyraźnie oddziela kod stworzony na potrzeby konkretnej strony od modułów pobranych z zewnątrz, ułatwia zarządzanie uprawnieniami oraz przenoszenie projektu. W instalacjach multisite możliwe jest też utrzymywanie modułów i motywów specyficznych tylko dla wybranej instancji serwisu, umieszczając je w katalogu sites/nazwa_strony/modules.

Własne rozszerzenia strukturalnie wyglądają tak samo jak te w katalogu core/modules: zawierają plik .info.yml, katalog src z klasami PHP, katalog config z domyślną konfiguracją, a w przypadku motywów – zestaw szablonów Twig i zasobów front-endowych. Drupal automatycznie skanuje wszystkie zdefiniowane ścieżki w poszukiwaniu plików .info.yml, dzięki czemu rozszerzenia są widoczne w panelu administracyjnym bez dodatkowych kroków konfiguracyjnych.

Katalogi modules i themes poza core

Podział na contributed, custom i core

W ekosystemie Drupala przyjęło się dzielić moduły i motywy na trzy główne kategorie: core (wbudowane w rdzeń), contrib (pobrane z zewnętrznych repozytoriów, głównie z Drupal.org) oraz custom (tworzone na potrzeby konkretnego projektu). Ten podział nie jest wymuszany technicznie, ale jest uznaną i bardzo praktyczną konwencją porządkującą strukturę katalogów.

W praktyce oznacza to, że w katalogu modules (lub sites/default/modules) możesz utworzyć podkatalogi: core, contrib, custom. Moduły pobrane z Drupal.org trafiają do contrib, natomiast autorskie rozwiązania – do custom. Analogicznie organizuje się motywy w katalogu themes. Dzięki takiemu uporządkowaniu łatwo zorientować się, który element jest źródłem danej funkcjonalności i jak zarządzać aktualizacjami.

Podczas audytu bezpieczeństwa lub migracji projektu ten podział pozwala szybko rozpoznać, które moduły można zaktualizować automatycznie z repozytorium społeczności, a które są unikalne i wymagają indywidualnej analizy. To znacząco przyspiesza prace utrzymaniowe w większych instalacjach.

Struktura typowego modułu

Typowy moduł znajdujący się w katalogu modules lub w strukturze sites posiada co najmniej plik .info.yml, w którym deklarowane są podstawowe informacje: nazwa, opis, typ, wymagane zależności oraz wersja. Dodatkowo znajdują się tam często pliki .module, .install, .routing.yml, .links.menu.yml, a także katalog src z przestrzeniami nazw odpowiadającymi funkcjonalnym komponentom modułu.

W katalogu src można znaleźć kontrolery, pluginy, serwisy, formularze, encje czy subskrybery zdarzeń. Konwencja PSR-4 określa, jak przestrzeń nazw jest mapowana na podkatalogi, np. Drupalnazwa_moduluController odpowiada katalogowi src/Controller. Dzięki temu utrzymanie modułu jest przejrzyste, a jego elementy są automatycznie ładowane przez autoloader.

Jeśli moduł dostarcza własne szablony Twig, umieszcza się je w katalogu templates. Dodatkowe zasoby, takie jak style CSS i skrypty JavaScript, są definiowane w pliku .libraries.yml, a następnie dołączane w odpowiednich miejscach za pomocą mechanizmu bibliotek. Cała ta struktura pozwala na jasne oddzielenie logiki od warstwy prezentacji i konfiguracji.

Struktura typowego motywu

Motywy przechowywane w katalogu themes mają strukturę zbliżoną do modułów, ale kładącą nacisk na warstwę wizualną. Podstawowym plikiem jest plik .info.yml, w którym określa się m.in. bazowy motyw (base theme), regiony, ścieżki do bibliotek CSS/JS oraz zależności od modułów. Motyw może mieć także pliki .libraries.yml, theme-settings.php oraz liczne szablony Twig.

W katalogu templates znajdują się szablony odpowiadające różnym elementom strony: węzłom (node), blokom, polom, stronom, menu. Drupal umożliwia nadpisywanie szablonów dostarczanych przez rdzeń lub moduły, wystarczy umieścić odpowiednio nazwaną wersję pliku Twig w motywie. To właśnie dzięki temu mechanizmowi można dostosować wygląd niemal każdego elementu bez ingerencji w kod core.

Zasoby front-endowe – CSS, JavaScript, obrazy – są zwykle rozmieszczane w podkatalogach css, js, images w obrębie motywu. Plik .libraries.yml grupuje te zasoby w logiczne biblioteki, które następnie można dołączać np. do konkretnych typów węzłów, widoków czy formularzy. Takie podejście daje dużą elastyczność w zarządzaniu wydajnością i minimalizacją zasobów.

Konwencje nazewnicze i dobre praktyki

Przy tworzeniu katalogów w obrębie modules i themes Drupal zaleca stosowanie jasnych konwencji nazewniczych. Nazwa katalogu modułu powinna być krótka, małymi literami, bez spacji, najlepiej opisująca funkcję (np. blog_extra, api_integration). Ta sama nazwa jest używana w plikach .info.yml i przestrzeniach nazw PHP, co zwiększa spójność projektu.

Dobrą praktyką jest także unikanie modyfikowania kodu w modułach contributed – zamiast tego, jeśli trzeba rozszerzyć ich funkcjonalność, tworzy się osobne moduły custom, które korzystają z hooków i pluginów. Pozwala to bezkonfliktowo aktualizować moduły zewnętrzne, jednocześnie zachowując wszystkie wprowadzone rozszerzenia i modyfikacje.

W większych projektach przydaje się również logiczny podział katalogów custom według domen funkcjonalnych, np. custom/content, custom/integration, custom/migration. Ułatwia to nowym członkom zespołu odnalezienie kluczowych elementów i zrozumienie architektury rozwiązania bez konieczności szczegółowego analizowania całego kodu.