Defective Code Logo

Total Downloads Latest Stable Version Latest Stable Version

English | العربية | বাংলা | Bosanski | Deutsch | Español | Français | हिन्दी | Italiano | 日本語 | 한국어 | मराठी | Português | Русский | Kiswahili | தமிழ் | తెలుగు | Türkçe | اردو | Tiếng Việt | 中文

Mise à jour

Si vous effectuez une mise à jour depuis une version précédente, veuillez consulter le Guide de mise à jour pour les changements importants et les étapes de migration.

Introduction

MJML est un langage de balisage spécifiquement conçu pour simplifier le processus de codage d'emails réactifs. Sa syntaxe sémantique garantit facilité et simplicité, tandis que sa vaste bibliothèque de composants standards accélère le développement et réduit la complexité de votre code d'email. Le moteur open-source de MJML génère un HTML réactif et de haute qualité qui respecte les meilleures pratiques. Si vous avez rencontré les frustrations de travailler avec Outlook, ce package est fait pour vous.

Notre implémentation de MJML sert d'enveloppe pour l'API officielle de MJML. Elle permet une compilation pratique de MJML en HTML directement dans PHP, sans avoir besoin de NodeJS. Ce package est idéal pour les applications PHP qui souhaitent intégrer MJML sans le tracas d'installer NodeJS et le CLI MJML.

Exemple

// Sans Laravel
(new MJML)->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// HTML minifié
(new MJML)->minify()->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// Avec Laravel
MJML::render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// Avec Laravel et HTML minifié
MJML::minify()->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);

Installation

  1. Ajoutez d'abord ce qui suit à votre fichier composer.json pour indiquer à notre package de récupérer les binaires corrects pour votre système d'exploitation lors de l'installation de notre package. Les binaires seront téléchargés après que vous ayez exécuté install, update, ou dump-autoload.

    {
        "post-autoload-dump": ["DefectiveCode\\MJML\\PullBinary::all"]
    }

    Le binaire MJML sera obtenu depuis notre CDN et sauvegardé dans le dossier "bin" de ce package lors de l'installation ou de la mise à jour de composer. Assurez-vous que vous avez les binaires nécessaires chargés pour votre environnement local et de production.

    Par défaut, all extraira tous les binaires que nous supportons. Nous recommandons de limiter cela aux systèmes d'exploitation et architectures dont vous avez besoin pour économiser de la bande passante et du temps d'installation. Voici les binaires disponibles.

    Système d'exploitation Architecture Commande post-mise à jour de Composer
    Tous Tous DefectiveCode\MJML\PullBinary::all
    Darwin (MacOS) arm64 DefectiveCode\MJML\PullBinary::darwin-arm64
    Darwin (MacOS) x64 DefectiveCode\MJML\PullBinary::darwin-x64
    Linux (glibc) arm64 DefectiveCode\MJML\PullBinary::linux-arm64
    Linux (glibc) x64 DefectiveCode\MJML\PullBinary::linux-x64
    Linux (musl) arm64 DefectiveCode\MJML\PullBinary::linux-arm64-musl
    Linux (musl) x64 DefectiveCode\MJML\PullBinary::linux-x64-musl

  2. Ensuite, installez le package PHP en exécutant la commande composer suivante :

    composer require defectivecode/mjml

  3. C'est tout ! Si vous utilisez Laravel, notre package s'installera automatiquement en utilisant la découverte de package de Laravel.

Utilisation (Sans Laravel)

Consultez l'utilisation avec Laravel ci-dessous si vous utilisez Laravel.

Rendu de MJML

Pour rendre MJML, il suffit de passer votre chaîne MJML à la méthode render :

use DefectiveCode\MJML\MJML;
 
$html = (new MJML)->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);

Validation de MJML

Pour valider MJML, il suffit de passer votre chaîne MJML à la méthode isValid :

use DefectiveCode\MJML\MJML;
 
