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

Atualização

Se você está atualizando de uma versão anterior, por favor, consulte o Guia de Atualização para mudanças significativas e etapas de migração.

Introdução

MJML é uma linguagem de marcação especificamente projetada para simplificar o processo de codificação de emails responsivos. Sua sintaxe semântica garante facilidade e simplicidade, enquanto sua vasta biblioteca de componentes padrão acelera o desenvolvimento e reduz a complexidade do seu código de emails. O mecanismo de código aberto do MJML gera HTML de alta qualidade e responsivo que adere às melhores práticas. Se você já experimentou as frustrações de trabalhar com Outlook, este pacote é feito para você.

Nossa implementação do MJML serve como um wrapper para a API oficial do MJML. Ele permite a compilação conveniente do MJML em HTML diretamente dentro do PHP, sem a necessidade de NodeJS. Este pacote é ideal para aplicações PHP que desejam incorporar MJML sem o incômodo de instalar NodeJS e o CLI do MJML.

Exemplo

// Sem Laravel
(new MJML)->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Olá 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>Olá Mundo</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// Com Laravel
MJML::render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Olá Mundo</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// Com Laravel e HTML minificado
MJML::minify()->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Olá Mundo</mj-text></mj-column></mj-section></mj-body></mjml>'
);

Instalação

  1. Primeiro, adicione o seguinte ao seu arquivo composer.json para instruir nosso pacote a baixar os binários corretos para o seu sistema operacional quando nosso pacote for instalado. Os binários serão baixados após você executar install, update ou dump-autoload.

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

    O binário do MJML será obtido de nosso CDN e salvo na pasta "bin" deste pacote durante a instalação ou atualização do composer. Certifique-se de que você tenha os binários necessários carregados tanto para seu ambiente local quanto de produção.

    Por padrão, all irá puxar todos os binários que suportamos. Recomendamos restringir isso aos sistemas operacionais e arquiteturas que você precisa para economizar largura de banda e tempo de instalação. Os seguintes são os binários disponíveis.

    Sistema Operacional Arquitetura Comando Pós-Atualização do 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. Em seguida, instale o pacote PHP executando o seguinte comando do composer:

    composer require defectivecode/mjml

  3. É isso! Se estiver usando Laravel, nosso pacote será instalado automaticamente usando a descoberta de pacotes do Laravel.

Uso (Sem Laravel)

Veja o uso com Laravel abaixo se você estiver usando Laravel.

Renderizando MJML

Para renderizar MJML, basta passar sua string MJML para o método render:

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

Validando MJML

Para validar MJML, basta passar sua string MJML para o método isValid:

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

Uso (Com Laravel)

Renderizando MJML

Para renderizar MJML, basta passar sua string MJML para o render no facade do MJML:

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

Validando MJML

Para validar MJML, basta passar sua string MJML para o método isValid no facade do MJML:

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

Configuração

Você pode publicar o arquivo de configuração usando o seguinte comando:

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

Isso criará um arquivo de configuração mjml.php na sua pasta config. Todas as opções listadas no arquivo de configuração são passadas para o objeto config quando você usa o facade do MJML.

Configuração

Todas as opções de configuração podem ser definidas chamando os seguintes métodos diretamente no objeto MJML.

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

Nosso pacote segue a mesma configuração que o pacote oficial do MJML, exceto pelas seguintes:

Fontes

Nosso pacote usa as seguintes fontes por padrão:

Você pode mudar as fontes usando os seguintes métodos:

Comentários

Comentários são mantidos por padrão. Se você deseja remover comentários, pode usar o método removeComments().

Você também pode reverter o removeComments() chamando o método keepComments().

Ignorar Includes

Por padrão, nosso pacote incluirá quaisquer mj-include tags. Você pode ajustar comportamento chamando o método ignoreIncludes(bool $ignore).

Embelezar

Nosso pacote embelezará o HTML usando js-beautify com as seguintes opções padrão:

Embora o js-beautify use snake_case para fornecer opções, você deve usar camelCase ao usar nosso pacote. Nós fizemos essa escolha para manter nosso pacote consistente com o resto das opções de configuração. Nosso pacote automaticamente converterá as opções camelCase para snake_case.

Você pode substituir qualquer uma dessas opções fornecendo uma configuração válida do js-beautify usando os seguintes métodos:

Minificar

Nosso pacote irá minificar a saída HTML quando ativado. A minificação realiza o seguinte:

Você pode ativar ou desativar a minificação chamando o método minify(bool $minify).

Por que minificação baseada em PHP? O pacote oficial do MJML usa html-minifier para minificação, que possui uma conhecida vulnerabilidade ReDoS (CVE-2022-37620) sem correção disponível já que o pacote não está sendo mantido. Para evitar empacotar dependências vulneráveis, movemos a minificação para PHP usando uma implementação leve e segura.

Nível de Validação

Nosso pacote irá validar o MJML usando o nível de validação soft por padrão. Você pode alterar isso usando o método validationLevel(ValidationLevel $validationLevel). Os seguintes níveis de validação estão disponíveis:

Caminho do Arquivo

Nosso pacote usará o diretório . por padrão. Você pode alterar isso chamando o método filePath(string $path).

Juice

Não fornecemos opções de juice por padrão. Você pode adicionar opções juice usando os seguintes métodos:

Diretrizes de Suporte

Obrigado por escolher nosso pacote de código aberto! Por favor, reserve um momento para conferir estas diretrizes de suporte. Elas ajudarão você a aproveitar ao máximo nosso projeto.

Suporte Direcionado pela Comunidade

Nosso projeto de código aberto é alimentado por nossa incrível comunidade. Se você tiver dúvidas ou precisar de assistência, StackOverflow e outros recursos online são suas melhores opções.

Erros e Priorização de Recursos

A realidade de gerenciar um projeto de código aberto significa que não podemos abordar imediatamente todos os erros ou solicitações de recursos relatados. Priorizamos as questões na seguinte ordem:

1. Erros que Afetam Nossos Produtos Pagos

Erros que impactam nossos produtos pagos serão sempre nossa maior prioridade. Em alguns casos, podemos abordar apenas erros que nos afetam diretamente.

2. Pull Requests da Comunidade

Se você identificou um erro e tem uma solução, por favor, envie um pull request. Após as questões que afetam nossos produtos, damos a próxima maior prioridade a essas correções impulsionadas pela comunidade. Uma vez revisada e aprovada, iremos mesclar sua solução e creditar sua contribuição.

3. Apoio Financeiro

Para questões fora das categorias mencionadas, você pode optar por financiar sua resolução. Cada problema em aberto está vinculado a um formulário de pedido onde você pode contribuir financeiramente. Priorizamos essas questões com base no valor do financiamento fornecido.

Contribuições da Comunidade

O código aberto prospera quando sua comunidade é ativa. Mesmo que você não esteja corrigindo erros, considere contribuir com melhorias de código, atualizações de documentação, tutoriais ou ajudando outros em canais da comunidade. Incentivamos fortemente todos, como comunidade, a ajudar a apoiar o trabalho de código aberto.

Para reiterar, a DefectiveCode priorizará erros com base em como eles impactam nossos produtos pagos, pull requests da comunidade e o apoio financeiro recebido para as questões.

Licença - Licença MIT

Copyright © Defective Code, LLC. Todos os direitos reservados

A permissão é concedida, sem qualquer custo, a qualquer pessoa que obter uma cópia deste software e dos arquivos de documentação associados (o "Software"), para lidar com o Software sem restrições, incluindo, sem limitação, os direitos de usar, copiar, modificar, fundir, publicar, distribuir, sublicenciar e/ou vender cópias do Software, e para permitir que pessoas a quem o Software é fornecido façam o mesmo, sujeito às seguintes condições:

O aviso de copyright acima e este aviso de permissão devem ser incluídos em todas as cópias ou porções substanciais do Software.

O SOFTWARE É FORNECIDO "COMO ESTÁ", SEM GARANTIA DE QUALQUER TIPO, EXPRESSA OU IMPLÍCITA, INCLUINDO, MAS NÃO SE LIMITANDO A GARANTIAS DE COMERCIALIZAÇÃO, ADEQUAÇÃO A UM FIM ESPECÍFICO E NÃO INFRAÇÃO. EM NENHUM CASO OS AUTORES OU DETENTORES DO DIREITO AUTORAL SERÃO RESPONSÁVEIS POR QUALQUER RECLAMAÇÃO, DANOS OU OUTRA RESPONSABILIDADE, SEJA EM AÇÃO DE CONTRATO, DELITO OU DE OUTRA FORMA, DECORRENTES DE, EM DECORRÊNCIA OU EM CONEXÃO COM O SOFTWARE OU O USO OU OUTRAS NEGOCIAÇÕES NO SOFTWARE.