Jak stworzyć moduł PrestaShop z pomocą AI

Paczkę pobierzesz jednym poleceniem:

for f in SKILL.md references/struktura.md \
         references/hooki.md references/bezpieczenstwo.md; do
  curl -sL --create-dirs \
    -o ~/.claude/skills/prestashop-module/$f \
    https://nice-code.com/skills/prestashop-module/$f
done

Trafi do ~/.claude/skills/prestashop-module/, a Claude Code podłączy ją automatycznie przy zadaniach dotyczących modułów PrestaShop. W innych narzędziach (Cursor, Copilot, ChatGPT) wklej zawartość SKILL.md jako instrukcję systemową, a pliki z references/ dołącz do projektu. Całą treść paczki znajdziesz też niżej w tym artykule.

Moduł PrestaShop to samodzielny katalog w folderze modules/, który podpina się do sklepu przez hooki i rozszerza go o nowe funkcje bez ruszania plików rdzenia. Model językowy napisze taki moduł w kilka minut — ale tylko wtedy, gdy dostanie kontekst, którego sam nie ma: aktualną strukturę katalogów, prawdziwe nazwy hooków i reguły bezpieczeństwa PrestaShop. Bez tego dostaniesz kod, który wygląda poprawnie i nie instaluje się na produkcji.

Ten artykuł zbiera minimum wiedzy potrzebnej, żeby prowadzić AI przy pisaniu modułu, opisuje błędy, które modele powtarzają najczęściej, i kończy się gotową paczką skill — zestawem plików, które wgrywasz do modelu, żeby przestał zgadywać.

Czego AI nie wie o PrestaShop

Modele uczą się na kodzie z internetu, a w internecie dominuje PrestaShop 1.6 i 1.7. Efekt jest przewidywalny: generowany moduł miesza API z czterech wersji naraz, wywołuje metody usunięte lata temu i rejestruje hooki, które nigdy nie istniały.

Do tego dochodzi problem, którego model nie zobaczy z definicji — nie zna Twojego sklepu. Nie wie, jaką masz wersję PrestaShop, czy działasz w trybie multistore, jaki masz szablon ani które moduły już modyfikują ten sam hook. Ta wiedza musi przyjść od Ciebie.

Struktura modułu PrestaShop 8 i 9

Moduł to katalog o nazwie identycznej z nazwą modułu, a w nim plik PHP o tej samej nazwie. Poniżej pełna struktura zgodna z dokumentacją PrestaShop 9:

ncbadge
├── config
│   ├── admin
│   │   └── services.yml
│   ├── front
│   │   └── services.yml
│   └── services.yml
├── controllers
│   ├── admin
│   └── front
├── src
│   ├── Controller
│   └── Entity
├── translations
├── upgrade
├── views
│   ├── css
│   ├── img
│   ├── js
│   └── templates
│       ├── admin
│       ├── front
│       └── hook
├── config.xml
├── logo.png
└── ncbadge.php

Co musisz wiedzieć o poszczególnych elementach:

Minimalny działający moduł potrzebuje tylko trzech rzeczy: katalogu, pliku PHP z klasą i pliku logo.png. Reszta dochodzi wtedy, gdy jest potrzebna.

Hooki — najważniejsze pojęcie w całym PrestaShop

Hook to punkt zaczepienia w kodzie sklepu, w którym PrestaShop zatrzymuje się i pyta wszystkich zainstalowanych modułów: „czy ktoś chce tu coś dodać albo zmienić?". Moduł odpowiada, implementując metodę o nazwie hook plus nazwa hooka.

Hooki dzielą się na dwie rodziny, a pomylenie ich to najczęstszy błąd początkujących:

Hooki, od których zaczyna się większość modułów:

• actionFrontControllerSetMedia — dodawanie własnego CSS i JavaScriptu na froncie
• displayHeader — treść w sekcji head strony
• displayProductAdditionalInfo — blok na karcie produktu, pod ceną
• actionValidateOrder — moment zatwierdzenia zamówienia, wywoływany po zapłacie
• actionCartSave — każda zmiana w koszyku
• actionObjectProductUpdateAfter — zapis produktu, przydatne przy synchronizacji z ERP
• displayBackOfficeHeader — zasoby w panelu administracyjnym

Pełną listę hooków dla swojej wersji znajdziesz w panelu administracyjnym w sekcji Design → Positions, a programistycznie w tabeli ps_hook. To jest źródło prawdy, nie pamięć modelu. Jeśli AI proponuje hook, którego nie ma na tej liście, to go zmyśliło.

Cykl życia modułu: install, uninstall, upgrade