$isValid = (new MJML)->isValid(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);

Utilisation (Avec Laravel)

Rendu de MJML

Pour rendre MJML, il suffit de passer votre chaîne MJML à la méthode render sur la façade MJML :

use DefectiveCode\MJML\Facades\MJML;
 
$html = MJML::render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);

Validation de MJML

Pour valider MJML, il suffit de passer votre chaîne MJML à la méthode isValid sur la façade MJML :

use DefectiveCode\MJML\Facades\MJML;
 
$isValid = MJML::isValid(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);

Configuration

Vous pouvez publier le fichier de configuration en utilisant la commande suivante :

php artisan vendor:publish --provider="DefectiveCode\MJML\MJMLServiceProvider"

Cela créera un fichier de configuration mjml.php dans votre dossier config. Toutes les options énumérées dans le fichier de configuration sont passées à l'objet config lorsque vous utilisez la façade MJML.

Configuration

Toutes les options de configuration peuvent être définies en appelant les méthodes suivantes directement sur l'objet MJML.

use DefectiveCode\MJML\MJML;
 
$html = (new MJML)
    ->setMinify(true)
    ->setBeautify(false)
    ->render(
        '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
    );

Notre package suit la même configuration que le package MJML officiel, à l'exception des éléments suivants :

Polices

Notre package utilise les polices suivantes par défaut :

Vous pouvez changer les polices en utilisant les méthodes suivantes :

Commentaires

Les commentaires sont conservés par défaut. Si vous souhaitez supprimer les commentaires, vous pouvez utiliser la méthode removeComments().

Vous pouvez également rétablir removeComments() en appelant la méthode keepComments().

Ignorer les inclusions

Par défaut, notre package ignore les tags mj-include. Cela correspond au comportement par défaut plus sécurisé de MJML 5. Vous pouvez activer les inclusions en appelant ignoreIncludes(false).

Lors de l'activation des inclusions, utilisez filePath(string $path) comme répertoire de base et includePath(string|array|null $path) pour autoriser des répertoires d'inclusion supplémentaires.

Embellir

Notre package embellira le HTML en utilisant js-beautify. MJML 5.2 utilise également js-beautify en interne, mais ce package conserve l'embellissement au niveau de l'enveloppe afin que les beautifyOptions PHP personnalisés continuent de fonctionner. Les options par défaut sont :

Bien que js-beautify utilise le snake_case pour fournir des options, vous devez utiliser le camelCase lorsque vous utilisez notre package. Nous avons fait ce choix pour garder notre package cohérent avec le reste des options de configuration. Notre package convertira automatiquement les options camelCase en snake_case.

Vous pouvez remplacer l'une de ces options en fournissant une configuration valide js-beautify en utilisant les méthodes suivantes :

Minifier

Notre package minifiera la sortie HTML lorsqu'il est activé. La minification effectue les actions suivantes :

Vous pouvez activer ou désactiver la minification en appelant la méthode minify(bool $minify).

Pourquoi une minification basée sur PHP ? MJML 5 n'utilise plus le vieux package vulnérable html-minifier. Ce package conserve toujours la minification en PHP pour préserver le comportement de sortie introduit dans la version 2.x. Si vous avez besoin des options de minification natives htmlnano/cssnano de MJML 5, ouvrez un problème avec la forme d'option requise.

Niveau de validation

Notre package validera le MJML en utilisant le niveau de validation soft par défaut. Vous pouvez changer cela en utilisant la méthode validationLevel(ValidationLevel $validationLevel). Les niveaux de validation suivants sont disponibles :

Chemin de fichier

Notre package utilisera le répertoire . par défaut. Vous pouvez changer cela en appelant la méthode filePath(string $path).

MJML 5 traite filePath comme la base du sandbox d'inclusion. Si les inclusions sont activées, les chemins en dehors de filePath sont refusés à moins qu'ils ne soient explicitement autorisés avec includePath(string|array|null $path).

