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, veja o Guia de Atualização para mudanças importantes e etapas de migração.

Introdução

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

Nossa implementação do MJML serve como uma camada para a API oficial do MJML. Ela permite a compilação conveniente do MJML em HTML diretamente no PHP, sem a necessidade de NodeJS. Este pacote é ideal para aplicações PHP que desejam incorporar o MJML sem a complicação de instalar o NodeJS e o CLI do MJML.

Exemplo

// Sem 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 Minificado
(new MJML)->minify()->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// Com Laravel
MJML::render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</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>Hello World</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 buscar os binários corretos para 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 para os seus ambientes local e de produção.

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

    Sistema Operacional Arquitetura Comando de 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 o 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, simplesmente passe sua string MJML ao método render:

use DefectiveCode\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>'
);

Validando MJML

Para validar MJML, simplesmente passe sua string MJML ao método isValid:

use DefectiveCode\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>'
);

Uso (Com Laravel)

Renderizando MJML

Para renderizar MJML, simplesmente passe sua string MJML ao render na fachada 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>'
);

Validando MJML

Para validar MJML, simplesmente passe sua string MJML ao método isValid na fachada 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>'
);

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 a fachada 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>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
    );

Nosso pacote segue a mesma configuração do 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

Os 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 Inclusões

Por padrão, nosso pacote ignora as tags mj-include. Isso corresponde ao padrão mais seguro do MJML 5. Você pode habilitar inclusões chamando ignoreIncludes(false).

Ao habilitar inclusões, use filePath(string $path) como o diretório base e includePath(string|array|null $path) para permitir diretórios de inclusão adicionais.

Embelezar

Nosso pacote embelezará o HTML usando js-beautify. O MJML 5.2 também usa js-beautify internamente, mas este pacote mantém a embelezamento em nível de wrapper para que opções de beautifyOptions personalizadas em PHP continuem a funcionar. As opções padrão são:

Enquanto o js-beautify usa snake_case para fornecer opções, você deve usar camelCase ao usar nosso pacote. Fizemos essa escolha para manter nosso pacote consistente com o restante das opções de configuração. Nosso pacote irá automaticamente converter as opções camelCase em 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 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 MJML 5 não usa mais o velho e vulnerável pacote html-minifier. Este pacote ainda mantém a minificação em PHP para preservar o comportamento de saída introduzido na versão 2.x. Se você precisar das opções de minificação nativas htmlnano/cssnano do MJML 5, abra um problema com a forma da opção necessária.

Nível de Validação

Nosso pacote validará o MJML usando o nível de validação soft por padrão. Você pode mudar 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 mudar isso chamando o método filePath(string $path).

O MJML 5 trata filePath como o base do sandbox de inclusão. Se as inclusões estiverem habilitadas, os caminhos fora de filePath são negados a menos que sejam explicitamente autorizados com includePath(string|array|null $path).

Juice

Nós não fornecemos nenhuma opção de juice por padrão. Você pode adicionar opções de 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.