Czym jest PrestaShop GitHub i co tam realnie znajdziesz

GitHub to warsztat, w którym powstaje PrestaShop, a nie sklep, który dostajesz do ręki. Cały kod źródłowy leży w organizacji PrestaShop. Najważniejsze repozytorium to PrestaShop/PrestaShop – pełny Core: kontrolery, klasy, szablony Smarty, instalator, tłumaczenia. Obok niego funkcjonują osobne repozytoria modułów natywnych (m.in. blockreassurance, ps_checkpayment) i motywu classic. Każde z nich ma własne wersjonowanie i własny cykl wydań – moduł działający na 1.7 nie musi działać na 8.2, mimo że leży w tej samej organizacji.

Drugie rozróżnienie, które najczęściej myli się w praktyce: develop vs tagi. Branch develop to bieżąca praca programistów – kod między commitami bywa niespójny, funkcje są w połowie, a testy nie przechodzą. Tagi (np. 8.1.x, 8.2.x) to zamrożone stany kodu odpowiadające konkretnym wydaniom. Gdy sprawdzasz, czy błąd w sklepie klienta jest błędem PrestaShop, patrz na tag zgodny z jego wersją, nie na develop. Inaczej porównujesz dwie różne rzeczy i wyciągasz błędne wnioski.

Trzecia rzecz: instalacja z GitHuba to nie instalacja produkcyjna. Repozytorium nie zawiera skompilowanych assetów (CSS/JS), nie ma w nim zależności PHP pobieranych przez Composer ani finalnej struktury paczki. Paczki release dla produkcji są przygotowywane i publikowane osobno. Klonowanie kodu ma sens w trzech sytuacjach: zgłaszasz błąd, piszesz pull request albo chcesz przetestować poprawkę przed wydaniem. W pozostałych przypadkach tracisz czas.

Z naszych wdrożeń: większość zgłoszeń „PrestaShop ma błąd, widziałem to na GitHubie” dotyczy kodu z develop, który nigdy nie trafił do wydania. Zanim zaczniesz panikować, sprawdź, jak czytane są wydania PrestaShop i kiedy warto aktualizować.

Jak znaleźć właściwe repozytorium i nie pomylić forka z oryginałem

Szukając modułu na GitHubie, wpisujesz frazę i dostajesz kilkanaście wyników. Pierwszy z listy bywa forkiem porzuconym trzy lata temu. Sprawdzasz więc cztery liczby: liczbę commitów (kilka commitów to zwykle eksperyment, nie produkt), datę ostatniej aktywności, liczbę otwartych issues i tempo odpowiedzi na nie oraz obecność pliku LICENSE. Brak licencji to nie formalność – bez niej nie masz jasno określonych praw do używania kodu w komercyjnym sklepie.

Fork poznasz po etykiecie „forked from …” pod nazwą repozytorium i po tym, że nie ma własnych release’ów ani tagów. Skutek przy aktualizacji PrestaShop jest banalnie prosty: nie ma się do czego odwołać. Gdy przechodzisz z PHP 7.4 na 8.1/8.2, porzucony moduł sypie błędami (typowo: dynamiczne właściwości, przestarzałe funkcje mcrypt, brak wsparcia dla intl), a Ty nie masz skąd pobrać poprawki. Zostaje własny patch albo wymiana modułu – obie opcje generują koszt, którego nikt nie zaplanował w budżecie.

Konkretne sygnały ostrzegawcze:

• ostatni commit starszy niż 18 miesięcy,
• w composer.json zapis "php": ">=7.1" przy sklepie na PHP 8.2,
• brak katalogu tests/ i brak CI (GitHub Actions),
• issues bez odpowiedzi od pół roku,
• instalacja tylko z brancha master, bez ani jednego tagu wersji.

Zanim wgrasz moduł na produkcję, otwórz composer.json i config.xml: sprawdź wymagania PHP, rozszerzenia (intl, gd, zip) i deklarowaną wersję MySQL/MariaDB. Strukturę modułu i wymagania opisuje dokumentacja dla deweloperów PrestaShop. Jeśli nie chcesz analizować kodu, zleć to komuś, kto robi wdrożenia PrestaShop na co dzień – taniej niż gaszenie sklepu po nieudanej instalacji.