Jus

Nous ne fournissons aucun options de jus par défaut. Vous pouvez ajouter des options de jus en utilisant les méthodes suivantes :

Directives de Support

Merci d'avoir choisi notre paquet open source ! Veuillez prendre un moment pour consulter ces directives de support. Elles vous aideront à tirer le meilleur parti de notre projet.

Support Axé sur la Communauté

Notre projet open-source est alimenté par notre incroyable communauté. Si vous avez des questions ou avez besoin d'aide, StackOverflow et d'autres ressources en ligne sont vos meilleures options.

Bugs et Priorisation des Fonctionnalités

La réalité de la gestion d'un projet open-source signifie que nous ne pouvons pas traiter tous les bugs ou demandes de fonctionnalités immédiatement. Nous priorisons les problèmes dans l'ordre suivant :

1. Bugs Affectant Nos Produits Payants

Les bugs qui impactent nos produits payants seront toujours notre priorité absolue. Dans certains cas, nous ne traiterons peut-être que les bugs qui nous affectent directement.

2. Demandes de Tirage de la Communauté

Si vous avez identifié un bug et avez une solution, veuillez soumettre une demande de tirage. Après les problèmes affectant nos produits, nous accordons la prochaine priorité la plus élevée à ces corrections pilotées par la communauté. Une fois examinée et approuvée, nous fusionnerons votre solution et créditerons votre contribution.

3. Soutien Financier

Pour les problèmes en dehors des catégories mentionnées, vous pouvez choisir de financer leur résolution. Chaque problème ouvert est lié à un bon de commande où vous pouvez contribuer financièrement. Nous priorisons ces problèmes en fonction du montant du financement fourni.

Contributions de la Communauté

L'open-source prospère lorsque sa communauté est active. Même si vous ne réparez pas de bugs, envisagez de contribuer par des améliorations de code, des mises à jour de documentation, des tutoriels, ou en aidant les autres dans les canaux communautaires. Nous encourageons vivement tout le monde, en tant que communauté, à aider à soutenir le travail open-source.

Pour réitérer, DefectiveCode priorisera les bugs en fonction de leur impact sur nos produits payants, des demandes de tirage de la communauté, et du soutien financier reçu pour les problèmes.

Licence - Licence MIT

Copyright © Defective Code, LLC. Tous droits réservés

La permission est par la présente accordée, gratuitement, à toute personne obtenant une copie de ce logiciel et des fichiers de documentation associés (le "Logiciel"), de traiter le Logiciel sans restriction, y compris sans limitation les droits d'utiliser, de copier, de modifier, de fusionner, de publier, de distribuer, de sous-licencier, et/ou de vendre des copies du Logiciel, et de permettre aux personnes à qui le Logiciel est fourni de le faire, sous réserve des conditions suivantes :

L'avertissement de copyright ci-dessus et cet avis de permission doivent être inclus dans toutes les copies ou portions substantielles du Logiciel.

LE LOGICIEL EST FOURNI "EN L'ÉTAT", SANS GARANTIE D'AUCUNE SORTE, EXPRESSE OU TACITE, Y COMPRIS MAIS SANS S'Y LIMITER AUX GARANTIES DE COMMERCIALITÉ, D'ADAPTATION À UN OBJECTIF PARTICULIER ET DE NON CONTREFAÇON. EN AUCUN CAS, LES AUTEURS OU DÉTENTEURS DE DROITS D'AUTEUR NE POURRONT ÊTRE TENUS RESPONSABLES DE TOUTE RECLAMATION, DOMMAGE OU AUTRE RESPONSABILITÉ, QUE CE SOIT DANS LE CADRE D'UN CONTRAT, DUN DÉLIT OU AUTRE, DÉCOULANT DE, OU EN RELATION AVEC LE LOGICIEL OU L'UTILISATION OU AUTRES TRANSACTIONS DANS LE LOGICIEL.