websystems/ws-prestashop-update-package

A Composer package for PrestaShop to manage module licensing and updates for Websystems package server.

v1.0.9 2026-05-29 10:34 UTC

Requires

• php: >=7.2
• ext-curl: *
• ext-zip: *

proprietary

• Artur Ograbek

README

Paczka Composer do zarządzania licencjami i aktualizacjami modułów PrestaShop przez serwer UpdatePulse. Zamiast duplikować kod w każdym module, wystarczy dołączyć tę paczkę i użyć gotowego traita.

Wymagania

• PHP >= 7.2
• Rozszerzenia PHP: ext-curl, ext-zip
• PrestaShop 1.7 lub 8.x
• Plik updatepulse.json w katalogu głównym modułu

Instalacja

composer require websystems/ws-prestashop-update-package

Następnie upewnij się, że autoload Composera jest ładowany w module (zwykle już jest w vendor/autoload.php).

Plik updatepulse.json

Każdy moduł musi posiadać plik updatepulse.json w swoim katalogu głównym (np. modules/ws_mymodule/updatepulse.json):

{
    "server": "https://admin.k4.pl",
    "packageData": {
        "Name": "Nazwa modułu",
        "Version": "1.0.0",
        "Homepage": "https://admin.k4.pl/",
        "Author": "Web Systems",
        "AuthorURI": "https://admin.k4.pl/",
        "Description": "Opis modułu",
        "RequireLicense": true
    }
}

Opcjonalnie można dodać pole "Slug" w packageData — jeśli go nie ma, używana jest nazwa modułu ($module->name).

Integracja z modułem

Trait WsLicenseTrait można użyć w dwóch miejscach niezależnie lub razem:

Miejsce	Do czego
Klasa modułu (Module)	Globalny baner powiadomień o aktualizacji
Kontroler admina (ModuleAdminController)	Pełna zakładka „Licencja i aktualizacje"

1. Globalny baner powiadomień (klasa modułu)

Dzięki temu baner o dostępnej aktualizacji pojawia się na każdej stronie admina — wewnątrz #content, tak samo jak natywne komunikaty PrestaShop — a nie tylko w zakładce konfiguracji modułu.

class Ws_mymodule extends Module
{
    use \Websystems\PrestashopUpdatePackage\Traits\WsLicenseTrait;

    public function __construct()
    {
        // ...
        parent::__construct();
        // ...

        // Inicjalizacja klienta aktualizacji
        $this->wsInitUpdateManager($this, 'WS_MYMODULE');
    }

    public function install(): bool
    {
        return parent::install()
            && $this->registerHook('displayAdminAfterHeader');
            // ... pozostałe hooki
    }

    /**
     * Renderuje baner z informacją o dostępnej aktualizacji.
     * Sprawdzanie serwera odbywa się max raz na 24 h (cache w Configuration).
     * Sam baner pokazuje się zawsze gdy wykryto nowszą wersję — bez limitu czasowego.
     */
    public function hookDisplayAdminAfterHeader(): string
    {
        $tabUrl = $this->context->link->getAdminLink('AdminWsMyModule') . '&ws_tab=license';
        return $this->wsRenderUpdateNotification($tabUrl);
    }
}

Wariant z hookDisplayBackOfficeHeader — automatyczne sprawdzanie w tle

Jeśli chcesz aby sprawdzanie aktualizacji odbywało się automatycznie w tle na każdej stronie admina (bez renderowania HTML), użyj wsCheckForUpdates(). Metoda odpytuje serwer max raz na 24 h — same zarządza cache w Configuration; nie musisz ręcznie porównywać timestampów ani zapisywać czasu ostatniego sprawdzenia.

class Ws_mymodule extends Module
{
    use \Websystems\PrestashopUpdatePackage\Traits\WsLicenseTrait;

    public function __construct()
    {
        parent::__construct();
        $this->wsInitUpdateManager($this, 'WS_MYMODULE');
    }

    public function install(): bool
    {
        return parent::install()
            && $this->registerHook('displayBackOfficeHeader')
            && $this->registerHook('displayAdminAfterHeader');
            // ... pozostałe hooki
    }

    /**
     * Sprawdza aktualizacje w tle — max raz na 24 h.
     * Nie renderuje HTML. Odpowiednik ręcznego wzorca z Configuration::get/updateValue.
     */
    public function hookDisplayBackOfficeHeader(): void
    {
        $this->wsCheckForUpdates();
    }

    /**
     * Renderuje baner gdy dostępna jest nowsza wersja.
     * Dane są już w cache z hookDisplayBackOfficeHeader.
     */
    public function hookDisplayAdminAfterHeader(): string
    {
        $tabUrl = $this->context->link->getAdminLink('AdminWsMyModule') . '&ws_tab=license';
        return $this->wsRenderUpdateNotification($tabUrl);
    }
}

