Zgodność z PrestaShop: środowiska, API i migracja modułów

Jak byśmy do tego podeszli

Ilość pracy przy module zależy od tego, co robi w sklepie i gdzie działa: od docelowego wydania, starszych sklepów, które nadal obsługuje, motywu, integracji, z którymi się komunikuje, i własnych zmian wokół niego. Sporządzilibyśmy wykaz zależności i zadań biznesowych modułu, a następnie przetestowali procesy o najwyższym ryzyku na chronionej kopii docelowego sklepu. Zachowaj utrzymywany, zgodny istniejący moduł, jeśli przechodzi testy. Dostosuj kod pisany na zamówienie, jeśli wymaganie pozostaje przydatne, a zastąp go tylko wtedy, gdy zamiennik obejmuje rzeczywisty proces i jego dane.

Dla sprzedawcy przenoszącego cały sklep zgodność modułów jest częścią szerszej ścieżki. Ta ścieżka zależy od modułów, integracji, motywu i danych istniejącego sklepu. Zwykle bezpieczną ścieżką jest czysty sklep docelowy na środowisku testowym wraz z przećwiczoną migracją danych. Inną opcją jest aktualizacja kopii testowej, jeśli pozwala na to obecna konfiguracja. Przetestuj kompletny zestaw modułów na własnych danych sklepu, a następnie przełącz sklep w zaplanowanym czasie. Plan dla sklepu opisuje lista kontrolna aktualizacji i migracji. Ten poradnik podaje programiście konkretne prace i dowody odbioru, które należy dostarczyć.

Jeśli chcesz, aby całe przeniesienie wykonano za Ciebie, PrestaShop Upgrade Service zaczyna się od bezpłatnego sprawdzenia wersji, PHP, hostingu, motywu i modułów, daje stałą pisemną wycenę przed rozpoczęciem prac i działa na kopii testowej, podczas gdy sklep produkcyjny nadal przyjmuje zamówienia.

Jeśli wymaganie potrzebuje modułu pisanego na zamówienie, PrestaShop Custom Module Development Service zaczyna się od pisemnej specyfikacji i stałej wyceny uzgodnionego zakresu, a testy, kontrolowane uruchomienie i plan powrotu są częścią realizacji.

Zacznij od ryzyk biznesowych modułu

Ustal kolejność prac nad zgodnością według tego, co najszybciej zatrzymałoby działalność, a nie według tego, który kod wygląda na najstarszy.

Wypisz własny kod i dane należące do modułu, które stoją za każdym obszarem odpowiedzialności. Zamiennik musi zachować potrzebne działanie i zapewnić ścieżkę migracji tych danych.

Na przykład narzędzie administracyjne może poprawnie otwierać pulpit, ale zawodzić, gdy pracownik magazynu eksportuje przefiltrowaną listę lub uruchamia operację masową. Moduł przewoźnika może wyświetlać ustawienia, a błąd ujawniać dopiero przy zamawianiu etykiety. Nadaj tym działaniom wyższy priorytet niż kosmetycznemu refaktoryzowaniu kontrolerów i ustal, jaki dostęp do środowiska sandbox lub dostawcy będzie potrzebny do testów.

Utrzymuj decyzje o zgodności w jednym miejscu

Warstwa zgodności zapewnia modułowi mały, stabilny interfejs do API różniących się między wydaniami PrestaShop. Umieszczaj tam sprawdzanie wersji, zamiast powtarzać je w kontrolerach, hookach i szablonach. Testuj każdy moduł w jego własnym deklarowanym zakresie obsługi.

Na przykład MyPrestaRocks\Compat\PriceFormatter::format() deleguje do ToolsCompat::displayPrice(). Ta funkcja pomocnicza sprawdza natywne API, ustala walutę i w razie potrzeby korzysta z bieżącego formatera ustawień regionalnych.

Niektórych możliwości nie da się odtworzyć przez zmianę nazwy metody. W PrestaShop 1.6 hook filtrujący wynikowy dokument jest niedostępny. Zastępcze wstawienie na początku body przez displayBanner także zależy od położenia w motywie. Zgłoś to ograniczenie i zastosuj świadomą zmianę szablonu, gdy funkcja wymaga dokładnego miejsca wstawienia.

Odróżniaj minimalną wersję składni PHP od środowiska sklepu

Ograniczenie wersji PHP biblioteki nie określa, która wersja PHP może uruchomić sklep. Kod współdzielony może zachowywać składnię zgodną z PHP 7.1, podczas gdy konkretne wydanie PrestaShop wymaga nowszego środowiska. PHP 7.1 nie jest już wspierane i nie stanowi rekomendacji dla hostingu.

Budując macierz, korzystaj z wymagań PrestaShop 8 i wymagań PrestaShop 9. Udane eksperymentalne uruchomienie poza udokumentowanym zakresem to nie to samo co oficjalna obsługa platformy. Wsparcie upstream dla PHP 8.1 zakończyło się 31 grudnia 2025 r. Zachowaj środowisko 8.1 do testów zgodności tam, gdzie jest potrzebne, i zaplanuj aktualizację sklepu oraz środowiska do wersji z aktualnym wsparciem bezpieczeństwa PHP.