Trzy metody decydują o tym, czy moduł da się zainstalować, odinstalować i zaktualizować bez zostawiania śmieci w bazie.

<?php
 
declare(strict_types=1);
 
if (!defined('_PS_VERSION_')) {
    exit;
}
 
class NcBadge extends Module
{
    public function __construct()
    {
        $this->name = 'ncbadge';
        $this->tab = 'front_office_features';
        $this->version = '1.0.0';
        $this->author = 'Nice Code';
        $this->need_instance = 0;
        $this->ps_versions_compliancy = [
            'min' => '8.0.0',
            'max' => _PS_VERSION_,
        ];
        $this->bootstrap = true;
 
        parent::__construct();
 
        $domain = 'Modules.Ncbadge.Admin';
 
        $this->displayName = $this->trans(
            'Etykiety produktów', [], $domain
        );
        $this->description = $this->trans(
            'Dodaje etykiety na karcie produktu.', [], $domain
        );
        $this->confirmUninstall = $this->trans(
            'Czy na pewno usunąć moduł?', [], $domain
        );
    }
 
    public function install(): bool
    {
        return parent::install()
            && $this->registerHook('displayProductAdditionalInfo')
            && $this->registerHook('actionFrontControllerSetMedia')
            && Configuration::updateValue('NC_BADGE', 'Nowość')
            && $this->installDb();
    }
 
    public function uninstall(): bool
    {
        return parent::uninstall()
            && Configuration::deleteByName('NC_BADGE')
            && $this->uninstallDb();
    }
 
    private function installDb(): bool
    {
        $table = _DB_PREFIX_ . 'ncbadge';
 
        $sql = "CREATE TABLE IF NOT EXISTS `$table` (
            `id_badge` int(10) unsigned NOT NULL AUTO_INCREMENT,
            `id_product` int(10) unsigned NOT NULL,
            `id_shop` int(10) unsigned NOT NULL,
            `label` varchar(64) NOT NULL,
            `date_add` datetime NOT NULL,
            PRIMARY KEY (`id_badge`),
            KEY `id_product` (`id_product`)
        ) ENGINE=" . _MYSQL_ENGINE_ . " CHARSET=utf8mb4;";
 
        return (bool) Db::getInstance()->execute($sql);
    }
 
    private function uninstallDb(): bool
    {
        $table = _DB_PREFIX_ . 'ncbadge';
 
        return (bool) Db::getInstance()->execute(
            "DROP TABLE IF EXISTS `$table`"
        );
    }
}

Zwróć uwagę na cztery rzeczy, które AI pomija najczęściej:

1. Linia if (!defined('_PS_VERSION_')) exit; — zabezpieczenie przed bezpośrednim wywołaniem pliku z przeglądarki. Obowiązkowa w każdym pliku PHP modułu.
2. ps_versions_compliancy — deklaracja zgodności wersji. Bez tego moduł zainstaluje się tam, gdzie nie powinien.
3. uninstall() faktycznie sprzątający — usunięcie wpisów konfiguracji i tabel. Moduł, który zostawia po sobie dane, po kilku reinstalacjach zamienia bazę w śmietnik.
4. trans() zamiast $this->l() — starsza metoda l() jest przestarzała w PrestaShop 1.7 i nowszych. Modele nagminnie generują l(), bo w danych treningowych jest jej pełno.

Hook wyświetlający i szablon

public function hookActionFrontControllerSetMedia(): void
{
    $this->context->controller->registerStylesheet(
        'ncbadge-style',
        'modules/' . $this->name . '/views/css/front.css',
        ['media' => 'all', 'priority' => 150]
    );
}
 
public function hookDisplayProductAdditionalInfo(
    array $params
): string {
    $idProduct = (int) ($params['product']['id_product'] ?? 0);
 
    if ($idProduct === 0) {
        return '';
    }
 
    $sql = new DbQuery();
    $sql->select('label')
        ->from('ncbadge')
        ->where('id_product = ' . $idProduct)
        ->where('id_shop = ' . (int) $this->context->shop->id);
 
    $label = Db::getInstance()->getValue($sql);
 
    if (!$label) {
        return '';
    }
 
    $this->smarty->assign('nc_badge_label', $label);
 
    return $this->fetch(
        'module:ncbadge/views/templates/hook/badge.tpl'
    );
}

Ten fragment pokazuje trzy wzorce warte skopiowania: rzutowanie na int przed wstawieniem do zapytania, użycie DbQuery zamiast sklejania SQL-a ze stringów oraz filtrowanie po id_shop, dzięki któremu moduł działa poprawnie w trybie multistore.

Osiem błędów, które AI popełnia w modułach PrestaShop

