Struktura katalogów PrestaShop: co robi każdy folder i kiedy go potrzebujesz

Dlaczego zrozumienie struktury katalogów ma znaczenie

PrestaShop to duża aplikacja. Typowa instalacja zawiera ponad 30 000 plików w setkach katalogów. Większość właścicieli sklepów nigdy nie musi zaglądać do filesystem. Ale jeśli tworzysz moduły, customizujesz motywy, debugujesz problemy albo zarządzasz własnym serwerem, wiedza o tym, który katalog za co odpowiada, oszczędza godziny szukania i chroni przed kosztownymi błędami.

Ten poradnik obejmuje najważniejsze katalogi w instalacji PrestaShop 1.7.x, 8.x albo 9.x. Zaczynamy od katalogów, z którymi będziesz pracować najczęściej, i schodzimy do tych, które lepiej zostawić w spokoju.

/modules/ -- Serce customizacji PrestaShop

To katalog, z którym będziesz pracować najczęściej. Każdy moduł -- zainstalowany z marketplace, wgrany jako ZIP albo napisany na zamówienie -- mieszka tutaj jako podkatalog.

modules/
  ps_emailsubscription/       -- PrestaShop native module
  mprcheckoutrevolution/      -- third-party module
  mymodule/                   -- your custom module
    mymodule.php              -- main module file (required)
    config.xml                -- cached module metadata
    views/
      templates/              -- Smarty templates
      css/                    -- stylesheets
      js/                     -- JavaScript
    controllers/
      front/                  -- front office controllers
      admin/                  -- admin controllers
    sql/                      -- install/upgrade SQL
    upgrade/                  -- version upgrade scripts
    translations/             -- translation files
    vendor/                   -- Composer dependencies

Kluczowe zasady:

• Główny plik PHP musi mieć dokładnie tę samą nazwę co katalog: modules/mymodule/mymodule.php
• Nazwa klasy w środku też musi pasować: class Mymodule extends Module
• Nigdy nie edytuj natywnych modułów PS (z prefiksem ps_) -- aktualizacje nadpiszą zmiany. Użyj zamiast tego hooków, override albo override szablonów modułu w motywie
• Pliki modułu muszą należeć do użytkownika serwera WWW (www-data w większości konfiguracji Linux), żeby uploady i generowanie cache działały

Kiedy potrzebujesz tego katalogu: instalowanie modułów, rozwój modułów, debugowanie problemów modułów, sprawdzanie zainstalowanych modułów, przegląd kodu źródłowego modułów.

/themes/ -- Wygląd i szablony

Cały wizualny output front office jest kontrolowany przez motywy. Każdy motyw to podkatalog zawierający szablony, assety i konfigurację.

themes/
  classic/                    -- PS default theme (1.7/8)
    config/theme.yml          -- theme metadata, asset registration
    templates/                -- Smarty .tpl files
      catalog/                -- product, category pages
      checkout/               -- cart, checkout flow
      cms/                    -- CMS pages
      customer/               -- account pages
      _partials/              -- header, footer, notifications
      layouts/                -- page layout wrappers
    assets/
      css/                    -- compiled CSS
      js/                     -- compiled JS
      img/                    -- theme images (icons, placeholders)
    modules/                  -- module template overrides
  hummingbird/                -- PS 9 default theme
  my-child-theme/             -- your child theme

Kluczowe zasady:

• Nigdy nie edytuj motywu nadrzędnego bezpośrednio. Utwórz child theme, który dziedziczy po rodzicu, i nadpisuj tylko to, co zmieniasz.
• Aktywny motyw ustawiasz w Back Office > Design > Theme & Logo
• modules/ wewnątrz motywu ma priorytet nad własnymi szablonami modułu -- tak motywy customizują output modułów
• PrestaShop 9 używa Hummingbird (Bootstrap 5, CSS layers). PrestaShop 1.7/8 używa Classic (Bootstrap 4).

Kiedy potrzebujesz tego katalogu: customizacja wyglądu sklepu, tworzenie child themes, override szablonów modułów, debugowanie problemów szablonów.

/config/ -- Pliki konfiguracji

Konfiguracja core, którą PrestaShop czyta przy każdym request.

config/
  config.inc.php              -- NEVER EDIT: auto-generated, loads settings.inc.php
  settings.inc.php            -- database credentials, cookie key, PS version
  defines.inc.php             -- path constants, debug flags
  smarty.config.inc.php       -- Smarty template engine configuration
  autoload.php                -- Composer autoloader bootstrap

Kluczowe pliki:

• settings.inc.php -- Zawiera host, nazwę, użytkownika i hasło bazy danych oraz klucz szyfrowania cookies. Ten plik powstaje podczas instalacji. Zrób jego backup. Jeśli stracisz cookie key, wszystkie istniejące sesje klientów i pracowników staną się nieważne.
• defines.inc.php -- Tutaj przełączasz debug mode: ustaw _PS_MODE_DEV_ na true dla developmentu (pokazuje błędy), false dla produkcji. Zawiera też _PS_CACHE_ENABLED_ i inne runtime flags.