Dla każdego środowiska testowego zapisz dokładne wydanie poprawkowe, wersję PHP, kompilację modułu, motyw i istotne zależności wraz z datą testu. Jedna udana kompilacja PrestaShop 9 nie jest dowodem dla każdego późniejszego wydania pomniejszego lub poprawkowego. Testuj najniższą i najwyższą deklarowaną wersję PHP tylko tam, gdzie dane wydanie PrestaShop je obsługuje, i nie łącz niezależnie obsługiwanych zakresów w nieprawidłową parę.

PHP parsuje plik, zanim wykona gałąź zależną od wersji. Warunek wokół wyrażenia dostępnego tylko w PHP 8 nie sprawi, że ten plik załaduje się w PHP 7.1. Trzymaj typowane właściwości, argumenty nazwane, enumy, match i inną nowszą składnię poza plikami ładowanymi w starszych środowiskach albo ładuj osobną implementację tylko w odpowiednim środowisku. Jeśli jedna paczka nie może bezpiecznie obsłużyć każdego wspieranego środowiska, dostarczaj osobne zgodne kompilacje, zamiast po cichu porzucać istniejące sklepy.

Rozwiązuj zależności Composer względem najniższej deklarowanej wersji PHP. Uruchom też composer check-platform-reqs na zainstalowanym środowisku docelowym: symulowana platforma to ustawienie rozwiązywania zależności, a nie test działania.

{
  "require": {"php": ">=8.1 <8.6"},
  "config": {"platform": {"php": "8.1.0"}}
}

Ten przykład opisuje zasady zależności modułu dla PHP od 8.1 do 8.5. Nie deklaruje, że każde wydanie PrestaShop obsługuje wszystkie te wersje. Zachowaj spójność ps_versions_compliancy modułu, ograniczeń Composer, wersji zależności i testowanych kombinacji. Górna granica taka jak 9.99.99 dopuszcza także przyszłe, nieprzetestowane wydania 9.x.

Łącz sprawdzanie wersji ze sprawdzaniem dostępnych możliwości

Używaj version_compare() dla znanej zmiany zachowania. Używaj method_exists(), is_callable() lub class_exists(), gdy musisz wiedzieć, czy API jest dostępne. Istnienie metody nie dowodzi identycznego działania w różnych wydaniach, a numer wersji nie dowodzi, że zmodyfikowane środowisko udostępnia każdą oczekiwaną usługę.

Ten przykład zasobów pokazuje sprawdzanie dostępnej możliwości wewnątrz funkcji obsługi actionFrontControllerSetMedia. Zachowaj osobną starszą ścieżkę rejestracji, jeśli obsługujesz też wydanie, które nie wykonuje tego hooka.

public function hookActionFrontControllerSetMedia($params)
{
    $controller = $this->context->controller;
    if (!isset($controller->php_self) || $controller->php_self !== 'product') {
        return;
    }

    if (is_callable(array($controller, 'registerStylesheet'))) {
        $controller->registerStylesheet(
            'mymodule-front',
            'modules/' . $this->name . '/views/css/front.css',
            array('media' => 'all', 'priority' => 150)
        );
    } elseif (is_callable(array($controller, 'addCSS'))) {
        $controller->addCSS($this->_path . 'views/css/front.css');
    }
}

Scentralizuj obsługę tej różnicy, zamiast powtarzać warunek przy każdym wywołaniu. Pokazuj wywołującemu nieobsługiwaną możliwość, zamiast po cichu zgłaszać sukces. Zachowaj istotne zachowanie, w tym ustawienia regionalne, walutę, kontekst sklepu i zakończenie odpowiedzi.

Sklasyfikuj każde ustalenie przed zmianą kodu

Dla każdej podejrzewanej niezgodności zapisz symbol lub zachowanie, dokładne wydanie, którego dotyczy, dowód z kodu źródłowego lub dokumentacji dla programistów oraz proces, który ją odtwarza. Klasyfikacja decyduje o zakresie prac:

Wyszukaj stare wywołania formatowania cen, takie jak Tools::displayPrice(), klasy bazowe kontrolerów i dostęp do usług przez $this->get(), adnotacje bezpieczeństwa, Context::getContext(), starsze hooki logowania i strony produktu, biblioteki poczty oraz bezpośrednie importy zależności. To kandydaci do sprawdzenia, a nie lista usunięć: poniższe sekcje pokazują, że część z nich usunięto, część oznaczono jako przestarzałe, a część jest nadal obsługiwana. Sprawdź każdy względem dokładnej wersji docelowej i nie traktuj szerokiego wyszukaj i zamień jako dowodu, że zamiennik działa tak samo.

