Magixcartpay

Architecture E-commerce

Avertissement technique & Prérequis d'installation

Le module Magixcartpay constitue le composant central du commerce électronique sous Magix CMS 4. En raison de sa complexité architecturale, de l'orchestration de modules satellites (paiements sécurisés, facturation, transporteurs) et de la manipulation de flux transactionnels sensibles, son installation, sa configuration en base de données et son intégration dans les thèmes doivent être impérativement confiées à un professionnel expérimenté ou à une agence web spécialisée.

1. Vue d'ensemble & Rôle pivot

Magixcartpay ne se contente pas de gérer un panier d'achat : il agit comme un orchestrateur d'écosystème. Conçu selon les principes de modularité et de découplage strict de Magix CMS 4, il centralise les flux commerciaux tout en déléguant les traitements spécialisés à des extensions tierces interconnectées :

• Passerelles de paiement : intégration modulaire de passerelles en ligne (MagixStripe, etc.) et gestion native des règlements différés (virement bancaire).
• Système de facturation : liaison automatisée avec MagixInvoice pour la génération de documents comptables dès confirmation de paiement.
• Transport & Livraison : architecture prête à accueillir des plugins de transporteurs tiers (points relais, enlèvement sur place, transporteurs nationaux et internationaux).
• Espace Client : intégration bidirectionnelle native avec Magixaccount pour la consultation de l'historique et des détails de commande.

2. Modèle économique hybride : Commandes & Devis

L'une des forces majeures de Magixcartpay réside dans sa capacité à fonctionner aussi bien en boutique en ligne B2C qu'en catalogue de devis B2B sans nécessiter de composants distincts. La configuration globale (table mc_magixcartpay_config) permet trois modes d'exploitation :

3. Architecture d'orchestration des Addons

Magixcartpay ne dépend en dur d'aucun module externe. Au moment de l'initialisation du panier, le contrôleur interroge la table de liaison mc_plugins_module afin d'identifier tous les plugins actifs déclarés pour la cible magixcartpay.

Pour chaque extension détectée, le moteur instancie dynamiquement sa classe d'amorçage :

$bootClass = "Plugins\" . $pluginName . "\Boot";
if (class_exists($bootClass)) {
    (new $bootClass())->register();
}

Cette approche permet d'étendre les fonctionnalités (modes de paiement en ligne, calculs de frais d'expédition complexes) par simple installation d'un plugin supplémentaire, sans jamais modifier le code source de Magixcartpay.

4. Cycle transactionnel & Gestion des événements

Le processus de finalisation (checkout) intègre une double sécurité native : un champ Honeypot contre les robots automatisés et une vérification asynchrone par Google reCAPTCHA v3.

La gestion du cycle de vie d'une commande s'articule autour du gestionnaire d'événements (HookManager) :

1. Création : transformation des lignes du panier en commande dans mc_magixcartpay_order, gestion isolée de l'adresse de facturation et de l'adresse de livraison facultative (mc_magixcartpay_order_address).
2. Notification : envoi automatique des courriels transactionnels de confirmation (client et administrateur) via MailTool avec support SMTP.
3. Mise à jour d'état : lors d'une validation de paiement (manuelle en back-office ou automatique via le Webhook d'un module comme MagixStripe), la méthode updateOrderStatus() exécute le filtre global :

   HookManager::triggerFilter('actionOrderStatusUpdated', true, [
       'order_ref'      => $orderRef,
       'status'         => $status,
       'payment_method' => $paymentMethod
   ]);

   C'est ce signal standardisé qui réveille les modules tiers, déclenchant par exemple la création et l'envoi de la facture PDF par MagixInvoice.

5. Synergie avec l'Espace Membre (Magixaccount)

Lorsqu'il cohabite avec le plugin Magixaccount, Magixcartpay enrichit immédiatement l'espace client :

• Sécurisation du tunnel : possibilité d'exiger une authentification préalable avant d'accéder à la validation du panier.
• Pré-remplissage : récupération des données du compte et du profil pour alimenter automatiquement les champs de facturation.
• Historique & Consultation : injection automatique du lien « Mes commandes » et du tableau récapitulatif dans la barre latérale et le tableau de bord du client via les hooks displayAccountProfileMenu et displayAccountProfileContent.
• Contrôle des achats (Smarty) : mise à disposition de la fonction de gabarit {has_purchased id_product=X} permettant de conditionner l'affichage d'un contenu (téléchargement numérique, dépôt d'avis vérifié) au paiement effectif du produit par l'utilisateur connecté.

6. Points d'accroche Frontend (Hooks)

Le déploiement graphique s'appuie sur des points d'injection clairs :

• {event name="displayHeaderCartWidget"} : injecte le récapitulatif compact du panier dans l'en-tête du site.
• {event name="displayProductAddToCart" id_product=$product.id} : insère le bouton d'ajout au panier et la sélection de quantité sur les fiches produits.
• {event name="displayCartpayOrderActions" order_ref=$order.reference} : point d'extension inséré dans le détail d'une commande (order_detail.tpl), permettant à des modules comme MagixInvoice d'afficher le bouton de téléchargement direct de la facture.

7. Bonnes pratiques de surcharge (Theming)

Pour préserver l'intégrité de la plateforme lors des futures montées de version, les fichiers situés dans plugins/Magixcartpay/views/ ne doivent jamais être édités directement. Toute personnalisation de gabarit (panier, historique, détail de commande, gabarits d'emails) doit s'effectuer par surcharge dans le répertoire du thème actif :

skin/{votre_theme}/plugins/magixcartpay/