Instalacja PrestaShop z GitHuba – krok po kroku (dla developmentu, nie produkcji)

To procedura dla środowiska lokalnego albo stagingowego. Nigdy na sklepie klienta.

Wymagania wstępne: Git, Composer 2, Node.js LTS + npm, PHP 8.1 lub 8.2 z rozszerzeniami intl, mbstring, gd, zip, curl, pdo_mysql, MySQL 5.7+/MariaDB 10.4+, oraz Laragon, DDEV albo Docker. Bazę twórz z kodowaniem utf8mb4 – konwersja później to niepotrzebna robota.

Kolejność działań:

• git clone --branch 8.1.x https://github.com/PrestaShop/PrestaShop.git – klonuj tag/branch wydania, nie develop, jeśli nie testujesz konkretnej poprawki.
• composer install w katalogu głównym – pobiera zależności PHP. Bez tego instalator w przeglądarce się nie uruchomi.
• npm install, a następnie skrypt budujący assety administracyjne z package.json. Motyw classic ma osobny katalog _dev z własnym package.json – assety motywu kompilujesz tam. Nazwy skryptów różnią się między wersjami, więc sprawdź sekcję scripts w package.json swojej wersji, zamiast kopiować komendę z bloga.
• Plik app/config/parameters.php: w części wydań znajdziesz wzór z rozszerzeniem .dist. Jeśli go nie ma, parameters.php wygeneruje instalator w przeglądarce. Wpisujesz tam host, nazwę bazy, użytkownika, hasło i prefiks tabel.
• Uprawnienia: katalogi var/, img/, modules/, app/config/, translations/ zapisywalne dla użytkownika PHP (np. www-data), typowo 755 dla katalogów i 644 dla plików. Nie ustawiaj 777 „na wszelki wypadek”.

Ostrzeżenie: branch develop może zawierać niedokończone zmiany i nie jest wspierany produkcyjnie. Instalator może się wywalić w połowie, a migracje bazy nie przejść. Testuj na kopii bazy, nie na danych klienta. Jeśli dopiero porównujesz wersje, zamiast klonować kod, wygodniej zacząć od wersji demo i sprawdzenia, co realnie działa przed wdrożeniem, a przy własnych szablonach przeczytaj, jak wygląda wybór i wdrożenie motywu PrestaShop.

Git w pracy nad własnym modułem PrestaShop – standard, który się sprawdza

Moduł w PrestaShop to katalog, którego nazwa musi być identyczna z nazwą pliku głównego: /modules/mojmodul/mojmodul.php. Układ, który przechodzi walidację i nie sprawia kłopotów przy aktualizacjach:

• mojmodul.php – klasa dziedzicząca po Module; w konstruktorze name, version, author, ps_versions_compliancy,
• controllers/front/ i controllers/admin/ – kontrolery frontu i zaplecza,
• views/templates/front/, views/templates/admin/, views/css/, views/js/,
• translations/pl.php oraz pozostałe pliki językowe,
• upgrade/upgrade-1.4.0.php – skrypty migracji uruchamiane przy aktualizacji modułu,
• config.xml – metadane czytane przez panel i Addons,
• vendor/ – zależności Composera, poza repozytorium.

Wersję trzymasz w dwóch miejscach: $this->version = '1.4.2' w pliku głównym oraz w config.xml. Jeśli te wartości się rozjadą, panel może nie zaproponować aktualizacji, a osoba utrzymująca sklep nie odtworzy stanu kodu. Semver stosuj dosłownie: MAJOR, gdy zmieniasz sygnaturę hooka, usuniesz opcję konfiguracyjną albo strukturę tabeli; MINOR, gdy dodajesz nowy hook, kontroler lub ustawienie; PATCH przy poprawkach, które nie zmieniają API modułu.

