MagixInvoice for Magix CMS 4

MagixInvoice est un module officiel et autonome de facturation pour Magix CMS 4. Il permet la génération automatique de factures au format PDF dès confirmation du paiement d'une commande, l'envoi de la facture en pièce jointe par email et la mise à disposition d'un lien de téléchargement direct depuis l'espace client.

Conçu selon l'architecture modulaire et événementielle de Magix CMS, MagixInvoice s'intègre nativement avec Magixcartpay tout en restant découplé pour être interfacé avec n'importe quel autre module tiers.

---

Fonctionnalités

• Génération automatique de PDF : Création instantanée des factures conformes dès qu'une commande passe au statut paid.
• Numérotation incrémentale personnalisable : Gestion du préfixe (FAC-), de l'année et du compteur séquentiel paramétrable.
• Envoi d'emails transactionnels : Expédition automatique au client avec la facture PDF en pièce jointe via MailTool (support SMTP et fonction mail native).
• Intégration Espace Client : Point d'accroche par Hook pour afficher un bouton de téléchargement direct du PDF dans le détail des commandes (order_detail.tpl).
• Templates personnalisables : Mise en page du PDF et du corps d'email pilotée par Smarty (support MJML/HTML responsive).
• Support multilingue : Fichiers .conf dédiés (i18n/front/) pour adapter les libellés selon la langue de la commande.
• Stockage structuré : Classement des fichiers PDF par arborescence chronologique (upload/invoices/YYYY/MM/).

---

Prérequis

• Magix CMS : Version 4.0 ou supérieure
• PHP : Version 8.2 ou supérieure
• Modules recommandés :
  • Magixcartpay (gestion du panier, commandes et paiements)
  • Magixaccount (espace membre client)

---

Structure du module

plugins/MagixInvoice/
├── Boot.php                       # Enregistrement des hooks et filtres
├── db/
│   └── InvoiceCoreDb.php          # Requêtes de persistance des factures
├── i18n/
│   └── front/
│       └── fr.conf                # Traductions front-office et emails
├── src/
│   └── Service/
│       └── InvoiceService.php     # Moteur métier (génération PDF, envoi email)
└── views/
    ├── front/
    │   └── emails/
    │       └── invoice_attachment.tpl  # Template de l'email avec pièce jointe
    └── pdf/
        └── standard_invoice.tpl        # Template Smarty du document PDF

---

Installation

1. Déposez le dossier MagixInvoice dans le répertoire plugins/ de votre installation Magix CMS :

   git clone [https://github.com/votre-compte/MagixInvoice.git](https://github.com/votre-compte/MagixInvoice.git) plugins/MagixInvoice

2. Rendez-vous dans le panneau d'administration de Magix CMS > Gestion des Plugins.
3. Activez le plugin MagixInvoice et liez-le au module Magixcartpay (ou votre passerelle personnalisée).
4. Assurez-vous que le dossier de destination des uploads dispose des permissions d'écriture :

   chmod -R 775 upload/invoices

---

Base de données

Le plugin s'appuie sur deux tables dédiées :

1. Configuration (mc_magixinvoice_config)

CREATE TABLE IF NOT EXISTS `mc_magixinvoice_config` (
  `id_config` int(11) NOT NULL AUTO_INCREMENT,
  `invoice_prefix` varchar(10) NOT NULL DEFAULT 'FAC-',
  `next_number` int(11) NOT NULL DEFAULT 1,
  PRIMARY KEY (`id_config`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

INSERT INTO `mc_magixinvoice_config` (`invoice_prefix`, `next_number`) VALUES ('FAC-', 1);

2. Registre des factures émises (mc_magixinvoice_document)

CREATE TABLE IF NOT EXISTS `mc_magixinvoice_document` (
  `id_invoice` int(11) NOT NULL AUTO_INCREMENT,
  `invoice_number` varchar(50) NOT NULL,
  `module_source` varchar(50) NOT NULL DEFAULT 'Magixcartpay',
  `source_reference` varchar(50) NOT NULL,
  `client_name` varchar(150) DEFAULT NULL,
  `total_ht` decimal(10,2) NOT NULL DEFAULT 0.00,
  `total_tax` decimal(10,2) NOT NULL DEFAULT 0.00,
  `total_ttc` decimal(10,2) NOT NULL DEFAULT 0.00,
  `pdf_path` varchar(255) NOT NULL,
  `date_add` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id_invoice`),
  UNIQUE KEY `uniq_invoice_number` (`invoice_number`),
  KEY `idx_source_reference` (`source_reference`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

---

Utilisation & Intégration

1. Déclenchement automatique au paiement

Le plugin écoute automatiquement le filtre d'état de commande :

HookManager::addFilter('actionOrderStatusUpdated', function($value, array $params) { ... });

Dès qu'une commande reçoit le statut 'paid', la facture est vérifiée ou générée, puis expédiée au format PDF au client.

2. Affichage du bouton dans l'espace client

Pour afficher le bouton de téléchargement de la facture dans la vue de détail d'une commande (plugins/Magixcartpay/views/front/order_detail.tpl), insérez simplement la balise d'événement à l'endroit désiré :

{event name="displayCartpayOrderActions" order_ref=$order.reference}

Si une facture existe pour cette référence, MagixInvoice génère le lien de consultation du PDF.

---

Personnalisation

• Gabarit du PDF : Modifiez views/pdf/standard_invoice.tpl pour ajuster les mentions légales, le logo, les taux de TVA et le style du document.
• Contenu de l'e-mail : Adaptez views/front/emails/invoice_attachment.tpl en fonction de votre charte graphique (hérite de emails/layout.tpl).
• Traductions : Ajoutez des fichiers de langues dans i18n/front/ (ex. en.conf, nl.conf).

---

Licence & Auteur

• Auteur : Aurélien Gerits (MagixDev)
• Copyright : (C) 2008 - 2026 Gerits Aurélien (Magix CMS)
• Licence : Distribué sous licence GNU General Public License v3 (GPLv3). Consultez le fichier LICENSE pour plus de détails.