Opisz każde ustalenie tak, aby programista mógł je rozwiązać: plik i symbol, dokładna wersja docelowa, klasyfikacja, dowód ze źródła, dotknięta ścieżka, proponowana zmiana i ponowny test. Wpis „stary kontroler” nie pozwala na żadne działanie. Wpis „akcja eksportu nie może rozwiązać swojej zależności w tej wersji docelowej; oto wyjątek i trasa” daje programiście odtwarzalny błąd.

Oznaczenie jako przestarzałe samo w sobie nie blokuje aktualizacji. Zapisz jego wpływ i planowany zamiennik w odniesieniu do swojej polityki wsparcia, odróżniaj ostrzeżenie od niedostępnej ścieżki i zachowaj działającą obsługiwaną ścieżkę, chyba że wymagania wydania lub wykazane zachowanie uzasadniają jej zastąpienie.

Zastępuj usunięte API bez zmiany publicznego kontraktu

Formatowanie cen

Tools::displayPrice() oznaczono jako przestarzałe w PrestaShop 1.7.6 i usunięto w 9.0. W żądaniu nowoczesnego sklepu użyj ustawień regionalnych z kodem ISO waluty. W kodzie obejmującym wiele wydań wywołaj zamiast tego funkcję pomocniczą zgodności.

$context = Context::getContext();
$formatted = $context->getCurrentLocale()->formatPrice(
    19.95,
    $context->currency->iso_code
);

// With the shared compatibility package installed and autoloaded:
$formatted = \MyPrestaRocks\Compat\PriceFormatter::format(
    19.95,
    $context->currency
);

Jawnie inicjalizuj wymagany kontekst w kodzie CLI lub procesów roboczych. Prosty formater zastępczy nie odtworzy wszystkich reguł walutowych i regionalnych.

Odpowiedzi AJAX

Zastąp usunięte wywołania ajaxDie() obsługiwaną ścieżką odpowiedzi kontrolera. Starsze ajaxRender() renderuje treść, ale samo w sobie nie zapewnia takiego samego kontraktu zakończenia. Funkcja pomocnicza odpowiedzi dla zgodności może zakodować tablice do JSON, ustawić typ zawartości, wywołać natywny renderer i zakończyć działanie. W kontrolerach Symfony zwracaj JsonResponse.

Zależności

PrestaShop 9 usunął zależności, które starsze moduły mogły pożyczać z rdzenia, w tym Guzzle, SwiftMailer, Tactician Bundle i PEAR Archive_Tar. Przeszukaj swoje importy i każdą odroczoną ścieżkę wykonania oraz sprawdź spakowany moduł, a także listę zależności wersji docelowej. Ekran konfiguracji może działać, a pierwsze zaplanowane wywołanie HTTP lub e-mail mimo to zawiedzie.

Przy migracji klienta HTTP zachowaj bazowy URL, parametry zapytania, uwierzytelnianie, limity czasu i kontrole odpowiedzi. Żądanie Symfony HttpClient może używać auth_bearer i dekodować JSON przez toArray(); obsłuż wyjątki transportu, HTTP i dekodowania. Przy migracji do Mailer utwórz Email z nadawcą, odbiorcą, tematem, treścią i załącznikami, a następnie wyślij go przez skonfigurowany MailerInterface. Jawnie zarejestruj lub dołącz zależności wymagane przez moduł. Dołączona biblioteka może nadal kolidować z wersją ładowaną przez rdzeń lub inny moduł, więc sprawdź automatyczne ładowanie w kompletnym sklepie.

Konfiguracja poczty w PrestaShop 9 zmieniła się wraz z Symfony Mailer. Przetestuj rzeczywisty serwer SMTP, port, szyfrowanie i uwierzytelnianie. Stara wartość szyfrowania inna niż „off” jest mapowana przez implementację poczty na flagę TLS, więc aktualizacja nie musi zepsuć każdego serwera skonfigurowanego wcześniej z SSL. Wyślij każdy typ wiadomości transakcyjnej do testowej skrzynki i sprawdź jej zmienne, nadawcę, tłumaczenia, nagłówki i załączniki.

Migruj kontrolery Symfony i weryfikuj uprawnienia

PrestaShop 9 używa Symfony 6.4. Nowe kontrolery panelu administracyjnego Symfony powinny rozszerzać PrestaShopAdminController i otrzymywać zależności przez wstrzykiwanie do konstruktora lub akcji. Starszy FrameworkBundleAdminController pozostaje przestarzałym mostem zgodności: jego get() nadal może pobierać publiczne usługi z globalnego kontenera. Nie traktuj tego mostu jako dowodu, że konfiguracja zależności nie wymaga już uwagi.

Poniższy przykład PHP 8.1+ wstrzykuje zarejestrowaną usługę kontekstu rdzenia i chroni akcję odczytu. Zakłada, że autoloader modułu mapuje Acme\Compat\ na src/, a karta AdminAcmeCompat zapewnia zamierzone mapowanie uprawnień.

