serverless

Função para converter HTML para PDF usando PHP e wkhtmltopdf no AWS Lambda

Aqui na TreinaWeb sempre usamos o wkhtmltopdf para a conversão de HTML para PDF. É a base da geração dos nossos certificados, ementas, relatórios administrativos etc.

Um problema que sempre tivemos foi com o manejo do binário do wkhtmltopdf. Tínhamos que tê-lo disponível em qualquer instância EC2 que fôssemos utilizar. Quando uma nova versão era lançada, tínhamos que compilá-lo do zero novamente em todas as instâncias que o utilizassem, até mesmo localmente no ambiente de desenvolvimento. Para além disso, tínhamos com frequência alguns erros na geração do PDF por causa de algum pico de uso da CPU por conta dele.

PHP Básico
Curso de PHP Básico
CONHEÇA O CURSO

Resolvemos os nossos problemas de uma forma bem tranquila e altamente escalável usando Serverless. Fizemos o deploy de uma função no AWS Lambda especializada na conversão de HTML para PDF. E, para o nosso caso de uso, tudo o que precisávamos era receber o HTML e então retornar um Base64 do PDF. Notamos, também, uma melhor performance na geração dos PDFs.

Se você não conhece o que é Serverless, sugiro a leitura do artigo: Serverless: uma introdução.

E, para que você consiga acompanhar como o deploy da função que converte o HTML para PDF foi feito, é necessário que você tenha lido o artigo: Aplicação Serverless desenvolvida em PHP usando AWS Lambda.

O que utilizaremos daqui pra frente:

  • PHP: essa maravilhosa linguagem de programação.
  • Bref: ferramenta que faz com que seja simples o deploy de aplicações PHP Serverless.
  • Serverless Framework: framework completo para teste e deploy de aplicações nas principais plataformas Serverless do mercado.
  • AWS Lambda: onde faremos o deploy da função.

Como funciona a conversão do HTML para PDF?

O sistema de layers para o Lambda lançado pela AWS no ano passado mudou o jogo completamente. Com ele é possível que uma função use qualquer binário. É possível rodar até Cobol no AWS Lambda. E foi ele que permitiu que agora pudéssemos criar uma função que use o binário do wkhtmltopdf para a conversão de HTML para PDF. Não obstante, ele também é o responsável por podermos usar o PHP no AWS Lambda.

O que inicialmente tivemos que fazer foi compilar o wkhtmltopdf manualmente na nossa máquina para que pudéssemos criar um Layer dele no AWS Lambda pra ser linkado com a função. E, para isso, o artigo Compiling wkhtmltopdf for use inside an AWS Lambda function with Bref is easier than you’d think deixou tudo bem detalhado sobre como isso pode ser feito.

O código completo da função você encontra nesse repositório: KennedyTedesco/wkhtmltopdf-lambda-php. Mas eu vou passar pelos principais pontos aqui nesse artigo.

Primeiro de tudo, vamos avaliar o arquivo serverless.yml:

service: wkhtmltopdf

provider:
    name: aws
    region: sa-east-1
    runtime: provided
    stage: prod
    memorySize: 1024
    timeout: 60

plugins:
    - ./vendor/bref/bref

functions:
    html-to-base64-pdf:
        handler: index.php
        description: 'HTML to Base64 PDF'
        layers:
            - ${bref:layer.php-73}
            - 'arn:aws:lambda:sa-east-1:391960246434:layer:wkhtmltopdf-bin:1'

Veja em layers que temos declarado arn:aws:lambda:sa-east-1:391960246434:layer:wkhtmltopdf-bin:1, esse é o layer que compilamos manualmente e subimos para a AWS. É o layer do binário do wkhtmltopdf. É o que faz ele ficar disponível no diretório /opt/wkhtmltopdf.

PHP Intermediário
Curso de PHP Intermediário
CONHEÇA O CURSO

E a função propriamente dita é pura e simplesmente isso:

<?php

declare(strict_types=1);

require __DIR__.'/vendor/autoload.php';

use Knp\Snappy\Pdf;

lambda(static function (array $event) {
    $pdf = new Pdf('/opt/wkhtmltopdf');

    $options = [
        'encoding' => 'utf-8',
        'page-size' => 'A4',
        'margin-bottom' => 0,
        'margin-left' => 0,
        'margin-top' => 0,
        'margin-right' => 0,
        'disable-smart-shrinking' => true,
        'disable-javascript' => true,
    ];

    if (isset($event['options'])) {
        $options = \array_merge(
            $options,
            \json_decode($event['options'], true)
        );
    }

    $output = $pdf->getOutputFromHtml($event['html'], $options);

    if (empty($output)) {
        throw new \RuntimeException('Unable to generate the html');
    }

    return \base64_encode($output);
});