To lista z realnych przeglądów kodu. Każdy z tych błędów widzieliśmy w module wygenerowanym przez model językowy.

Dwa ostatnie punkty są szczególnie zdradliwe, bo nie dają objawów od razu. Multistore ujawnia się dopiero, gdy klient uruchomi drugi sklep. Brak skryptów aktualizacji boli przy pierwszej podmianie wersji modułu na produkcji.

Paczka skill dla modelu AI

Poniżej gotowy zestaw plików, który przekazujesz modelowi jako kontekst. Format jest zgodny ze skillami Claude Code, ale treść zadziała w dowolnym narzędziu — możesz ją wkleić jako instrukcję systemową w Cursorze, Copilocie czy ChatGPT.

Struktura paczki:

prestashop-module/
├── SKILL.md
└── references/
    ├── struktura.md
    ├── hooki.md
    └── bezpieczenstwo.md

Plik SKILL.md

---
name: prestashop-module
description: Tworzenie i modyfikacja modułów PrestaShop 8 i 9.
  Użyj przy zadaniach dotyczących modułu - nowy moduł, hook,
  strona konfiguracji, zapytania do bazy, integracja, migracja.
---
 
# Moduły PrestaShop 8 i 9
 
## Zanim napiszesz jakikolwiek kod
 
Zapytaj użytkownika o te informacje, jeśli ich nie podał:
 
1. Dokładna wersja PrestaShop (np. 8.1.7, 9.0.2)
2. Wersja PHP na serwerze
3. Czy sklep działa w trybie multistore
4. Nazwa hooka, w którym funkcja ma się pojawić (użytkownik
znajdzie ją
   w panelu: Design - Positions)
5. Czy moduł ma mieć stronę konfiguracji w back office
 
Nie zgaduj tych wartości. Błędna wersja to najczęstsza przyczyna
kodu,
który się nie instaluje.
 
## Reguły bezwzględne
 
- Każdy plik PHP zaczyna się od:
  `if (!defined('_PS_VERSION_')) { exit; }`
- Nigdy nie używaj `$this->l()` - to przestarzałe API.
  Używaj `$this->trans('tekst', [], 'Modules.Nazwamodulu.Admin')`
- Nigdy nie sklejaj SQL ze zmiennych. Liczby rzutuj przez `(int)`,
  stringi przez `pSQL()`, a najlepiej używaj `DbQuery`
- Nigdy nie proponuj override bez sprawdzenia, czy jest hook
- Każde zapytanie do własnej tabeli filtruj po `id_shop`
- `uninstall()` musi usunąć wszystko, co stworzył `install()`:
  tabele, wpisy `Configuration`, zarejestrowane taby
- Nazwa klasy modułu odpowiada nazwie katalogu i pliku
- Zmiana schematu bazy wymaga skryptu w katalogu `upgrade/`
 
## Kolejność pracy
 
1. Ustal zakres i hook
2. Napisz szkielet: konstruktor, `install()`, `uninstall()`
3. Dodaj implementację hooka
4. Dodaj stronę konfiguracji, jeśli jest potrzebna
5. Dodaj tłumaczenia
6. Przejdź checklistę z references/bezpieczenstwo.md
7. Powiedz użytkownikowi wprost, czego NIE przetestowałeś
 
## Czego nie wolno zakładać
 
Nie twierdź, że moduł działa. Nie masz dostępu do sklepu, nie
uruchomiłeś
instalacji i nie widziałeś logów. Napisz, co użytkownik powinien
sprawdzić
jako pierwsze po instalacji na kopii sklepu.
 
## Pliki referencyjne
 
- references/struktura.md - struktura katalogów i szkielet klasy
- references/hooki.md - najczęstsze hooki i ich sygnatury
- references/bezpieczenstwo.md - checklista przed oddaniem kodu

Plik references/hooki.md

# Hooki PrestaShop - ściąga
 
Hook `display*` zwraca HTML. Hook `action*` nic nie zwraca.
Metoda w klasie modułu: `hook` + nazwa hooka, np.
`hookDisplayHeader()`.
 
## Front office
 
| Hook | Kiedy | Zwraca |
|---|---|---|
| actionFrontControllerSetMedia | lista zasobów | void |
| displayHeader | sekcja head | string |
| displayProductAdditionalInfo | karta produktu | string |
| displayShoppingCartFooter | podsumowanie koszyka | string |
| displayCustomerAccount | panel klienta | string |
| displayFooter | stopka | string |
 
## Akcje biznesowe
 