<?php
namespace Acme\Compat\Controller;

use PrestaShop\PrestaShop\Core\Context\CurrencyContext;
use PrestaShopBundle\Controller\Admin\PrestaShopAdminController;
use PrestaShopBundle\Security\Attribute\AdminSecurity;
use Symfony\Component\HttpFoundation\Response;

final class CompatibilityController extends PrestaShopAdminController
{
    private CurrencyContext $currencyContext;

    public function __construct(CurrencyContext $currencyContext)
    {
        $this->currencyContext = $currencyContext;
    }

    #[AdminSecurity("is_granted('read', request.get('_legacy_controller'))")]
    public function indexAction(): Response
    {
        return new Response($this->currencyContext->getIsoCode());
    }
}

Zarejestruj kontroler jako usługę i udostępnij trasę. Utrzymuj mapowanie kontroli dostępu zgodne z zainstalowaną kartą. Dla akcji zmieniającej stan używaj odpowiedniego uprawnienia tworzenia, edycji lub usuwania i dodaj ochronę CSRF. Udany autowiring na czystej instalacji nie sprawdza każdej kombinacji sklepu, więc przetestuj rzeczywistą trasę, wykrywanie usług i argumenty akcji w zestawie modułów sprzedawcy.

# config/services.yml
services:
  Acme\Compat\Controller\CompatibilityController:
    public: true
    autowire: true
    autoconfigure: true
    tags: ['controller.service_arguments']

# config/routes.yml
acme_compat_index:
  path: /acme-compat
  methods: [GET]
  defaults:
    _controller: 'Acme\Compat\Controller\CompatibilityController::indexAction'
    _legacy_controller: AdminAcmeCompat

Atrybuty, adnotacje i listenery zdarzeń

Migruj deklaracje routingu, AdminSecurity i DemoRestricted oddzielnie. Nowoczesne atrybuty bezpieczeństwa używają PrestaShopBundle\Security\Attribute. Zachowana ścieżka adnotacji AdminSecurity nadal jest egzekwowana w PrestaShop 9, choć jest przestarzała.

Testuj każdą trasę po wylogowaniu i z pracownikami o różnych uprawnieniach. Potwierdź, że dostęp do odczytu nie pozwala na zapis. Sprawdź też ograniczenia trybu demonstracyjnego i wszystkie trasy AJAX. Pomyślne wyświetlenie strony nie jest testem uprawnień.

1. Otwórz rzeczywistą listę lub formularz jako uprawniony pracownik. Uruchom filtr, eksport, akcję wiersza, operację AJAX i akcję masową, jeśli moduł je udostępnia.
2. Powtórz chronione operacje jako pracownik bez odpowiedniego uprawnienia. Potwierdź, że po odmowie rekordy pozostają niezmienione; ukryty przycisk nie jest dowodem.
3. Przetestuj każde zabezpieczenie osobno na środowisku testowym: nieprawidłowe dane z poprawnym tokenem CSRF, a następnie poprawne dane z brakującym lub nieprawidłowym tokenem. Spróbuj też niedozwolonej metody HTTP. Sprawdź odpowiedź i potwierdź, że każdy odrzucony zapis pozostawia rekordy bez zmian.

Możesz zachować listenery zdarzeń z tagami w YAML lub użyć atrybutu Symfony AsEventListener w zarejestrowanej, automatycznie konfigurowanej usłudze. Atrybut nie rejestruje klasy, która nie została w inny sposób wykryta. Jeśli podczas migracji używasz getSubscribedServices(), połącz subskrypcje klasy nadrzędnej i jawnie zadeklaruj wymagane usługi.

Obsługa dwóch generacji kontrolerów

Jeśli jeden moduł obsługuje PS 8 i 9, niewielka nadrzędna klasa zgodności może wybierać dostępną klasę. Rozwiązanie to wybiera jedynie klasę nadrzędną; nie niweluje wszystkich różnic w metodach ani w kontenerze usług.

<?php
namespace Acme\Compat\Controller;

if (class_exists('PrestaShopBundle\Controller\Admin\PrestaShopAdminController')) {
    abstract class CompatibleAdminController extends \PrestaShopBundle\Controller\Admin\PrestaShopAdminController
    {
    }
} else {
    abstract class CompatibleAdminController extends \PrestaShopBundle\Controller\Admin\FrameworkBundleAdminController
    {
    }
}

Konfiguruj usługi, kontekst i polecenia konsolowe dla docelowego wydania

Konfiguracja usług

W wydaniach przed 9.2 zachowaj config/services.yml jako punkt wejścia usług modułu. Może on jawnie importować konfigurację PHP. Umieszczenie obok osobnego services.php nie sprawi, że starsze mechanizmy ładowania automatycznie wybiorą ten plik.

# config/services.yml on an older target
imports:
  - { resource: services.php }