2. Zakładka „Licencja i aktualizacje" (kontroler admina)

use Websystems\PrestashopUpdatePackage\Traits\WsLicenseTrait;

class AdminWsMyModuleController extends ModuleAdminController
{
    use WsLicenseTrait;

    public function __construct()
    {
        parent::__construct();
        // Inicjalizacja — przekaż instancję modułu i prefiks klucza konfiguracyjnego
        $this->wsInitUpdateManager($this->module, 'WS_MYMODULE');
    }

    public function postProcess()
    {
        // Obsługuje submitWsLicenseActivate, submitWsLicenseDeactivate,
        // submitWsCheckUpdate, submitWsInstallUpdate
        $this->wsHandleLicenseActions();
        parent::postProcess();
    }

    public function renderView()
    {
        if (Tools::getValue('ws_tab') === 'license') {
            $adminUrl = $this->context->link->getAdminLink('AdminWsMyModule') . '&ws_tab=license';
            return $this->wsRenderLicenseTab($adminUrl);
        }
        return parent::renderView();
    }
}

Jak działa zarządzanie licencjami

1. Admin wpisuje klucz licencji w formularzu i klika Aktywuj licencję.
2. Paczka wysyła żądanie do serwera UpdatePulse (updatepulse-server-license-api).
3. Serwer weryfikuje klucz i domenę sklepu — w odpowiedzi odsyła license_signature.
4. Klucz i sygnatura są zapisywane w Configuration PrestaShop (klucze: WS_MYMODULE_LICENSE_KEY, WS_MYMODULE_LICENSE_SIG).
5. Dezaktywacja usuwa dane z Configuration i informuje serwer.

Jak działają aktualizacje

1. Paczka odpytuje serwer (updatepulse-server-update-api, akcja get_metadata) max raz na 24 h (cache w Configuration).
2. Wynik jest cache'owany — klucze WS_MYMODULE_UPDATE_INFO (JSON) i WS_MYMODULE_UPDATE_LAST_CHECK (timestamp).
3. Baner powiadomienia (hookDisplayAdminAfterHeader) wyświetla się na każdej stronie admina gdy dostępna jest nowsza wersja; sam baner nie ma żadnego limitu czasowego.
4. W zakładce „Licencja i aktualizacje" pojawia się przycisk Zainstaluj aktualizację oraz link do pobrania ZIP.
5. Instalacja jest wyłącznie ręczna — tylko gdy admin kliknie przycisk. Pobiera ZIP przez cURL (wyłącznie HTTPS), rozpakowuje do _PS_MODULE_DIR_, uruchamia skrypty upgrade z katalogu upgrade/, aktualizuje wersję w ps_module.
6. Przycisk Sprawdź teraz w zakładce wymusza natychmiastowe odpytanie serwera (pomija cache).

Klucze konfiguracyjne w bazie danych

Klucze są budowane automatycznie z przekazanego prefiksu (np. WS_MYMODULE):

Klucz	Zawartość
WS_MYMODULE_LICENSE_KEY	Klucz licencji
WS_MYMODULE_LICENSE_SIG	Sygnatura licencji (z serwera)
WS_MYMODULE_UPDATE_INFO	JSON z metadanymi ostatniej odpowiedzi serwera
WS_MYMODULE_UPDATE_LAST_CHECK	Timestamp ostatniego sprawdzenia aktualizacji

Uwaga: Gdy "RequireLicense": false w updatepulse.json, sekcja licencji jest całkowicie ukryta w zakładce admina, a zapytanie o aktualizacje jest wysyłane bez parametrów licencyjnych.

Struktura paczki

src/
  Update/
    UpdatePulseClient.php     ← klient HTTP do serwera UpdatePulse
  License/
    LicenseTabRenderer.php    ← generator HTML zakładki "Licencja i aktualizacje"
  Traits/
    WsLicenseTrait.php        ← trait do wklejenia w AdminController (zakładka licencji)
  Translations.php            ← tłumaczenia PL/EN (tablice statyczne)

Tłumaczenia

Paczka zawiera wbudowane tłumaczenia PL i EN. Język wykrywany jest automatycznie z Context::getContext()->language->iso_code. Można też użyć bezpośrednio:

use Websystems\PrestashopUpdatePackage\Translations;

$msg = Translations::trans('License activated successfully.', 'pl');
// → "Licencja aktywowana pomyślnie."

Autor

Artur Ograbek — [e-mail]
Web Systems — https://www.web-systems.pl/