| Hook | Kiedy | Uwaga |
|---|---|---|
| actionValidateOrder | zamówienie zatwierdzone | order, cart |
| actionOrderStatusPostUpdate | zmiana statusu | integracje |
| actionCartSave | zmiana w koszyku | częsty, pilnuj wydajności |
| actionObjectProductUpdateAfter | zapis produktu | sync z ERP |
| actionCustomerAccountAdd | rejestracja klienta | newCustomer |
 
## Back office
 
| Hook | Kiedy |
|---|---|
| displayBackOfficeHeader | zasoby panelu |
| displayAdminProductsExtra | zakładka produktu w BO |
 
## Weryfikacja
 
Lista hooków dostępnych w konkretnym sklepie: panel Design -
Positions
albo tabela `ps_hook`. Jeśli hooka nie ma na tej liście, nie
istnieje.
Nie wymyślaj nazw hooków.

Plik references/bezpieczenstwo.md

# Checklista przed oddaniem kodu modułu
 
Przejdź punkt po punkcie. Przy każdym napisz TAK albo opisz,
czego brakuje.
 
## Bezpieczeństwo
 
- [ ] Każdy plik PHP ma `if (!defined('_PS_VERSION_')) { exit; }`
- [ ] Żadne zapytanie SQL nie skleja niezaufanych danych
- [ ] Dane z `Tools::getValue()` walidowane przez `Validate::*`
- [ ] Formularze w back office mają token CSRF
- [ ] Brak `eval()`, `exec()` na danych z formularzy
- [ ] Wgrywane pliki mają sprawdzany typ MIME i rozszerzenie
- [ ] Żadnych kluczy API ani haseł zapisanych w kodzie
 
## Poprawność PrestaShop
 
- [ ] Nazwy hooków zweryfikowane, nie zmyślone
- [ ] `install()` i `uninstall()` są symetryczne
- [ ] Teksty przez `trans()` z poprawną domeną
- [ ] Zapytania filtrowane po `id_shop`
- [ ] Brak override, jeśli dało się użyć hooka
- [ ] Skrypt w `upgrade/` przy zmianie schematu bazy
- [ ] `ps_versions_compliancy` odpowiada wersji docelowej
 
## Jakość
 
- [ ] Typy parametrów i zwracanych wartości
- [ ] Brak zapytań SQL w pętli
- [ ] Zasoby front przez `registerStylesheet`
      i `registerJavascript`
- [ ] Kod zgodny ze standardem PrestaShop (php-cs-fixer)
 
## Na koniec
 
Wypisz, czego nie przetestowałeś i co użytkownik musi sprawdzić
ręcznie
na kopii sklepu przed wdrożeniem na produkcję.

Czwartego pliku, references/struktura.md, nie wklejamy tutaj w całości — to drzewo katalogów i szkielet klasy z wcześniejszej części artykułu. Jest w paczce do pobrania, a jeśli składasz zestaw ręcznie, skopiuj tam te dwa fragmenty.

Jak prowadzić AI krok po kroku

Najgorsze, co możesz zrobić, to poprosić o cały moduł jednym zdaniem. Model wygeneruje wtedy kilkaset linii, których nikt nie zweryfikuje. Lepiej działa podział na etapy, gdzie po każdym sprawdzasz efekt.

1. Opisz problem biznesowy, nie rozwiązanie. Zamiast „napisz moduł z hookiem displayProductAdditionalInfo" powiedz „na karcie produktu ma się pojawić etykieta z terminem dostawy, pobierana z naszego ERP".
2. Podaj kontekst techniczny. Wersja PrestaShop, wersja PHP, multistore, nazwa hooka z panelu.
3. Poproś najpierw o szkielet. Konstruktor, install(), uninstall() — nic więcej. Zainstaluj go na kopii sklepu i sprawdź, czy się rejestruje.
4. Dopiero potem logika. Implementacja hooka, zapytania, szablon.
5. Na końcu konfiguracja i tłumaczenia.
6. Przepuść całość przez checklistę z paczki skill i popraw to, co wyszło.

Testowanie i walidacja

Trzy narzędzia, które wyłapią większość problemów przed wdrożeniem:

• PrestaShop Validator — oficjalny walidator sprawdzający zgodność modułu ze standardami. Ten sam mechanizm decyduje o przyjęciu modułu do oficjalnego katalogu Addons.
• Module Generator — generator szkieletu modułu od twórców PrestaShop. Warto wygenerować nim strukturę i dopiero ją dać modelowi jako punkt wyjścia, zamiast pozwalać mu wymyślać układ katalogów.
• php-cs-fixer ze standardem PrestaShop — automatyczne formatowanie zgodne z konwencją projektu.