W 9.2 priorytet plików usług to services.php, następnie services-9.2.yml, potem services-9.yml i services.yml. Traktuj wybrany plik jako punkt wejścia i importuj wszystko inne, czego potrzebuje. Autowiring nadal wymaga jawnych wartości argumentów skalarnych i jawnych powiązań, gdy interfejsy mają wiele implementacji.

Działającego YAML nie trzeba przepisywać na PHP dla wyglądu: zachowaj go, dopóki wersja docelowa go ładuje, a wymagane usługi się rozwiązują. Sama zmiana formatu nie jest dowodem odbioru.

Sprawdź dekorowanie usług z pełnym zestawem zainstalowanych modułów. Kolejność dekorowania, widoczność usług i konfiguracja innego modułu mogą zmienić implementację, która otrzyma wywołanie.

Kontekst i uwierzytelnianie pracowników

Context::getContext() pozostaje dostępne. W nowym kodzie Symfony preferuj wstrzykiwane usługi kontekstu i ustal kontekst sklepu, języka, waluty i pracownika potrzebny poleceniom lub procesom roboczym.

Usługi kontekstu obejmują EmployeeContext, ShopContext, LanguageContext, CurrencyContext, CountryContext, ApiClientContext i LegacyControllerContext. Używaj CurrencyContext::getId(), getIsoCode() lub getConversionRate() dla potrzebnej wartości. Nie istnieje CurrencyContext::getCurrency().

Panel administracyjny używa Symfony Security do uwierzytelniania pracowników. Odczytuj tożsamość pracownika przez obsługiwany kontekst pracownika lub usługę bezpieczeństwa, zamiast traktować starsze pola ciasteczka jako źródło uwierzytelnienia. EmployeeContext::getEmployee() może zwrócić null, a wstrzyknięcie usługi kontekstu nie loguje pracownika dla polecenia ani procesu roboczego. Używaj RequestStack dla własnych danych sesji żądania i obsłuż brak żądania lub sesji poza wykonaniem HTTP.

Kernele konsoli

PrestaShop 9 ma kernele aplikacji admin, admin-api i front. Przed użyciem poniższych przykładów sprawdź listę poleceń i pomoc zainstalowanej konsoli dla dokładnego wydania, potwierdzając identyfikatory aplikacji i obsługiwane opcje. Sprawdzaj swoje polecenie i usługi w kernelu, w którym działają. Nie zakładaj, że polecenie zarejestrowane w jednej aplikacji jest dostępne w innej.

php bin/console list --app-id=admin
php bin/console debug:container 'Acme\Compat\Controller\CompatibilityController' --app-id=admin
php bin/console debug:event-dispatcher kernel.request --app-id=front
php bin/console debug:router --app-id=admin-api

Do diagnozowania wykrywania używaj list, debug:container i konfiguracji usług. Rejestruj polecenia konsoli za pomocą obsługiwanej konfiguracji Symfony dla docelowego kernela. Sprawdź definicję usługi polecenia i jej tagi w tym kernelu, a zaplanowane polecenia uruchamiaj tym programem PHP CLI i na tym koncie wykonawczym, których faktycznie używa harmonogram.

Przykład: strona ustawień działa, zaplanowany eksport zawodzi

Załóżmy, że strona ustawień zapisuje się poprawnie, ale eksport ładuje bibliotekę HTTP dopiero przy uruchomieniu zaplanowanego zadania. Przetestuj to polecenie z dostarczonej paczki z zamierzonym PHP CLI i kontem wykonawczym oraz sprawdź dostępność i konfigurację biblioteki oraz odpowiedź zewnętrzną. Udana instalacja nigdy nie przeszła tej ścieżki.

Następnie porównaj kontekst sklepu i języka polecenia z żądaniem w panelu administracyjnym. Proces roboczy nie może po cichu dziedziczyć sklepu, który pracownik wybrał jako ostatni. Potwierdź, że odczytuje zamierzone rekordy i zapisuje do zamierzonego konta zdalnego, a następnie ponów nieudany eksport w sandboxie i sprawdź, czy nie powstały zduplikowane rekordy zewnętrzne.

Sprawdzaj hooki, dane motywu i punkty końcowe obsługiwane przez routing

Hooki i migracje stron

System hooków pozostaje dostępny, ale każdy wykonywany hook należy do konkretnej ścieżki kodu. Zmigrowany edytor produktów nie wykonuje już starych hooków cyklu życia actionAdminProductsController*. Niektóre starsze hooki logowania pozostają: actionAdminLoginControllerSetMedia dla zasobów i displayAdminLogin dla HTML. Używaj actionBackOfficeLoginForm i actionEmployeeRequestPasswordResetForm do rozszerzania tych formularzy, zdarzeń Symfony Security do logiki uwierzytelniania i nowoczesnych hooków formularza produktu do pól produktów.

Na stronach sklepu używających prezenterów odczytuj prezentowane dane, zamiast zakładać starszą strukturę obiektu. Dane obrazu mogą teraz być tablicą zawierającą adresy URL dla poszczególnych rozmiarów, na przykład $manufacturer.image.medium.url w Smarty. Do zmian danych preferuj odpowiedni hook actionPresent*, jeśli jest dostępny.

