====== Mail com Laravel ======

===== Introdução =====

**Laravel** provê uma //API// construida sobre a biblioteca //SwiftMailer// com //drivers// para **STMP**, **Mailgun**, **SparkPost**, **Amazon SES**, funções **PHP's mail** e **sendmail**, permitindo rapidamente implementar o envio de e-mail, seja localmente, quer seja por serviços em nuvem.

===== Pré-requisitos =====

A API baseada nos drives Mailgun e SparkPost são geralmente mais simples e rápidos que os serviços SMTP. Se possível, deve-se usar um desses drivers. Todos os driver da API requerem a biblioteca **Guzzle HTTP**, que pode ser instalada via gerenciador de pacotes //Composer//. 

> composer require guzzlehttp/guzzle

==== Mailgun Driver ====

Para usar o Driver Mailgun, deve-se primeiramente instalar o Guzzle, então, atribui-se a opção ''driver'' no arquivo de configuração ''config/mail.php'' para ''mailgun''. Em seguida, deve-se verificar se o arquivo de configuração ''config/serveces.php'' contêm as seguintes opções:

> 'mailgun' => [
>    'domain' => 'your-mailgun-domain',
>    'secret' => 'your-mailgun-key',
> ],

==== SparkPost Driver ====

Para usar o Driver SparkPost, deve-se primeiramente instalar o Guzzle, então, atribui-se a opção ''driver'' no arquivo de configuração ''config/mail.php'' para ''sparkpost''  Em seguida, deve-se verificar se o arquivo de configuração ''config/serveces.php'' contêm as seguintes opções:

>'sparkpost' => [
>    'secret' => 'your-sparkpost-key',
>],

==== SES Driver ====

Para usar o Driver Amazon SES, deve-se primeiramente instalar o ''Amazon AWS SDK'' para PHP. Para isso, deve-se adicionar a linha de código a seguir no arquivo ''composer.json'' na seção ''require'' e executar o comando ''composer update'':

> "aws/aws-sdk-php": "~3.0"

Em seguida, atribui-se a opção ''driver'' no arquivo de configuração ''config/mail.php'' para ''ses'' e verifica-se o arquivo de configuração ''config/serveces.php'' para assegurar se o mesmo contêm as seguintes opções:

>'ses' => [
>    'key' => 'your-ses-key',
>    'secret' => 'your-ses-secret',
>    'region' => 'ses-region',
>],

===== Gerando Mailables =====

Em Laravel, cada tipo de email enviado pela aplicação é representada como uma classe ''mailable''. Essa classe está armazenada no diretório ''app/Mail''. Para criar um //mailable//, pode-se usar o comando ''make:mail'':

> php artisan make:mail OrderShipped

===== Escrevendo Mailables =====

Toda a configuração de uma classe //mailable// é feito no método ''build''. Com este método, pode-se chamar vários outros métodos como ''from'', ''subject'', ''view'' e ''attach'' para configurar o email.

==== Configurando o Sender ====

=== Usando o método from ===

Há duas formar de configurar o //sender//. Primeiramente, pode-se usar o método ''from'' com o método ''build'' da classe //mailable//:


> public function build()
> {
>     return $this->from('example@example.com')
>                 ->view('emails.orders.shipped');
> }

=== Usando um endereço from global ===

Toda via, se a aplicação usa um mesmo endereço remetente para qualquer envio, pode-se tornar custoso chamar o método from em cada classe //mailable//. Contudo, pode-se especificar um endereço remetente global no arquivo de configuração ''config/mail.php''. Este endereço é usado se nenhum outro endereço remetente for especificado na classe //mailable//.

> from' => ['address' => 'example@example.com', 'name' => 'App Name'],

==== Configurando a View ====

Em um método ''build'' de uma classe //mailable//, pode-se utilizar o método ''view'' para especificar qual //template// deve ser usado quando renderizar o conteúdo do e-mail. Uma vez que cada e-mail tipicamente usa um ''blade template'' para renderizar o conteúdo, tem-se toda a conveniência do ''blade'' para construir e-mails com HTML.

> public function build()
> {
>     return $this->view('emails.orders.shipped');
> }

> Você talvez deseja criar um diretório ''resources/views/emails'' para hospedar todos os seus templates de emails; toda via, você é livre para armazená-los onde você desejar, desde que dentro do diretório ''resources/views''.

===== Enviando e-mail =====

Para enviar um email, usa-se o método ''to'' no //facade// ''Mail''. O método ''to'' aceita um endereço de email, uma instância de ''user'', ou uma coleção de ''users''. Se for passado um objeto ou uma coleção deles, o //mailer// irá usar suas propriedades ''email'' e ''name'' quando configurar o e-mail, devendo confirmar que esses atributos estão disponíveis no objeto passado. Uma vez especificados, pode-se passar uma instância da classe //mailable// para o método ''send'':


> class OrderController extends Controller {
>     public function ship(Request $request, $orderId){
>         $order = Order::findOrFail($orderId);
>         Mail::to($request->user())->send(new OrderShipped($order));
>     }
> }