Do tego zwykłe testy ręczne na kopii sklepu: instalacja, odinstalowanie, ponowna instalacja, sprawdzenie czy tabele zniknęły, test na drugim sklepie w multistore.

Kiedy AI wystarczy, a kiedy potrzebujesz programisty

Szczerze: nie każdy moduł nadaje się do napisania z modelem, nawet dobrze prowadzonym.

Linia podziału jest prosta: im bliżej pieniędzy i danych klientów, tym mniej miejsca na kod, którego nikt nie przejrzał. Moduł płatności z błędem w walidacji to nie jest problem techniczny, tylko finansowy.

Jeśli Twój przypadek jest po prawej stronie tabeli, zobacz, jak wygląda tworzenie dedykowanych modułów PrestaShop u nas — część naszych modułów udostępniamy jako open source, więc możesz przeczytać kod, zanim cokolwiek zlecisz.

Najczęstsze pytania

Czy moduł napisany przez AI można sprzedawać w PrestaShop Addons?

Technicznie tak — pochodzenie kodu nie jest kryterium przyjęcia. Praktycznie moduł musi przejść walidację PrestaShop Validator, spełnić wymogi bezpieczeństwa i standardy kodowania, a z tym wygenerowany kod ma problem bez ręcznej poprawki. Traktuj wynik pracy modelu jako wersję roboczą do przeglądu, nie jako produkt gotowy do publikacji.

Jaką wersję PrestaShop wskazać modelowi?

Zawsze dokładną wersję z Twojego sklepu, łącznie z numerem wydania. Różnice między 8.0 a 8.1, a tym bardziej między 8.x a 9.x, są na tyle duże, że kod napisany „pod PrestaShop 8" potrafi nie zadziałać. Wersję sprawdzisz w panelu administracyjnym w stopce albo w pliku config/defines.inc.php.

Czy AI poradzi sobie z migracją modułu z PrestaShop 1.7 na 9?

Częściowo. Model dobrze radzi sobie z mechaniczną częścią: zamianą l() na trans(), poprawą sygnatur metod, aktualizacją deklaracji zgodności. Gorzej z rzeczami wymagającymi decyzji — czy przepisać kontroler legacy na Symfony, czy zostawić, co zrobić z override'ami, jak potraktować zależności. Migrację prowadź etapami i po każdym uruchamiaj sklep.

Skąd wziąć prawdziwą listę hooków?

Z własnego sklepu, nie z internetu. Panel administracyjny, sekcja Design → Positions, pokazuje wszystkie hooki dostępne w Twojej instalacji wraz z modułami, które już się do nich podpięły. To drugie jest równie ważne — jeśli w danym hooku siedzi już pięć modułów, kolejność wyświetlania będzie miała znaczenie.

Czy muszę znać PHP, żeby zrobić moduł z AI?

Do prostego modułu wyświetlającego — niekoniecznie, choć bez podstaw nie ocenisz, czy kod jest bezpieczny. Do czegokolwiek zapisującego dane — tak. Model nie powie Ci, że popełnił błąd, bo o nim nie wie. Jeśli nie umiesz przeczytać wygenerowanego zapytania SQL, nie wypuszczaj go na sklep, który przyjmuje zamówienia.

Co zrobić, gdy moduł się nie instaluje?

Włącz tryb debugowania w config/defines.inc.php (stała _PS_MODE_DEV_) na kopii sklepu i sprawdź komunikat błędu. Najczęstsze przyczyny to: nazwa klasy niezgodna z nazwą katalogu, błąd składni PHP, nieistniejący hook w registerHook() oraz install() zwracający false przez nieudane zapytanie SQL. Przekaż modelowi treść błędu — z konkretnym komunikatem poprawi kod znacznie skuteczniej niż z opisem „nie działa".

Podsumowanie

Model językowy jest dobrym narzędziem do pisania modułów PrestaShop pod warunkiem, że dostanie to, czego sam nie ma: aktualną strukturę katalogów, prawdziwe nazwy hooków z Twojego sklepu i twarde reguły bezpieczeństwa. Paczka skill z tego artykułu zamyka większość tej luki — resztę musisz dołożyć Ty, podając wersję PrestaShop i kontekst biznesowy.

Reszta to zwykła higiena: testuj na kopii, czytaj wygenerowany kod, przechodź checklistę i nie wypuszczaj na produkcję niczego, czego nie rozumiesz.

Potrzebujesz modułu, którego nie chcesz pisać samodzielnie? Opowiedz nam, co ma robić — wycena i analiza są bezpłatne. Zobacz też, jak podchodzimy do wdrożeń sklepów na PrestaShop i platform B2B dla hurtowni.