Smarty, Twig i Hummingbird

PrestaShop używa obu systemów szablonów. Motywy części sklepowej i starsze strony panelu administracyjnego używają Smarty. Zmigrowane strony panelu Symfony używają Twig. Przejście na Symfony nie zastąpiło Smarty w całej platformie.

Hummingbird jest domyślnym motywem nowych instalacji 9.1; aktualizacja nie zastępuje automatycznie istniejącego motywu sklepu. Testuj Classic, Hummingbird i każdy motyw, którego obsługę deklarujesz, a także rzeczywisty motyw sprzedawcy. Sprawdź karty produktów, zmiany kombinacji, koszyk, składanie zamówienia, konto klienta, miejsca hooków, selektory i zdarzenia JavaScript. Założenia dotyczące znaczników konkretnego motywu mogą zawieść, nawet gdy API PHP nadal działa: hook może wyświetlić właściwy tekst, a inne znaczniki motywu sprawią, że selektor lub obsługa kliknięcia nie znajdzie elementu sterującego. Pozostaw błędy przeglądarki widoczne na chronionym środowisku testowym.

AJAX i powiadomienia zwrotne

Przenieś bezpośrednio wywoływane skrypty ajax.php i callback.php z katalogu głównego modułu do obsługiwanego cyklu życia kontrolera. Dopóki tego nie zrobisz, nie zakładaj, że taki plik na pewno nie zadziała w PrestaShop 9 ani że jest bezpieczny: sprawdź jego uwierzytelnianie, kontekst i obsługę żądań. ModuleFrontController zapewnia żądaniu normalną ścieżkę routingu i kontekstu. Nie autoryzuje automatycznie Twojej operacji biznesowej.

W starszym kontrolerze AJAX udostępniającym displayAjaxProcess() włącz obsługę AJAX oprócz wybrania akcji. Wygenerowany adres URL modułu może zawierać ajax=1 i action=process. W PrestaShop 9 żądanie z Accept: application/json również włącza wykrywanie AJAX. Sama obecność action=process nie wystarcza.

$url = $this->context->link->getModuleLink(
    $this->name,
    'ajax',
    array('ajax' => 1, 'action' => 'process'),
    true
);

Dla danych klientów wymagaj uwierzytelnienia klienta i sprawdzania własności. Dla akcji administracyjnych wymagaj uprawnień pracownika i ochrony CSRF. W zewnętrznych callbackach weryfikuj podpis dostawcy i stosuj jego reguły obsługi duplikatów; zmiana URL nie zapewnia zaufania. Kontrole tokenów lub podpisów wykonuj na serwerze, używaj odpowiednich metod HTTP i zwracaj zamierzony status oraz typ zawartości.

Testuj callbacki dostawcy jego narzędziami sandbox: brakującą lub nieprawidłową weryfikację, normalne poprawne zdarzenie i powtórne doręczenie. Odrzucone zdarzenie nie może wykonać operacji biznesowej, a powtórzenie nie może jej zduplikować.

Podczas migracji punktu końcowego uzgodnij nowy adres z usługą zewnętrzną i przetestuj go przed przełączeniem. Nie pozostawiaj starego adresu dostępnego jako nieudokumentowanej ścieżki zapasowej. Uzgodnij, jak opóźnione zdarzenia trafią do właściwego punktu końcowego w trakcie wdrożenia, i zachowaj je do uzgodnienia, nie pozwalając im zmieniać częściowo zmigrowanej bazy danych.

Kontrakty integracji, które pozostają dostępne

Starsze Webservice API pozostaje dostępne obok nowszego Admin API. Wybieraj API według obsługiwanych zasobów i kontraktu uwierzytelniania, a nie zastępuj integracji na podstawie samej nazwy, i przed zmianą sprawdź uprawnienia, dane żądań, identyfikatory i zachowanie przy ponowieniach. Deskryptor modułu, Db::getInstance(), Configuration::get(), Configuration::updateValue() i ObjectModel pozostają dostępne. Konkretne przestarzałe klasy lub metody wymagają indywidualnych migracji; obiekty ObjectModel encji rdzenia jako grupa nie są przestarzałe.

Szerszy proces rozszerzania, integracji i zabezpieczania opisują poradnik hooków, poradnik Webservice API i lista kontrolna bezpieczeństwa.

Kontroluj konflikty i zachowanie właściwe dla sklepu

Preferuj hooki, obsługiwane usługi i dekorowanie usług, gdy zapewniają wymagany punkt rozszerzenia. Unikaj edycji plików rdzenia. Bezpośrednie zmiany rdzenia utrudniają porównywanie zachowania, stosowanie aktualizacji i odtwarzanie błędów.