Wydanie zamykasz tagiem: git tag -a v1.4.2 -m "wydanie 1.4.2", potem git push origin v1.4.2. Paczkę ZIP budujesz tak, aby w archiwum był katalog modułu, a nie luźne pliki – inaczej panel zwróci błąd struktury archiwum. W .gitignore trzymaj vendor/, node_modules/, var/cache/, *.zip, .idea/, .env. Kluczy API (płatności, kurierzy, BaseLinker) nie commituj nigdy – w historii Git zostają na zawsze. Trzymaj je w konfiguracji sklepu lub poza repozytorium, a jeśli już wyciekły, natychmiast rotuj klucz. Jeśli moduły ma utrzymywać ktoś z zewnątrz, ustal to wcześniej – to wątek, który rozwijamy w tekście o tym, jak wygląda praca przy PrestaShop i ile realnie zajmuje utrzymanie sklepu: role, stawki i godziny utrzymania sklepu. Punkt odniesienia dla struktury modułu znajdziesz w dokumentacji dla deweloperów PrestaShop.

Gdzie zgłaszać błędy: issues, forum, Slack – kolejność i zasady

Dobry issue to instrukcja odtworzenia, nie opis frustracji. Kolejność działania jest zawsze taka sama:

1. Odtwórz błąd na świeżej instalacji tej samej wersji (np. PrestaShop 8.1.5, PHP 8.1.27), z motywem classic i wyłączonymi modułami zewnętrznymi. Jeśli błąd znika – to nie Core.
2. Przeszukaj istniejące zgłoszenia po komunikacie błędu i numerze wersji, zanim dodasz kolejne.
3. Zgłoś problem w repozytorium PrestaShop/PrestaShop, wypełniając szablon issue.

Co musi znaleźć się w zgłoszeniu: wersja PrestaShop i PHP, wersja MySQL, dokładne kroki reprodukcji (1., 2., 3.), oczekiwany i faktyczny wynik, pełny stack trace oraz fragment logu z var/logs/ (dev.log lub prod.log), lista modułów zewnętrznych i nazwa motywu. Włącz tryb debug w Advanced Parameters → Performance, wyczyść cache i powtórz test – bez tego połowa zgłoszeń wraca z prośbą o uzupełnienie.

Zanim wpiszesz cokolwiek w Issues, sprawdź, czy nie modyfikowaliście plików rdzenia, czy w override/ nie ma nadpisań z poprzedniej wersji i czy winny nie jest moduł płatności lub dostawy. Błędy konfiguracji, limity PHP, OPcache i uprawnienia do katalogu var/ szybciej rozwiążesz na forum PrestaShop lub pisząc do autora modułu. GitHub Issues służy do błędów Core i propozycji zmian kodu, nie do pytań typu „jak ustawić podatek”.

Pull requesty: fork repozytorium, branch od develop, zmiany zgłaszasz do develop, nie do master. Zacznij od małych poprawek – literówka w tłumaczeniu, brakujący typ w PHPDoc, walidacja w kontrolerze. Mały PR przechodzi review w kilka dni, a duży refaktor potrafi leżeć tygodniami. Zasady kontrybucji są opisane w plikach CONTRIBUTING i szablonach issue w repozytorium – przeczytaj je przed pierwszym commitem.

Aktualizacja PrestaShop a Git: co śledzi sklep, a czego nie

Najczęstsza przyczyna sklepu, który po aktualizacji się nie podnosi, jest prosta: ktoś poprawił plik w classes/ albo controllers/, wrzucił zmianę do repozytorium i wdrożył na produkcję. Przy kolejnej aktualizacji nowa wersja nadpisuje ten plik albo – gorzej – ona sama się nie aplikuje, bo plik różni się od oryginału. Zasada jest jedna: Core zostaje bez modyfikacji.

Zmiany funkcjonalne robisz przez override/classes/ i override/controllers/, własne moduły w modules/, a wygląd w themes/. Każdy z tych obszarów trzymaj w osobnym repozytorium – moduł w swoim, motyw w swoim. Wtedy aktualizacja Core nie wchodzi w konflikt z Twoją pracą, a Ty widzisz w historii commitów, co zmieniła Twoja firma, a co przyszło z zewnątrz.

