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 | 中文

Actualización

Si está actualizando desde una versión anterior, consulte la Guía de Actualización para cambios importantes y pasos de migración.

Introducción

MJML es un lenguaje de marcado específicamente diseñado para simplificar el proceso de codificación de correos electrónicos responsivos. Su sintaxis semántica garantiza facilidad y simplicidad, mientras que su extensa biblioteca de componentes estándar acelera el desarrollo y reduce la complejidad de su base de código de correos electrónicos. El motor de código abierto de MJML genera HTML responsivo de alta calidad que se adhiere a las mejores prácticas. Si ha experimentado las frustraciones de trabajar con Outlook, este paquete está diseñado para usted.

Nuestra implementación de MJML sirve como un envoltorio para la API oficial de MJML. Permite una compilación conveniente de MJML en HTML directamente dentro de PHP, sin necesidad de NodeJS. Este paquete es ideal para aplicaciones PHP que desean incorporar MJML sin la molestia de instalar NodeJS y la CLI de MJML.

Ejemplo

// Sin Laravel
(new MJML)->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hola Mundo</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// HTML minificado
(new MJML)->minify()->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hola Mundo</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// Con Laravel
MJML::render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hola Mundo</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// Con Laravel y HTML minificado
MJML::minify()->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hola Mundo</mj-text></mj-column></mj-section></mj-body></mjml>'
);

Instalación

  1. Primero, agregue lo siguiente a su archivo composer.json para instruir a nuestro paquete a obtener los binarios correctos para su sistema operativo cuando se instale nuestro paquete. Los binarios se descargarán después de que ejecute install, update o dump-autoload.

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

    El binario de MJML se obtendrá de nuestro CDN y se guardará en la carpeta "bin" de este paquete durante la instalación o actualización de composer. Asegúrese de que tenga los binarios necesarios cargados tanto para su entorno local como de producción.

    Por defecto, all obtendrá todos los binarios que soportamos. Recomendamos limitar esto a los sistemas operativos y arquitecturas que necesita para ahorrar en ancho de banda y tiempos de instalación. Los siguientes son los binarios disponibles.

    Sistema Operativo Arquitectura Comando Post Actualización de Composer
    Todos Todos 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. A continuación, instale el paquete de PHP ejecutando el siguiente comando de composer:

    composer require defectivecode/mjml

  3. ¡Eso es todo! Si está utilizando Laravel, nuestro paquete se instalará automáticamente utilizando el descubrimiento de paquetes de Laravel.

Uso (Sin Laravel)

Consulte el uso con Laravel a continuación si está utilizando Laravel.

Renderizando MJML

Para renderizar MJML, simplemente pase su cadena MJML al método render:

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

Validando MJML

Para validar MJML, simplemente pase su cadena MJML al método isValid:

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

Uso (Con Laravel)

Renderizando MJML

Para renderizar MJML, simplemente pase su cadena MJML al método render en la fachada de MJML:

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

Validando MJML

Para validar MJML, simplemente pase su cadena MJML al método isValid en la fachada de MJML:

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

Configuración

Puede publicar el archivo de configuración utilizando el siguiente comando:

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

Esto creará un archivo de configuración mjml.php en su carpeta config. Todas las opciones listadas en el archivo de configuración se pasan al objeto config cuando usa la fachada de MJML.

Configuración

Todas las opciones de configuración se pueden establecer llamando a los siguientes métodos directamente en el objeto MJML.

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

Nuestro paquete sigue la misma configuración que el paquete oficial de MJML, excepto por lo siguiente:

Fuentes

Nuestro paquete utiliza las siguientes fuentes por defecto:

Puede cambiar las fuentes utilizando los siguientes métodos:

Comentarios

Los comentarios se mantienen por defecto. Si desea eliminar los comentarios, puede usar el método removeComments().

También puede revertir removeComments() llamando al método keepComments().

Ignorar Includes

Por defecto, nuestro paquete ignora las etiquetas mj-include. Esto coincide con el valor predeterminado más seguro de MJML 5. Puede habilitar los includes llamando a ignoreIncludes(false).

Al habilitar los includes, use filePath(string $path) como el directorio base y includePath(string|array|null $path) para permitir directorios de inclusión adicionales.

Beautify

Nuestro paquete embellecerá el HTML utilizando js-beautify. MJML 5.2 también utiliza js-beautify internamente, pero este paquete mantiene la embellecimiento a nivel de envoltorio para que las beautifyOptions de PHP personalizadas continúen funcionando. Las opciones predeterminadas son:

Aunque js-beautify utiliza snake_case para proporcionar opciones, debe usar camelCase al usar nuestro paquete. Hicimos esta elección para mantener nuestro paquete consistente con el resto de las opciones de configuración. Nuestro paquete convertirá automáticamente las opciones camelCase a snake_case.

Puede sobrescribir cualquiera de estas opciones proporcionando una configuración válida de js-beautify utilizando los siguientes métodos:

Minify

Nuestro paquete minificará la salida HTML cuando esté habilitado. La minificación realiza lo siguiente:

Puede habilitar o deshabilitar la minificación llamando al método minify(bool $minify).

¿Por qué minificación basada en PHP? MJML 5 ya no utiliza el antiguo paquete vulnerable html-minifier. Este paquete aún mantiene la minificación en PHP para preservar el comportamiento de salida introducido en la versión 2.x. Si necesita las opciones nativas de minificación htmlnano/cssnano de MJML 5, abra un problema con la forma de opción requerida.

Nivel de Validación

Nuestro paquete validará el MJML utilizando el nivel de validación soft por defecto. Puede cambiar esto utilizando el método validationLevel(ValidationLevel $validationLevel). Los siguientes niveles de validación están disponibles:

Ruta del Archivo

Nuestro paquete utilizará el directorio . por defecto. Puede cambiar esto llamando al método filePath(string $path).

MJML 5 trata filePath como la base del sandbox de inclusión. Si los includes están habilitados, las rutas fuera de filePath están denegadas a menos que sean explícitamente permitidas con includePath(string|array|null $path).

Juice

No proporcionamos ninguna opciones de juice por defecto. Puede agregar opciones de juice utilizando los siguientes métodos:

Directrices de Soporte

¡Gracias por elegir nuestro paquete de código abierto! Tómate un momento para revisar estas directrices de soporte. Te ayudarán a sacar el máximo provecho de nuestro proyecto.

Soporte Impulsado por la Comunidad

Nuestro proyecto de código abierto es impulsado por nuestra increíble comunidad. Si tienes preguntas o necesitas asistencia, StackOverflow y otros recursos en línea son tus mejores opciones.

Errores y Priorización de Funciones

La realidad de gestionar un proyecto de código abierto significa que no podemos abordar cada error reportado o solicitud de función de inmediato. Priorizamos los problemas en el siguiente orden:

1. Errores que Afectan Nuestros Productos de Pago

Los errores que impactan nuestros productos de pago siempre serán nuestra máxima prioridad. En algunos casos, solo abordaremos los errores que nos afectan directamente.

2. Solicitudes de Extracción de la Comunidad

Si has identificado un error y tienes una solución, por favor envía una solicitud de extracción. Después de los problemas que afectan a nuestros productos, damos la siguiente mayor prioridad a estas soluciones impulsadas por la comunidad. Una vez revisada y aprobada, integraremos tu solución y daremos crédito a tu contribución.

3. Apoyo Financiero

Para problemas fuera de las categorías mencionadas, puedes optar por financiar su resolución. Cada problema abierto está vinculado a un formulario de pedido donde puedes contribuir financieramente. Priorizamos estos problemas según la cantidad de financiamiento proporcionada.

Contribuciones de la Comunidad

El código abierto prospera cuando su comunidad está activa. Incluso si no estás solucionando errores, considera contribuir a través de mejoras de código, actualizaciones de documentación, tutoriales o asistiendo a otros en los canales de la comunidad. Animamos encarecidamente a todos, como comunidad, a ayudar a apoyar el trabajo de código abierto.

Para reiterar, DefectiveCode priorizará los errores en función de cómo impactan a nuestros productos de pago, las solicitudes de extracción de la comunidad y el apoyo financiero recibido para los problemas.

Licencia - Licencia MIT

Copyright © Defective Code, LLC. Todos los derechos reservados

Por la presente se otorga permiso, de forma gratuita, a cualquier persona que obtenga una copia de este software y los archivos de documentación asociados (el "Software"), para tratar el Software sin restricciones, incluyendo sin limitación los derechos a usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del Software, y a permitir a las personas a las que se les proporciona el Software hacerlo, sujeto a las siguientes condiciones:

La mención de copyright anterior y esta nota de permiso deberán incluirse en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUYENDO PERO NO LIMITÁNDOSE A LAS GARANTÍAS DE COMERCIALIZABILIDAD, ADECUACIÓN PARA UN PROPÓSITO PARTICULAR Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE NINGUNA RECLAMACIÓN, DAÑO O OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE OTRA MANERA, QUE SURJA DE, O EN CONEXIÓN CON EL SOFTWARE O EL USO O OTRAS NEGOCIACIONES EN EL SOFTWARE.