Websource Theme Config pour PrestaShop — référence développeur

Vue d'ensemble

• Module websourcethemeconfig, onglet front_office_features, espace de noms Websource\ThemeConfig\ (PSR-4 dans src/, autoload Composer embarqué, aucune dépendance exigée chez le client).
• Un seul réglage JSON WSTC_SETTINGS, propre à chaque boutique (repli : groupe, puis valeur globale), lu et écrit par Settings\SettingsRepository (load(), save(ThemeSettings), shopsWithOwnSettings(), delete()). Settings\ThemeSettings porte les valeurs par défaut (defaults()), les listes de choix (constantes *_CHOICES), get(), with(), color(), layoutClasses().
• Aucun cache propre ; les tables créées : wstc_demo_item (entités de catalogue marquées « démo », depuis 1.11.0).
• Médias : uploads/fonts (polices importées, noms uniques par contenu, Font\UploadedFontStorage), uploads/footer (logos du pied de page, Footer\FooterLogoStorage), uploads/theme (médias importés d'un paquet).

Hooks

Hooks greffés à l'installation

Hooks personnalisés exposés

actionWebsourceThemeExport(array $params): array et actionWebsourceThemeImport(array $params): array : tout module Websource peut y répondre pour être inclus dans l'export / import. Le module appelle directement les méthodes hookActionWebsourceThemeExport / hookActionWebsourceThemeImport des modules installés et actifs (isolation des erreurs).

public function hookActionWebsourceThemeExport(array $params): array
{
    // $params['ctx'] : Websource\ThemeConfig\Package\PackageContext
    return ['key' => 'megamenu', 'version' => 1, 'label' => $this->l('Méga menu'), 'data' => [/* … */]];
}

public function hookActionWebsourceThemeImport(array $params): array
{
    // $params : section, version, data, mode (replace|merge), dry_run (bool), ctx
    return ['action' => 'replace', 'counts' => ['create' => 0, 'update' => 1, 'delete' => 0, 'skip' => 0], 'messages' => []];
}

PackageContext : idShop(), baseUrl(), option($clé, $défaut), toIso(array $parIdLang), langMap(array $parIso), refTo($type, $id) / refResolve($ref), mediaLocalPath($url), warn($message). Règles : aucune écriture en dry_run, replace = l'état du module devient exactement celui du paquet, pas de transaction propre (le hub en gère une), invalider ses caches.

Variables Smarty assignées (hook displayHeader)

Variables CSS émises (<style id="wstc-vars">, Head\ThemeStyleBuilder)

Clés du réglage WSTC_SETTINGS

Valeurs par défaut entre parenthèses.

• Couleurs : primary (#0369a1), secondary (#0b3a5c), accent (#f5b83d), ink (#0f172a), line (#dbe4ee), page_bg, surface (#ffffff), footer_bg (#0c2a43), color_intensity (balanced ; sober, vivid), admin_palette (0).
• Forme : borders (1), shadow_when_no_border (1), radius (xl ; none, sm, md, lg).
• Polices : font_body_mode, font_head_mode (system ; google, upload), font_body, font_head, font_body_file, font_head_file.
• Head : og_enabled (1), theme_color (1), og_image, twitter_site, fb_app_id, preconnect, dns_prefetch, preload, head_extra.
• Microdonnées : ld_same_as, ld_phone, ld_email, ld_ship_countries, ld_handling_min|max, ld_transit_min|max, ld_ship_cost, ld_ship_free_from, ld_ship_currency, ld_return_mode, ld_return_days, ld_return_countries, ld_return_fees, ld_return_fee_amount, ld_return_method, ld_return_url, ld_pay_auto (0), ld_payment, ld_area_served, ld_price_range, ld_currencies_auto (0), ld_currencies.
• RSS : rss_enabled (1), rss_limit (30).
• Pied de page : copyright (par langue), footer_info_enabled (1), footer_info_shop (0 = boutique courante), footer_info_logo (1), footer_info_name (1), footer_logo_light, footer_logo_dark, footer_description (par langue), footer_social (réseau → URL).
• Mise en page (écrites par Websource Builder via saveLayout()) : mobile_nav (bottom, top), mobile_header (icons_right, centered, stacked), desktop_header (classic, centered, compact, split, band, dark, large, sticky), footer_variant (dark, light, brand, centered, minimal, accent, twotone, contrast), search_width (md ; sm, lg, full), search_align (center ; left, right), header_actions (main, top), header_min_height (0), header_pad_top (20), header_pad_bottom (20).
• Catalogue : subcat_mode (image_name), subcat_autoplay (1), subcat_delay (5), thumb_pad (0), thumb_img_radius (same, inner), thumb_variants (color ; off, all), thumb_variants_max (5, de 1 à 12), thumb_variants_stock (grey ; show, hide), share_networks, checkout_header, checkout_footer (full ; minimal, none).
• Badges : badge_radius_mode (pill), badge_radius_px (8), badge_font_size (12), badge_font_weight (700), badge_uppercase (0), badge_border_width (0), badge_pad_y (2), badge_pad_x (10), badge_gap (4), badge_<type>_bg|fg|bd (vide).

Autre clé de configuration : WSTC_PKG_PROFILES (identifiants de profils autorisés, en plus des super administrateurs, à utiliser l'écran Importer / Exporter).

Méthodes publiques du module

Classes utilitaires réutilisables : Color\Color (toFullScale(), contrast(), readable(), asText()), Settings\ColorPresets (9 palettes, match()), Ecosystem\EcosystemCatalog (correspondance module d'origine → module Websource et hooks attendus), Ecosystem\EcosystemInstaller, Ecosystem\HookRestorer (plan(), restore()), Footer\CopyrightRenderer / CopyrightSanitizer, Head\OrganizationJsonLdBuilder, Head\CommerceJsonLd, Package\DemoLibrary.

Contrôleurs et routes

Back-office

Front

Exemple :

GET /index.php?fc=module&module=websourcethemeconfig&controller=rss&id_category=3
→ 200 Content-Type: application/rss+xml ; <rss version="2.0"><channel><title>Maison Lumen</title>…<item><title>…</title><link>…</link>…

Commandes console

bin/console websource:theme:export <fichier.wsxtheme.json|zip> [--sections=theme,layout,…] [--catalog] [--contact] [--no-media] [--name=…] [--slug=…] [--description=…] [--industry=…]
bin/console websource:theme:import [<fichier>] [--demo=<slug>] [--dry-run] [--sections=…] [--mode=replace|merge] [--shops=current|all|1,2] [--catalog-mode=add|replace_demo|replace_all] [--confirm-replace-catalog] [--apply-contact] [--no-fill-missing] [--lang-map=en:fr] [--no-backup] [--non-atomic] [--json]
bin/console websource:theme:restore [<id>]      # sans identifiant : liste l'historique des imports

Format du paquet .wsxtheme (schéma wsxtheme/1)

• nom.wsxtheme.json : JSON seul, médias référencés ({{base_url}}/chemin ou URL externe). nom.wsxtheme.zip : theme.json + assets/* (médias {{asset:assets/<hash>-<nom>.<ext>}}) + previews/*. Toute autre entrée est ignorée, rien n'est extrait sur le disque.
• theme.json : schema, generator, created, name, slug, description, industry, tags, palette, languages, default_language, preview, previews[], includes (media, catalog, contact), excluded_modules, sections{clé → {version, label, module, data}}, integrity (sha256 du JSON canonique des sections).
• Conventions : textes multilingues indexés par code ISO ; entités référencées par type:slug (category:<link_rewrite>, product:…, cms:…, brand:…, supplier:…, cmscat:…, slider:…, category:@home) ; URLs de la boutique réécrites en {{base_url}}.
• Sections du module : theme (couleurs, formes, polices, badges, miniatures, microdonnées non sensibles, partage, RSS/OG), layout (variantes, recherche, hauteurs, logos et descriptions du pied de page, sous-catégories, tunnel), cms (création des pages manquantes seulement), catalog (catalogue de démonstration, sur demande). Autres sections : voir chaque module.
• Médias à l'import : extensions png jpg jpeg gif webp avif svg ico woff2 woff ttf otf, MIME réel vérifié, SVG filtré, signature des polices, 10 Mo par fichier, 200 Mo par paquet, copie sous nom aléatoire dans uploads/theme/.
• Exclus : secrets, code exécutable, head_extra, admin_palette, abonnés, avis réels, clés d'API ; modules websourcesociallogin, websourcecartrecovery, websourcecredit, websourceticketing.
• Démos livrées dans demos/<slug>/ (manifest avec label facultatif), installées par Package\DemoLibrary.

Sécurité

• HTML du copyright assaini à l'enregistrement et à l'affichage (Footer\CopyrightSanitizer) ; head_extra réservé à l'administrateur et jamais exporté.
• Sélecteur de palettes : aucun HTML pour les visiteurs ; cookie psAdmin validé (session, mot de passe, IP, profil super administrateur), jeton CSRF par employé, liste fermée de valeurs.
• Import : réservé aux super administrateurs (+ WSTC_PKG_PROFILES), zip-slip et bombes de décompression refusés, transaction avec point de sauvegarde par section, sauvegarde automatique avant chaque import.

Mises à jour

Scripts upgrade/upgrade-1.5.0.php à upgrade-1.11.0.php : enregistrement des nouveaux hooks (actionPresentProductListing en 1.10.0, hooks d'export / import et table wstc_demo_item en 1.11.0). Les clés absentes de WSTC_SETTINGS prennent leur valeur par défaut : aucune migration de données.