Usamos a library snappy que abstrai o uso do wkhtmltopdf. No mais, apenas recebemos o HTML e algumas opções para a geração do PDF, executamos o binário e retornamos um base64 do PDF gerado.

Se você tiver seguido o artigo Aplicação Serverless desenvolvida em PHP usando AWS Lambda, para fazer o deploy dessa função na sua infra da AWS, tudo o que você precisará é clonar esse projeto que disponibilizei no Github e então executar:

$ composer install --optimize-autoloader --no-dev

Vai baixar as dependências do projeto. Por fim:

$ serverless deploy

Fará o deploy da função no AWS Lambda.

E como a função é usada nas aplicações?

Não tivemos a necessidade de expor um endpoint do API Gateway para intermediar a execução da função (isso seria perfeitamente possível, principalmente se o serviço fosse uma API de acesso público). Fazemos a invocação direta dela pela SDK da AWS. E a SDK tem implementação para as principais linguagens. No caso do PHP seria algo como:

$lambda = new AwsLambdaClient([
  'version' => 'latest',
  'region' => 'sa-east-1',
  'credentials' => [
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
  ],
]);

$result = $lambda->invoke([
  'FunctionName' => 'wkhtmltopdf-prod-html-to-base64-pdf',
  'InvocationType' => 'RequestResponse',
  'LogType' => 'None',
  'Payload' => \json_encode([
    'html' => '<html>...',
  ]),
]);

$result = \json_decode($result->get('Payload')->getContents(), true); // base64 pdf

E se eu precisar gerar grandes arquivos PDF?

Se o seu caso de uso envolve gerar arquivos PDF de mais de 6MB, esse método da invocação direta não vai ser a melhor opção por causa do limite do tamanho do payload de retorno do AWS Lambda. Nesse caso, a melhor opção é você mudar a estratégia e, ao invés de retornar um base64 do PDF, você passar a salvá-lo em um bucket no S3. E a sua função retornaria um body com o link para acesso ao arquivo, por exemplo:

{
    "url": "https://seu-bucket.s3-sa-east-1.amazonaws.com/pdf/nome-do-arquivo.pdf"  
}

Inclusive, se for necessário, é possível até mesmo ter um bucket para receber os arquivos HTML que precisam ser convertidos e então a função seria invocada para convertê-los e então salvá-los em outro bucket de destino. Algo como:

  • O arquivo HTML é salvo no bucket arquivos-html, esse bucket está configurado para disparar um evento sempre que um novo arquivo é upado, evento esse que vai executar a função que criamos;
  • A função é executada, o PDF é salvo no bucket arquivos-pdf e a função retorna um body com o link para acesso ao arquivo PDF.
PHP Avançado
Curso de PHP Avançado
CONHEÇA O CURSO

As possibilidades são muitas, ademais, na AWS tudo se integra por eventos.

Até a próxima!

E-mails responsivos com a linguagem de marcação MJML

O MJML é um framework e linguagem de marcação para a criação de e-mails responsivos. Ele simplifica a escrita com uma linguagem simples e concisa (a Mailjet Markup Language) que é convertida para HTML.

Se você ainda não teve a oportunidade de ver o código HTML de um e-mail responsivo, costuma ser uma coisa muito bagunçada, pois os estilos são aplicados de forma inline e usa-se tabelas para a sua estruturação. Isso é feito para fazer com que o e-mail funcione no maior número possível de dispositivos.

HTML5 e CSS3 - Desenvolvimento web Básico
Curso de HTML5 e CSS3 - Desenvolvimento web Básico
CONHEÇA O CURSO

Para você ter ideia, esse trecho de MJML de um dos e-mails que enviamos na TreinaWeb:

<mj-section>
  <mj-column full-width="full-width">
    <mj-image src="https://d2knvm16wkt3ia.cloudfront.net/og/java-jax-ws-rs.png" href="https://www.treinaweb.com.br" />
    <mj-text align="center" font-size="35px" line-height="1.1"> <a href="https://www.treinaweb.com.br">Python - Collections</a> </mj-text>
    <mj-text align="justify"> Estruturas de dados são pontos cruciais em qualquer linguagem de programação. Sendo que em cada uma, podem ser implementadas de uma forma diferente. Por isso que conhecer as particularidades e recursos da linguagem em relação a estrutura de
      dados, é imprescindível a qualquer um que queira dominar uma linguagem. </mj-text>
    <mj-text align="justify"> Neste ponto o Python não fica atrás, fornecendo estruturas comuns em outras linguagens, bem como estruturas exclusivas. Neste curso veremos como manipulá-las e conheceremos os métodos de cada estrutura disponível nesta linguagem. </mj-text>
    <mj-button width="100%" background-color="#54CF8A" href="https://www.treinaweb.com.br">SAIBA MAIS SOBRE O CURSO</mj-button>
  </mj-column>
</mj-section>

É convertido para esse HTML:

<div style="Margin:0px auto;max-width:600px;">
    <table align="center" border="0" cellpadding="0" cellspacing="0" role="presentation" style="width:100%;">
        <tbody>
            <tr>
                <td style="direction:ltr;font-size:0px;padding:20px 0;text-align:center;vertical-align:top;">
                    <div class="mj-column-per-100 outlook-group-fix" style="font-size:13px;text-align:left;direction:ltr;display:inline-block;vertical-align:top;width:100%;">
                        <table border="0" cellpadding="0" cellspacing="0" role="presentation" style="vertical-align:top;" width="100%">
                            <tr>
                                <td align="center" style="font-size:0px;padding:10px 25px;word-break:break-word;">
                                    <table border="0" cellpadding="0" cellspacing="0" role="presentation" style="border-collapse:collapse;border-spacing:0px;">
                                        <tbody>
                                            <tr>
                                                <td style="width:550px;">
                                                    <a href="https://www.treinaweb.com.br" target="_blank" style="color: #444444;">
                                                        <img height="auto" src="https://d2knvm16wkt3ia.cloudfront.net/og/java-jax-ws-rs.png" style="border:0;display:block;outline:none;text-decoration:none;height:auto;width:100%;" width="550">
                                                    </a>
                                                </td>
                                            </tr>
                                        </tbody>
                                    </table>
                                </td>
                            </tr>
                            <tr>
                                <td align="center" style="font-size:0px;padding:10px 25px;word-break:break-word;">
                                    <div style="font-family:Helvetica, arial, sans-serif;font-size:35px;line-height:1.1;text-align:center;color:#444444;">
                                        <a href="https://www.treinaweb.com.br" style="color: #444444;">Python - Collections</a>
                                    </div>
                                </td>
                            </tr>
                            <tr>
                                <td align="justify" style="font-size:0px;padding:10px 25px;word-break:break-word;">
                                    <div style="font-family:Helvetica, arial, sans-serif;font-size:16px;line-height:24px;text-align:justify;color:#444444;"> Estruturas de dados são pontos cruciais em qualquer linguagem de programação. Sendo que em cada uma, podem ser implementadas de uma forma diferente. Por isso que conhecer as particularidades e recursos da linguagem em relação a estrutura de dados, é imprescindível a qualquer um que queira dominar uma linguagem. </div>
                                </td>
                            </tr>
                            <tr>
                                <td align="justify" style="font-size:0px;padding:10px 25px;word-break:break-word;">
                                    <div style="font-family:Helvetica, arial, sans-serif;font-size:16px;line-height:24px;text-align:justify;color:#444444;"> Neste ponto o Python não fica atrás, fornecendo estruturas comuns em outras linguagens, bem como estruturas exclusivas. Neste curso veremos como manipulá-las e conheceremos os métodos de cada estrutura disponível nesta linguagem. </div>
                                </td>
                            </tr>
                            <tr>
                                <td align="center" vertical-align="middle" style="font-size:0px;padding:10px 25px;word-break:break-word;">
                                    <table border="0" cellpadding="0" cellspacing="0" role="presentation" style="border-collapse:separate;width:100%;line-height:100%;">
                                        <tr>
                                            <td align="center" bgcolor="#54CF8A" role="presentation" style="border:none;border-radius:3px;cursor:auto;padding:10px 25px;background:#54CF8A;" valign="middle">
                                                <a href="https://www.treinaweb.com.br" style="background: #54CF8A; color: #ffffff; font-family: Helvetica, arial, sans-serif; font-size: 13px; font-weight: normal; line-height: 120%; Margin: 0; text-decoration: none; text-transform: none;" target="_blank">
              SAIBA MAIS SOBRE O CURSO
            </a>
                                            </td>
                                        </tr>
                                    </table>
                                </td>
                            </tr>
                        </table>
                    </div>
                </td>
            </tr>
        </tbody>
    </table>