Przed wdrożeniem zawsze staging: kopia plików i bazy, aktualizacja na kopii, test koszyka, płatności, wysyłki, maili i panelu. Backup bazy wykonaj bezpośrednio przed deploymentem (mysqldump z pełnym zrzutem, nie tylko eksport tabel), a pliki zabezpiecz snapshotem serwera – nie licz na to, że „cofniesz Git-em” aktualizację, która zdążyła zmienić schemat bazy. Po aktualizacji sprawdź, czy override/ działa z nowym Core, wyczyść cache i wygeneruj ponownie .htaccess oraz mapę URL-i. Jeśli motyw bazuje na classic, nie edytuj katalogu classic – trzymaj własny motyw, żeby aktualizacja go nie nadpisała. Kupionych modułów z Addons zwykle nie commitujemy ze względu na licencje – aktualizuj je z panelu, a w repozytorium trzymaj tylko te pisane na zamówienie. Warto też śledzić numery wydań, bo nie każda gałąź, np. 8.1.x, wymaga natychmiastowej aktualizacji – pomaga w tym nasze zestawienie PrestaShop news: jak czytać wydania i kiedy aktualizować.

Licencja i komercyjne użycie kodu z PrestaShop GitHub

Zanim sklonujesz cokolwiek z PrestaShop GitHub, otwórz plik LICENSE w katalogu głównym repozytorium. Rdzeń (PrestaShop/PrestaShop) działa na Open Software License 3.0 (OSL-3.0), czyli licencji copyleft. To nie jest „róbta, co chceta”.

Co to znaczy w praktyce:

• Używanie sklepu u siebie lub u klienta nie uruchamia obowiązku publikacji zmian, dopóki nie przekazujesz kodu dalej. Override'y w katalogu /override/ i modyfikacje motywu zostają Twoją sprawą.
• Dystrybucja zmodyfikowanego rdzenia – sprzedajesz „własną wersję PrestaShop” albo przekazujesz spakowany kod innej firmie – wymaga udostępnienia źródeł na OSL-3.0 z zachowaniem noty o prawach autorskich.
• Klauzula External Deployment: OSL-3.0 traktuje udostępnianie zmodyfikowanego kodu osobom trzecim przez sieć podobnie jak rozpowszechnianie. Jeśli planujesz model SaaS na zmodyfikowanym rdzeniu, przeanalizuj to przed startem, nie po.

Licencja rdzenia to jedno, licencje modułów to drugie. Moduły natywne w organizacji PrestaShop mają własne pliki LICENSE – najczęściej OSL-3.0 lub AFL-3.0, ale nie zakładaj tego z góry, tylko sprawdź. Moduły z Addons mają licencję producenta: zwykle własnościową, przypisaną do jednej domeny, z zakazem redystrybucji. Wrzucenie takiego kodu do publicznego repozytorium to najczęstszy błąd, jaki widzimy w audytach.

Prawnika warto zaangażować w trzech sytuacjach: chcesz sprzedawać lub udostępniać zmodyfikowany rdzeń albo jego pochodną, łączysz kod OSL-3.0 z własnym kodem, który ma zostać zamknięty, budujesz moduł na bazie cudzego kodu i planujesz go dystrybuować. Dokumentacja deweloperska PrestaShop opisuje strukturę kodu i hooki, ale nie zastąpi analizy licencyjnej. Jeśli nie chcesz wchodzić w temat kodu źródłowego, sprawdź, ile realnie kosztuje wdrożenie PrestaShop, i porównaj to z własnymi godzinami pracy.

Kiedy GitHub to dobry pomysł, a kiedy zwykła wdrożenie w DropDigital

GitHub ma sens wtedy, gdy wchodzisz w kod świadomie i masz czas go utrzymywać. Trzy scenariusze, w których warto działać samodzielnie:

• Nauka. Klonujesz repozytorium i uruchamiasz je lokalnie. Zero ryzyka dla produkcji, realna wiedza o strukturze kodu.
• Fork modułu. Natywny moduł robi 80% tego, czego potrzebujesz – dokładasz brakujące 20% i trzymasz prywatny fork. Pamiętaj o .gitignore: app/config/parameters.php (1.7 i 8.x) oraz settings.inc.php (1.6) nie mogą trafić do repozytorium.
• Własny dodatek wewnętrzny. Eksport zamówień do CSV, dodatkowe pole w formularzu, prosty hook wysyłający dane do wewnętrznego systemu.