Nadpisanie klasy zwykle rozszerza zainstalowaną klasę Core. Jej odziedziczone metody nadal pochodzą z tego rdzenia. Skopiowana logika wewnątrz nadpisanej metody może się zdezaktualizować, a niezgodna sygnatura może spowodować błąd po aktualizacji.

Instalator modułów może scalać niekonfliktowe metody, właściwości i stałe z istniejącym nadpisaniem klasy. Dwa moduły rozszerzające Product nie są automatycznie niezgodne. Konflikty powstają, gdy definiują ten sam element klasy lub wprowadzają niezgodne zachowanie. Udokumentuj objęte zmianą elementy klasy i sprawdź złożone nadpisanie oraz pamięć podręczną indeksu klas po zmianach.

Wyjątki muszą być widoczne: moduł może na przykład zawierać uzasadnione nadpisanie klasy PDF. Zapytaj, co zmienia, jak współpracuje z innymi zainstalowanymi modułami, jak testowane są aktualizacje i co usuwa odinstalowanie. Odinstalowanie może celowo zachowywać dane i nie może obiecywać cofnięcia każdego skutku zewnętrznego.

Testuj środowisko, a nie tylko numer wersji:

• Działanie reguł przepisywania Apache, Nginx lub LiteSpeed i uprawnienia plików.
• Wymagane rozszerzenia PHP, limity pamięci, OPcache i wersje PHP zadań w tle.
• Kontekst jednego sklepu, grupy sklepów i wszystkich sklepów, w tym dziedziczenie konfiguracji.
• Grupy klientów, ceny grupowe, ceny specyficzne, podatki, waluty, języki i zaokrąglenia.
• Inne moduły używające tych samych hooków, usług, szablonów lub elementów klas.
• Zmodyfikowane pliki rdzenia, własne motywy i historyczne dane z wcześniejszych wydań modułu.

Waliduj dane przychodzące do hooka i nieoczekiwany stan. Używaj odpowiedniego API tłumaczeń. Gdy brakuje danej możliwości, wyjaśnij, która funkcja jest niedostępna i jak postępować. Jasne etykiety, wartości domyślne i teksty pomocy zmniejszają liczbę błędów konfiguracji.

Utrzymuj niewielki narzut kodu zgodności i łatwość jego utrzymania

Kończ obsługę hooków od razu, gdy bieżąca strona nie potrzebuje Twojej funkcji. Ogranicz arkusze stylów i JavaScript do kontrolerów, które ich używają. Hook nagłówka może wykonywać się na wielu stronach sklepu, więc unikaj niepotrzebnego zapytania lub renderowania szablonu przy każdym żądaniu.

Przechowuj w pamięci podręcznej wielokrotnie używane wyniki zapytań tylko wtedy, gdy klucz zawiera każdy istotny kontekst sklepu, języka, waluty i klienta. Unieważniaj je po zmianie danych źródłowych. Pamięć podręczna lokalna dla żądania i trwała pamięć podręczna mają różne okresy życia.

Mierz narzut na reprezentatywnych danych za pomocą profilera. Na środowisku testowym _PS_DEBUG_PROFILING_ może pomagać obok trybu deweloperskiego. Porównuj tę samą trasę, stan pamięci podręcznej i dane przed zmianą i po niej. Nie istnieje uniwersalny limit milisekund dla modułu, który dowodzi, że sklep będzie szybki.

Utrzymuj warstwę pośrednią mniejszą niż problem, który rozwiązuje. Używaj czytelnych metod, zwykłego przepływu sterowania i jednego dobrze zdefiniowanego mechanizmu zastępczego. Wspólne poprawki powinny trafiać do każdego korzystającego modułu przez kontrolowaną aktualizację zależności i kontrole wydania. Świadomie usuwaj nieużywane funkcje i przekształcaj powtarzające się pytania do pomocy technicznej w lepszą dokumentację lub odtwarzalne przypadki testowe.

Testuj zainstalowany ZIP i każdą deklarowaną ścieżkę aktualizacji

Zacznij od czystej instalacji dla każdej obsługiwanej kombinacji platformy, używając dostarczonego pliku ZIP, a nie kopii roboczej programisty: zależności obecne tylko na komputerze programisty nie pokazują, że sprzedawca otrzymuje kompletny moduł. Następnie użyj kopii testowej odwzorowującej prawdziwy sklep: reprezentatywny rozmiar katalogu, historię zamówień, języki, motyw i zestaw modułów. Chroń dane klientów i trzymaj testowe dane dostępowe płatności, poczty i integracji osobno. Odizoluj kopię przed pierwszym uruchomieniem aplikacji, procesu roboczego lub zadania cyklicznego, z osobną bazą danych, danymi dostępowymi sandbox, testową skrzynką i kontrolowanym dostępem z zewnątrz, aby testy nie mogły kontaktować się z prawdziwymi klientami ani realizować prawdziwych zamówień.