Kiedy potrzebujesz tego katalogu: konfiguracja nowej instalacji, zmiana danych bazy, przełączanie debug mode, rozwiązywanie problemów z połączeniem.

/var/ -- Cache, logi i pliki tymczasowe

Dane runtime PrestaShop. Ten katalog rośnie z czasem i można go bezpiecznie czyścić (poza logami, które chcesz zachować).

var/
  cache/
    prod/                     -- production cache
      smarty/
        compile/              -- compiled Smarty templates
        cache/                -- Smarty output cache
      ContainerProdDebugProjectContainer.php  -- Symfony DI container
    dev/                      -- development cache (when _PS_MODE_DEV_ = true)
  logs/
    prod.log                  -- Symfony/PS error logs
    dev.log                   -- development mode logs

Kluczowe operacje:

• Czyszczenie cache: rm -rf var/cache/prod/* -- najczęstsza poprawka dla „zmieniłem coś, ale nic się nie stało”
• Alternatywnie: php bin/console cache:clear --env=prod
• Katalog compile Smarty przechowuje wstępnie skompilowane szablony. Jeśli zmiana szablonu się nie pojawia, usuń var/cache/prod/smarty/compile/*
• Sprawdzanie logów: var/logs/prod.log to pierwsze miejsce do sprawdzenia, gdy coś się psuje. Zawiera błędy PHP, wyjątki Symfony i błędy modułów.

Kiedy potrzebujesz tego katalogu: czyszczenie cache po zmianach, debugowanie błędów przez logi, zwalnianie miejsca na małych serwerach.

/classes/ -- Core business logic (legacy)

Oryginalny model obiektowy PrestaShop. Każdy plik to klasa PHP reprezentująca encję biznesową albo narzędzie.

classes/
  Product.php                 -- Product entity (attributes, prices, stock)
  Category.php                -- Category entity
  Cart.php                    -- Shopping cart logic
  Order.php                   -- Order entity
  Customer.php                -- Customer entity
  Module.php                  -- Base module class (install, hooks, config)
  Tools.php                   -- Utility functions (redirect, getValue, etc.)
  Db.php                      -- Database abstraction
  ObjectModel.php             -- Base ORM class
  shop/
    Shop.php                  -- Multi-shop logic
  tax/
    Tax.php                   -- Tax calculation
  stock/
    StockAvailable.php        -- Stock management

Kluczowe zasady:

• Nigdy nie edytuj tych plików bezpośrednio. Użyj mechanizmu /override/classes/, jeśli musisz zmienić zachowanie core (ale override mają własne problemy -- preferuj hooki i moduły).
• W PS 1.7+ wiele z tych klas jest stopniowo zastępowanych usługami Symfony w /src/. Oba systemy współistnieją.
• ObjectModel to klasa bazowa dla encji. Jej zrozumienie jest kluczowe przy rozwoju modułów -- dostarcza add(), update(), delete(), getFields() i walidację.

Kiedy potrzebujesz tego katalogu: zrozumienie, jak PrestaShop liczy ceny, zarządza stock, przetwarza zamówienia. Czytanie (nie edytowanie) tych plików to sposób nauki internal API.

/controllers/ -- Obsługa requestów

Kontrolery przetwarzają requesty HTTP i renderują strony. PrestaShop ma dwa zestawy: front office i admin.

controllers/
  front/
    ProductController.php     -- product page
    CategoryController.php    -- category listing
    CartController.php        -- cart operations
    OrderController.php       -- checkout steps
    CmsController.php         -- CMS pages
    SearchController.php      -- search results
  admin/
    AdminProductsController.php
    AdminOrdersController.php
    AdminCustomersController.php

Kluczowe zasady:

• Front controllers rozszerzają FrontController. Admin controllers rozszerzają AdminController.
• W PS 1.7+ admin controllers są migrowane do Symfony (w /src/PrestaShopBundle/Controller/). Część stron admin używa nowych kontrolerów Symfony, inne nadal używają tutaj legacy. Oba współistnieją.
• Kontrolery modułów mieszkają w modules/yourmodule/controllers/, nie tutaj.

Kiedy potrzebujesz tego katalogu: zrozumienie działania konkretnej strony, debugowanie problemów page-level, sprawdzanie, które hooki są dostępne na której stronie (kontrolery wywołują Hook::exec()).

/src/ -- Warstwa Symfony (PS 1.7+)

Nowoczesna warstwa architektury. Od wersji 1.7 PrestaShop stopniowo migruje z legacy wzorca /classes/ + /controllers/ do Symfony.

src/
  Adapter/                    -- bridges between legacy and Symfony
  Core/
    Domain/                   -- CQRS commands and queries
      Product/
        Command/              -- CreateProduct, UpdateProduct, etc.
        Query/                -- GetProductForEditing, etc.
    Grid/                     -- admin list/grid definitions
    Form/                     -- admin form definitions
  PrestaShopBundle/
    Controller/               -- Symfony admin controllers
    Entity/                   -- Doctrine entities
    Form/                     -- Form types
    Translation/              -- Translation system
    Twig/                     -- Twig extensions for admin

Kluczowe zasady:

• Ten katalog rośnie z każdą wersją PS, gdy kolejne funkcje migrują do Symfony
• Warstwa Adapter/ jest krytyczna -- opakowuje legacy classes, żeby usługi Symfony mogły z nich korzystać
• W PS 9 większość stron admin jest w pełni Symfony. W PS 1.7/8 to miks legacy i Symfony.
• Developerzy modułów rzadko muszą cokolwiek tutaj modyfikować -- korzystaj z tej warstwy przez usługi Symfony zarejestrowane w services.yml modułu

Kiedy potrzebujesz tego katalogu: zaawansowany rozwój modułów z usługami Symfony, zrozumienie wzorca CQRS dla zarządzania produktami/zamówieniami w PS 8+, kontrybucje do core PrestaShop.

/override/ -- System override

Mechanizm PrestaShop do modyfikowania zachowania core bez edycji plików core.

override/
  classes/
    Product.php               -- overrides classes/Product.php
    Cart.php                  -- overrides classes/Cart.php
  controllers/
    front/
      ProductController.php   -- overrides controllers/front/ProductController.php
    admin/
      AdminProductsController.php

Kluczowe zasady:

• Klasy override rozszerzają oryginał i nadpisują konkretne metody
• Możliwy jest tylko jeden override na klasę. Jeśli dwa moduły próbują nadpisać tę samą klasę, wygrywa tylko ostatni. Dlatego override są kruche -- konflikty modułów są gwarantowane w aktywnych sklepach.
• Po dodaniu albo usunięciu override zregeneruj indeks klas: usuń var/cache/prod/class_index.php i wyczyść cache
• PS 9 deprecjonuje system override. Dla nowego developmentu preferuj hooki, dekorowanie usług Symfony albo komendy CQRS.
• Override mogą powodować tajemnicze błędy trudne do śledzenia. Zawsze sprawdzaj override/, gdy debugujesz nieoczekiwane zachowanie.

Kiedy potrzebujesz tego katalogu: jako ostatnia deska ratunku, gdy hooki nie dają potrzebnej kontroli. Zawsze preferuj hooki i podejścia modułowe. Pełny obraz znajdziesz w naszej referencji Hooks & Overrides.

/img/ -- Obrazy produktów i treści

img/
  p/                          -- product images (organized by ID digits)
    1/2/3/                    -- product ID 123's images
      123.jpg                 -- original
      123-home_default.jpg    -- resized for homepage
      123-large_default.jpg   -- resized for product page
  c/                          -- category images
  m/                          -- manufacturer/brand logos
  s/                          -- supplier logos
  cms/                        -- CMS page images (uploaded via editor)
  l/                          -- language flag icons
  tmp/                        -- temporary uploads

Kluczowe zasady:

• Obrazy produktów są przechowywane w ścieżce pochodzącej z cyfr ID produktu: produkt 123 → img/p/1/2/3/. To rozkłada pliki po katalogach, żeby uniknąć limitów filesystem.
• Regeneracja obrazów (Back Office > Design > Image Settings > Regenerate) odtwarza wszystkie przeskalowane wersje z oryginałów. Przy dużych katalogach może trwać godziny.
• Zrób backup tego katalogu. Obrazów produktów nie da się odtworzyć, jeśli oryginały znikną.
• Wersje WebP są generowane obok JPG/PNG w PS 8+, gdy funkcja jest włączona.

Kiedy potrzebujesz tego katalogu: debugowanie brakujących obrazów produktów, sprawdzanie jakości obrazów, masowe operacje na obrazach, migracja serwera (to często największy katalog pod względem liczby plików).

/app/ -- Kernel aplikacji Symfony

app/
  AppKernel.php               -- Symfony kernel, registers bundles
  config/
    config.yml                -- Symfony service configuration
    parameters.php            -- auto-generated from settings.inc.php
    routing.yml               -- URL routing definitions
    security.yml              -- authentication/authorization
    services.yml              -- service container definitions

Kluczowe zasady:

• AppKernel.php to punkt wejścia dla strony Symfony w PrestaShop. Rejestruje wszystkie bundle, w tym bundle modułów.
• config/routing.yml definiuje wzorce URL admin. Trasy admin modułów są rejestrowane osobno przez własne pliki routingu modułu.
• W PS 9 kernel został znacząco zrefaktoryzowany. Generowanie parameters.php może się różnić.

Kiedy potrzebujesz tego katalogu: zaawansowane debugowanie routingu Symfony, problemów service container albo autoryzacji. Większość developerów nigdy nie dotyka go bezpośrednio.

/translations/ -- Pliki tłumaczeń core

translations/
  default/                    -- default English strings
  en-US/                      -- US English
  fr-FR/                      -- French
  de-DE/                      -- German
    ShopTheme.fr-FR.xlf       -- front office translations
    AdminNavigation.fr-FR.xlf -- admin menu translations

Kluczowe zasady:

• Tłumaczenia core używają formatu XLIFF (.xlf). Tłumaczenia modułów używają tablic PHP albo XLIFF zależnie od wersji PS.
• Paczki tłumaczeń instaluje się przez Back Office > International > Translations albo php bin/console prestashop:translation:export
• Tłumaczenia przechowywane w bazie (edytowane w back office) mają priorytet nad tłumaczeniami z plików.

Katalogi, których nigdy nie powinieneś modyfikować

Te katalogi są częścią infrastruktury core PrestaShop. Bezpośrednia edycja oznacza, że zmiany znikną przy aktualizacji, a Ty ryzykujesz uszkodzenie całej instalacji:

• /vendor/ -- Zależności Composer (Symfony, Doctrine itd.). Zarządzane przez composer install. Nigdy nie edytuj.
• /bin/ -- Komendy konsolowe (bin/console). Uruchamiaj je, nie edytuj.
• /tools/ -- Skrypty build i maintenance. Użycie wewnętrzne.
• /install/ -- Kreator instalacji. Usuwany po instalacji (powinien być, ze względów bezpieczeństwa).
• /admin-dev/ (albo Twój przemianowany folder admin) -- Punkt wejścia admin. Zmień nazwę dla bezpieczeństwa, ale nie edytuj plików w środku.
• /webservice/ -- Endpoint REST API. Konfigurowany przez back office, nie przez edycję plików.

Szybka referencja: gdzie czego szukać

Na live server taki szybki audyt mówi, gdzie sklep ma customowy kod, zanim czegokolwiek dotkniesz:

find modules themes override -maxdepth 2 -type d | sort
find override -type f -name '*.php' -print
find themes -path '*/modules/*' -type f -name '*.tpl' -print
find var/logs -type f -mtime -3 -print

Co zmienia się między wersjami PS

Ogólny trend jest jasny: PrestaShop przechodzi z architektury legacy (/classes/ + /controllers/ + /override/) w stronę Symfony (/src/ + dekorowanie usług + CQRS). Nowy rozwój modułów powinien używać wzorców Symfony tam, gdzie są dostępne, przy zachowaniu kompatybilności wstecznej z 1.7 przez kod zabezpieczony wersjami.

To część 1 serii

Ten przegląd daje mapę. Kolejne artykuły w tej serii wejdą do każdego katalogu z głębokością, jakiej wymaga reference guide -- plik po pliku, wzorzec po wzorcu, z realnymi przykładami ze sklepów produkcyjnych.

Seria PrestaShop Architecture:

• Folder Structure Overview (ten artykuł) -- szybki obraz tego, co robi każdy katalog
• /themes/ Deep Dive -- template resolution, asset pipeline, wnętrze child theme, Hummingbird vs Classic, CSS layers, jak Smarty renderuje stronę od request do HTML
• /modules/ Deep Dive -- lifecycle modułu, rejestracja hooków, skrypty upgrade, łańcuch install/uninstall, jak działa cache config.xml, wzorce autoloading
• /classes/ and /src/ Deep Dive -- wnętrze ObjectModel, współistnienie legacy i Symfony, warstwa Adapter, wzorce CQRS command/query w PS 8/9
• /controllers/ Deep Dive -- front vs admin controllers, status migracji Symfony per strona, routing, jak hooki są wywoływane per kontroler
• /config/ and /var/ Deep Dive -- sekwencja ładowania konfiguracji, warstwy cache (Smarty, Symfony, OPcache, Redis), debug flags, referencja defines.inc.php
• /override/ Deep Dive -- jak system override działa wewnętrznie, class_index.php, dlaczego konfliktuje, co zastępuje go w PS 9, kiedy używać go zamiast hooków
• /img/ Deep Dive -- przechowywanie obrazów po cyfrach ID, pipeline regeneracji, generowanie WebP, integracja CDN, system typów obrazów

Każdy artykuł jest pisany z perspektywy kogoś, kto zbudował i utrzymuje 140+ modułów PrestaShop w PS 1.7, 8 i 9. To nie jest dokumentacja przepisana z oficjalnych docs -- to praktyczna wiedza z lat debugowania, profilowania i budowania systemów produkcyjnych.