Temat warto oddać, gdy pojawia się migracja 1.6 → 8.x (motyw, override'y, moduły bez wsparcia), integracja z ERP (Subiekt GT/nexo, Comarch Optima, Baselinker), optymalizacja wydajności (Core Web Vitals, cache, indeksy w bazie przy 20+ GB) albo obsługa serwera (PHP-FPM, MariaDB, Redis, kopie zapasowe, WAF, aktualizacje bezpieczeństwa). Jedna pomylona aktualizacja na produkcji kosztuje więcej niż cały etap prac.

Opieka po wdrożeniu w praktyce wygląda tak: reakcja na zgłoszenie krytyczne w 4 h w dni robocze, pozostałe zgłoszenia do 1 dnia roboczego, kopia zapasowa co 24 h z testem odtworzenia raz na kwartał, aktualizacje modułów i motywu najpierw na staging, monitoring dostępności i raport miesięczny. Zakres godzinowy i stawki opisujemy szerzej w materiale o pracy przy PrestaShop i godzinach utrzymania sklepu.

Punkt wejścia dla firm, które potrzebują wsparcia zamiast eksperymentów: zaplecze PrestaShop DropDigital.

Najczęstsze błędy i jak je wykryć

Lista kontrolna do odklikania

• Wersja PrestaShop i PHP — Zapisz dokładne numery przed każdą zmianą. Wersję sklepu sprawdzisz w panelu, wersję PHP przez php -v na serwerze lub w informacjach o środowisku w hostingu.
• Branch czy tag — Ustal to przed klonowaniem. Do testów wystarczy tag wydania, np. 8.1.x; develop służy do pracy nad przyszłymi zmianami i codziennie się zmienia.
• Ostatnia aktywność repozytorium — Zerknij na datę ostatniego commita przy każdym module z GitHuba. Brak zmian przez ponad 18 miesięcy oznacza, że moduł wymaga przeglądu przed aktualizacją PHP.
• Plik LICENSE — Sprawdź go przed użyciem kodu komercyjnie. Brak licencji oznacza, że formalnie nie masz jasnej podstawy do wdrożenia modułu w sklepie klienta.
• composer.json i wymagania — Otwórz plik i przeczytaj sekcję require: wersja PHP, rozszerzenia, zależności. Porównaj to z wersją PHP na serwerze, zanim cokolwiek wgrasz.
• Open issues i tempo odpowiedzi — Zajrzyj w zakładkę Issues. Setki otwartych zgłoszeń bez odpowiedzi autora to sygnał, że wsparcie może być iluzoryczne.
• Wersja modułu w config.xml — Porównaj numer w pliku config.xml z tagiem wydania na GitHubie. Niezgodność oznacza, że paczka ZIP nie odpowiada kodowi w repozytorium.
• Uprawnienia katalogów — Po instalacji środowiska dev sprawdź zapis do var/, img/ i modules/. Bez tego instalator zatrzyma się w połowie.
• app/config/parameters.php — Sprawdź poprawność danych bazy po sklonowaniu repozytorium. Ten plik nigdy nie powinien trafić do repozytorium publicznego.
• .gitignore — Ustaw go przed pierwszym commitem w module. Powinien wykluczać vendor/, node_modules/ i cache/.
• Logi przed zgłoszeniem — Zbierz wpisy z var/logs/ oraz błędy z konsoli przeglądarki. Bez logów zgłoszenie najczęściej wraca z prośbą o doprecyzowanie.
• Kanał zgłoszenia — Błąd Core kieruj do GitHub Issues, pytanie o wdrożenie na forum lub Slack, błąd modułu do repozytorium jego autora. Wybór kanału skraca czas reakcji.

Najczęściej zadawane pytania

Źródła i materiały

• Google Search Central – tworzenie treści dla ludzi
• Google Search Central – dane strukturalne
• Google Search Central – Core Web Vitals
• PrestaShop – dokumentacja dla deweloperów
• Google Ads – dokumentacja API