Zachowaj PS 9.0 lub 9.1 w macierzy tak długo, jak deklarujesz ich obsługę. Dodawaj późniejsze wydania jawnie. W 9.1 sprawdź zainstalowane flagi funkcji rabatów i wielu przesyłek, hooki cyklu życia i konfiguracji oraz operacje CLI. W 9.2 uwzględnij wybór plików usług i kontrakt jednostronicowego składania zamówienia. Korzystaj ze zmian w 9.0, zmian w 9.1 i zmian w 9.2, aby ustalić kontrole właściwe dla wydania.

1. Sporządź wykaz kontrolerów, zależności, hooków, zadań, punktów końcowych i założeń dotyczących szablonów modułu.
2. Popraw użycia usuniętych API i odpowiedzialność za zależności, a następnie zmigruj usługi kontrolerów i kontrolę dostępu.
3. Zweryfikuj wyniki zarówno nowej instalacji, jak i aktualizacji modułu. Nie zakładaj, że prowadzą do tego samego stanu.
4. Uruchom opóźnione ścieżki kodu, w tym zadania harmonogramu, akcje masowe i e-maile.
5. Powtórz odpowiedni proces z rzeczywistym motywem i innymi zainstalowanymi modułami.
6. Opublikuj wraz z wydaniem dokładne przetestowane wersje, ograniczenia i instrukcje wycofania zmian.

Zadbaj o powtarzalność każdego testu

Używaj tego samego arkusza dla wersji docelowej sprzedawcy i dla starszych środowisk, które nadal obsługujesz. Zapisz w raporcie z testów następujące pola:

• Środowisko: dokładne wersje PrestaShop i PHP, motyw, kontekst sklepu, istotne zależności i datę.
• Paczka: wersję modułu i dokładną testowaną paczkę dystrybucyjną, a przy aktualizacji także początkową wersję modułu.
• Dane początkowe: reprezentatywne zapisane ustawienia i rekordy, języki, waluty oraz rolę pracownika.
• Działanie i oczekiwanie: zadanie klienta lub pracownika oraz oczekiwany wynik biznesowy.
• Obserwacja: wynik pozytywny lub błąd, powiązane logi lub zrzuty ekranu, znane ograniczenie i osobę odpowiedzialną.

Przykład: zachowanie ustawień właściciela sklepu podczas aktualizacji modułu

Użyj testowego zestawu danych z ustawieniami edytowanymi przez sprzedawcę, rekordami modułu i odpowiednimi powiązaniami ze sklepami. Zapisz ważne wartości przed uruchomieniem obsługiwanej aktualizacji. Następnie porównaj zamierzony schemat, hooki, karty i uprawnienia z projektem docelowym i potwierdź, że dotychczasowe wybory i powiązane rekordy przetrwały. Nowa instalacja może ustalić nowe wartości domyślne; aktualizacja nie powinna nadpisywać prawidłowych wyborów sprzedawcy tylko po to, by dopasować je do tych wartości.

Nie resetuj ani nie odinstalowuj modułu, aby test aktualizacji przeszedł: może to usunąć właśnie te dane, które aktualizacja musi zachować.

Wdrażaj z planem powrotu

Nie zastępuj pełnego przebiegu testów szeroką deklaracją zgodności. Przed wdrożeniem zachowaj instalowalną poprzednią kompilację modułu oraz spójną kopię zapasową bazy danych i plików. Przed zmianami schematu, usunięciem lub zastąpieniem odtwórz tę kopię na środowisku testowym i przećwicz wycofanie zmian, a następnie sprawdź wymagane ścieżki klientów i pracowników zarówno po odtworzeniu, jak i po aktualizacji.

Uzgodnij okno wdrożenia, warunek wycofania zmian i sposób uzgodnienia zamówień lub zapisów zewnętrznych przyjętych po wykonaniu migawki. Wdróż przetestowaną paczkę, powtórz niezbędne kontrole, obserwuj odpowiednie cykle zadań i procesów biznesowych i potwierdź, że publiczne wyświetlanie debugowania jest wyłączone. Przekaż paczkę, kod źródłowy, notatki o zależnościach i konfiguracji, wyniki testów i procedurę odtwarzania.

O co zapytać programistę przed odbiorem

• Które dokładnie środowiska i aktualizacje z istniejącymi danymi przeszły testy, a które pozostają niesprawdzone?
• Które ustalenia były rzeczywistymi niezgodnościami, a które zmiany stanowiły opcjonalne prace utrzymaniowe?
• Które ustawienia klienta i rekordy modułu porównano przed aktualizacją i po niej?
• Czy inny programista może zbudować i wdrożyć dostarczoną paczkę na podstawie udokumentowanego kodu źródłowego?
• Kto odpowiada za koordynację z dostawcami, awarię wdrożenia i uzgodnienie danych po wycofaniu zmian?

Jeśli zmiana zawiedzie, zachowaj dowody i skorzystaj z poradnika rozwiązywania problemów, aby wyodrębnić błędną ścieżkę, zanim zastosujesz kolejne migracje lub inną zmianę na produkcji.