The symfony Cookbook

Visão Geral

Enviar emails é uma tarefa comum para todos os desenvolvedores web, e o symfony 1.1 torna esta tarefa mais fácil do que nunca usando o Swift Mailer.

O Swift Mailer é uma poderosa biblioteca PHP5 totalmente orientada a objetos, que irá satisfazer 120% das suas necessidades de email.

Ela fica armazenada em um diretório SVN separado, e por isso não haverá problema algum com o seu projeto caso você decida atualizar a biblioteca. É você quem decide se quer atualizar para uma versão mais nova.

A forma de enviar emails pelo symfony é muito simples. Você cria um partial ou um componente que irá manipular o conteúdo do email, e usa o Swift para enviá-lo de uma forma bastante flexível.

Instalando

Se o seu projeto já estiver usando SVN, você pode instalá-lo usando o comando svn:externals:

$ cd /path/to/symfony/project
$ mkdir -p lib/vendor
$ svn propedit svn:externals .

E depois adicione a seguinte linha:

swift http://swiftmailer.svn.sourceforge.net/svnroot/swiftmailer/tags/php5/3.3.3/lib/

Se o seu projeto não estiver usando SVN, você ainda pode baixá-lo pelo subversion usando os seguintes comandos:

$ cd /path/to/symfony/project
$ mkdir -p lib/vendor
$ svn checkout http://swiftmailer.svn.sourceforge.net/svnroot/swiftmailer/tags/php5/3.3.3/lib/ swift

Depois disso, limpe o cache para forçar o symfony a enxergar os novos diretórios que foram criados, e pronto!

Configuração

Não há configuração específica de email.

Para manter o seu projeto flexível, você deve utilizar o arquivo de configuração app.yml para inserir os endereços de email. Desse modo, você pode ter vários remetentes/destinatários de acordo com o ambiente(environment) que você estiver trabalhando. E caso alguém precise alterá-los, não será necessário vasculhar todo o código do projeto. O lugar onde fazer a alteração será bastante óbvio.

Gerando o e-mail

A partir do symfony 1.1, você pode pegar facilmente o conteudo de partials ou componentes a partir de uma ação:

$corpoDoEmail = $this->getPartial('mailBody', array('name' => 'Vitor Mello'));
 

ou

$corpoDoEmail = $this->getComponent('mail', 'mailBody', array('name' => 'Vitor Mello'));
 

Enviar um e-mail HTML

Agora, vamos enviar o email acima usando o Swift:

try
{
  // Criar a mensagem e o objeto que irá enviar os emails
  $mailer = new Swift(new Swift_Connection_NativeMail());
  $mensagem = new Swift_Message('Assunto do Email', $corpoDoEmail, 'text/html');
 
  // Enviar
  $mailer->send($mensagem, $destinatario, $remetente);
  $mailer->disconnect();
}
catch (Exception $e)
{
  $mailer->disconnect();
 
  // tratar os erros aqui
}
 

Enviando um e-mail em várias partes

Alguns clientes de email não gostam muito de HTML, por isso é uma boa idéia enviar seus emails tanto em HTML como em texto puro.

try
{
  // Criar a mensagem e o objeto que irá enviar os emails
  $mailer = new Swift(new Swift_Connection_NativeMail());
  $mensagem = new Swift_Message('Assunto do email de testes');
 
  // Montar as várias partes do email
  $contextoDoEmail = array('name' => 'Vitor Mello');
  $mensagem->attach(new Swift_Message_Part($this->getPartial('mail/mailHtmlBody', $contextoDoEmail), 'text/html'));
  $mensagem->attach(new Swift_Message_Part($this->getPartial('mail/mailTextBody', $contextoDoEmail), 'text/plain'));
 
  // Enviar
  $mailer->send($mensagem, $destinatario, $remetente);
  $mailer->disconnect();
}
catch (Exception $e)
{
  $mailer->disconnect();
 
  // tratar erros aqui
}
 

Usando diferentes configurações de conexão

Quando você instancia a classe Swift, você pode utilizar diferentes objetos do tipo Swift_Connection.

• Swift_Connection_NativeMail é o driver de conexão que irá utilizar a funcão mail, nativa do PHP.

• Swift_Connection_SMTP envia os emails através de um servidor SMTP. O construtor pede três parâmetros, todos opcionais:

  public function __construct($server="localhost", $port=null, $encryption=null)
   

  Veremos daqui a pouco como usar este driver para enviar emails através de um servidor SMTP seguro, como o Gmail, por exemplo.

• Swift_Connection_Sendmail utiliza o binário sendmail para o envio de emails. Você pode especificar o caminho para ele no próprio construtor.