</div>

Através desse exemplo já dá para você notar como o MJML ajuda na escrita e na clareza do que está sendo escrito.

E para escrever um e-mail usando MJML?

O intuito desse artigo não é o de masterizar o uso do MJML ou de te ensinar a passo a passo a sintaxe dessa linguagem de marcação. O MJML possui uma completa documentação que mostra passo a passo tudo o que pode ser desenvolvido com ele.

A ideia aqui é te dar o caminho da pedra, te apresentar os recursos disponíveis, o que você pode usar e te mostrar como converter o MJML para HTML em seu projeto.

A documentação:

A documentação do MJML não deve ser ignorada. Portanto, é um ótimo começo.

Try it live:

Você pode visualizar o resultado enquanto escreve no editor online disponível no site do MJML.

Templates:

O site oficial tem uma área com alguns templates para que você possa visualizar e tirar algumas ideias na hora de construir os seus e-mails.

A própria documentação fornece um template básico para você começar por ele, caso deseje.

E como vou converter o MJML para HTML?

O MJML precisa ser convertido para HTML para que então os seus e-mails sejam enviados. Há algumas formas de atingir esse objetivo. Vamos começar pelas manuais:

1) É possível converter MJML para HTML pelo editor online oficial.

2) É possível converter através da aplicação desktop disponível para Linux, macOS e Windows.

Agora, se dinamicamente/programaticamente você constrói o MJML e precisa convertê-lo “on the fly” antes dos envios, existem algumas opções:

1) Se registrar na API Oficial do MJML para que você receba uma credencial que te permitirá fazer uma requisição na API para converter MJML para HTML. É de grátis.

curl \ 
-X POST "https://api.mjml.io/v1/render" \ 
--user "APPLICATION-ID:SECRET-KEY" \ 
-d '{ 
"mjml":"<mjml><mj-body><mj-container><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-container></mj-body></mjml>" 
}'

2) O MJML é open-source e escrito em JavaScript. Ou seja, você próprio pode criar a sua API em NodeJS para a conversão do MJML para HTML. Veja no Github.

Como usamos o MJML na TreinaWeb

Na TreinaWeb usamos uma abordagem Serverless para essa conversão. Você não sabe o que é Serverless? Recomendo a leitura do artigo: Serverless: uma introdução.

Criamos uma função e fizemos o deploy dela na AWS Lambda, pois é na AWS onde administramos toda a nossa infraestrutura.

O código-fonte dessa função e do template do Serverless Framework para deploy na AWS, você encontra nesse repositório: KennedyTedesco/mjml-lambda.

Node.js Completo
Curso de Node.js Completo
CONHEÇA O CURSO

A função é extremamente simples, ela apenas invoca o código do MJML para realizar a conversão:

import mjml2html from 'mjml';

export async function convert(event, context, callback) {
  return mjml2html(event.mjml, {
      beautify: true,
      minify: true,
      keepComments: false,
      validationLevel: 'skip'
  });
}

Uma vez que a lambda está disponível para uso, a invocamos em um de nossos sitemas usando a SDK da AWS para PHP. Uma possível forma de atingir esse objetivo usando o PHP:

$lambda = new \Aws\Lambda\LambdaClient([
    'version' => 'latest',
    'region' => 'us-east-1',
]);

$result = $lambda->invoke([
    'FunctionName' => 'mjml-prod-to-html',
    'InvocationType' => 'RequestResponse',
    'LogType' => 'None',
    'Payload' => json_encode(['mjml' => '<mjml>...',]),
]);

$result = json_decode($result->get('Payload')->getContents(), true);

$html = $result['html']; // O HTML convertido

No entanto, se fosse necessário expor essa função na Web para que qualquer um utilizasse, poderíamos usar o API Gateway na “frente” da lambda.

Dessa forma conseguimos manter o template dos nossos e-mails bem fáceis de serem desenvolvidos e alterados, além de que trazemos para a nossa infraestrutura a responsabilidade de fazer a conversão, para não ter que depender de um serviço de terceiro (a API BETA do MJML).

Espero que o MJML ajude a sua equipe a produzir lindos e-mails responsivos. Até a próxima!