• Swift_Connection_Multi é o primeiro driver especial, que pode ser usado para combinar mais de um driver de conexão. Ele irá automaticamente tentar um outro driver de conexão, caso o servidor SMTP esteja fora do ar ao tentar enviar o email, por exemplo. O construtor irá receber um array de instâncias do objeto Swift_Connection, que podem, inclusive, conter outras instâncias do Swift_Connection_Multi (embora a razão de fazer isto seja um pouco obscura).

• Swift_Connection_Rotator é o último, que faz um pouco mais do que o Swift_Connection_Multi: ele guarda uma lista dos servidores que estão inacessíveis, e faz uma rotação entre os servidores que estão ativos. O modo de usá-lo vai alem do escopo desse documento, e você deve procurar maiores informações na própria documentação do Documentação do Swift.

Usando os servidores SMTP do Gmail

Por que alguém iria querer usar uma conta do gmail para enviar emails?

• Você não precisará configurar e administrar um servidor SMTP
• Seus emails não serão vistos como spam pelos usuários do hotmail (ou similares)
• Você ganha uma cópia carbono de todos os emails enviados, na pasta Emails Enviados

Quais são as limitações?

• Você necessita de uma conta no gmail (é de graça!)
• As negociações entre SMTP e SSL demoram um pouco mais do que usar apenas SMTP.
• Você não pode enviar emails a partir de um email aleatório (mas você pode adicionar um novo endereço Enviar Email Como nas suas configurações de conta)

Veja como configurar um objeto do Swift:

$connection = new Swift_Connection_SMTP('smtp.gmail.com', 465, Swift_Connection_SMTP::ENC_SSL);
$connection->setUsername('vitormv@gmail.com');
$connection->setPassword('senhaUltraSegura');
 
$mailer = new Swift($connection);
 

Embutindo imagens

Para embutir imagens no seu email, você precisa convertê-las para um formato apropriado antes de exibir seu conteudo. Veja um exemplo de como fazer isto:

// Criar a mensagem e o objeto que irá enviar os emails
$mailer = new Swift(new Swift_Connection_NativeMail());
$mensagem = new Swift_Message('Assunto do email de Testes');
 
// Inline images
$images = array();
$images['symfony'] = new Swift_Message_Image(new Swift_File(sfConfig::get('sf_web_dir').'/images/symfony.gif'));
$images['swift']   = new Swift_Message_Image(new Swift_File(sfConfig::get('sf_web_dir').'/images/swift.jpg'));
 
$imageReferences = array();
foreach ($images as $name => $image)
{
  $imageReferences[$name] = $message->attach($image);
}
 
// Montar as várias partes do email
$mailContext = array('name' => 'Vitor Mello', 'images' => $imageReferences);
$mensagem->attach(new Swift_Message_Part($this->getPartial('mail/mailHtmlBody', $mailContext), 'text/html'));
$mensagem->attach(new Swift_Message_Part($this->getPartial('mail/mailTextBody', $mailContext), 'text/plain'));
 
// Send
$mailer->send($mensagem, $destinatario, $remetente);
$mailer->disconnect();
 

No seu partial/componente você pode incluir facilmente as imagens embutidas da seguinte maneira:

<img src="<?php echo $images['symfony']; ?>" alt="Symfony Project" />
<img src="<?php echo $images['swift']; ?>" alt="Swift Mailer" />

Fácil, fácil, não?

Anexos

Felizmente, anexar um arquivo a um email é tão simples quanto esperaríamos que fosse:

$message->attach(new Swift_Message_Attachment(new Swift_File($file), $filename, $mime_type));
 

Listas de Destinatários

Na maioria da vezes, você pode querer enviar o mesmo email para mais de uma pessoa, ou mesmo incluir outras pessoas como cópias carbono. Você pode fazer isso facilmente usando a classe Swift_RecipientList.

$destinatarios = new Swift_RecipientList();
$destinatarios->addTo($to);
$destinatarios->addCc($cc);
$destinatarios->addBcc($bcc);
 

Se você estiver enviando emails em um loop, não se esqueça de usar o método ->flush() na sua lista de $destinatarios, ou você vai ter um trabalhão pra explicar porque alguém recebeu 500 cópias de uma newsletter.

Enviando emails a partir de uma tarefa (task)

O processo é exatamente igual à maneira como você faria a partir de uma ação, com uma pequena diferença: você não pode mais utilizar os métodos da sfAction.

você precisará utilizar as funções get_partial() e get_component() contidas no PartialHelper ao invés dos métodos sfAction::getPartial() e sfAction::getComponent.

Documentação adicional

O site do SwiftMailer é uma mina de ouro de documentação e tutoriais.

E, é claro, o guia de referencia completo da API também está disponível, caso você precise.