php email
v1.0.5
Fornece uma maneira orientada a objetos de enviar e enfileirar e-mails.
Há necessidade de enviar e-mails em quase todos os projetos, por exemplo, para funções de registro de usuário ou redefinição de senha. A maioria dos e-mails enviados são muito fáceis. Recursos sofisticados como criptografia PGP, etc., não são necessários. Esta biblioteca oferece uma maneira de criar tais e-mails sem configurar o PHPMailer (a biblioteca subjacente), para enviar vários e-mails e até mesmo para adiar o envio de e-mails usando uma fila apoiada por um banco de dados - e tudo em um maneira orientada a objetos.
Os recursos são:
EmailQueue .Este projeto está licenciado sob GNU LGPL 3.0.
composer install technicalguru/email
Você pode baixar os pacotes de código-fonte na página de lançamento do GitHub
A classe central para configuração é EmailConfig . Ele contém todas as informações necessárias. Vamos começar com o esqueleto básico:
use TgEmailEmailConfig;
$config = new EmailConfig();
$config->setTimezone('Europe/Berlin');
$config->setDefaultSender('John Doe <[email protected]>');
$config->setSubjectPrefix('[MyAppName] ');
$config->setDebugAddress('[email protected]');
As linhas acima criam a configuração e dizem para usar o fuso horário Europe/Berlin quando precisar criar carimbos de data/hora. Isso é necessário principalmente quando os e-mails estão na fila e o carimbo de data/hora precisa ser registrado. Este valor é opcional e o padrão é UTC .
A seguir, um endereço de remetente padrão é configurado. O remetente padrão será utilizado quando um e-mail específico a ser enviado não definir um endereço de remetente. A criação de endereços de e-mail é explicada mais abaixo.
O prefixo do assunto é usado em todos os e-mails a serem enviados posteriormente. Os assuntos serão prefixados com esta string. O padrão é NULL e não modificará o assunto.
Um endereço de depuração é necessário somente quando você precisa enviar um email de teste.
Ainda precisamos saber onde nosso servidor SMTP está localizado. Então é assim que você define esses valores:
use TgEmailConfigSmtpConfig;
$host = 'smtp.example.com;
$port = 587;
$auth = TRUE;
$username = 'mySmtpUser';
$password = 'mySmtpPassword';
$secureOption = 'starttls';
$smtpConfig = new SmtpConfig($host, $port, $auth, $username, $password, $secureOption);
$config->setSmtpConfig($smtpConfig);
A maioria das opções é autoexplicativa. $auth informa ao PHPMailer subjacente se deve autenticar com determinadas credenciais de usuário. $secureOption é definido pelo PHPMailer e deve ter valor smtps ou starttls . Veja a documentação do PHPMailer para mais informações.
Todas as propriedades podem ser definidas usando um setter:
use TgEmailConfigSmtpConfig;
$smtpConfig = new SmtpConfig();
$smtpConfig->setHost('smtp.example.com');
$smtpConfig->setPort(587);
// continue setup...
As credenciais de autenticação também podem ser definidas usando a interface TgUtilsAuthCredentialsProvider do pacote technicalguru/utils :
// Define here your provider
$provider = ...;
// Tell SMTP config
$smtpConfig->setCredentialsProvider($provider);
Agora é hora de criar nosso objeto MailQueue central:
use TgEmailEmailQueue;
$mailer = new EmailQueue($config);
Você está pronto para enviar seu primeiro e-mail.
Existe uma maneira rápida e fácil de verificar se sua configuração funciona corretamente:
$email = $mailer->createTestMail();
$rc = $mailer->send($email);
Configuramos os requisitos mínimos para enviar um e-mail:
use TgEmailEmail;
$email = new Email();
$email
->setSubject('Hello World')
->addTo('[email protected]', 'John Doe')
->addBcc('[email protected]')
->setReplyTo('[email protected]')
->setBody(Email::TEXT, 'The text e-mail body')
->setBody(Email::HTML, '<p>The HTML e-mail body</p>');
// Will return FALSE when sending fails
$rc = $mailer->send($email);
É isso. O trecho de código acima é tudo que você precisa no código do seu aplicativo para enviar e-mails. A configuração e a configuração devem estar ocultas em algum lugar da configuração da sua infraestrutura.
Anexar arquivos ou incorporar imagens é simples. Você precisará ter o arquivo disponível e legível no sistema de arquivos:
use TgEmailAttachment;
$myFile = new Attachment(Attachment::ATTACHED, 'file.pdf', NULL, '/local/path/to/file.pdf', 'application/pdf');
$myImage = new Attachment(Attachment::EMBEDDED, 'img.png', 'img1', '/local/path/to/img.png', 'image/png');
$email
->addAttachment($myFile)
->addAttachment($myImage);
Observe o terceiro parâmetro das imagens incorporadas. Ele define um ID exclusivo em seu e-mail HTML que você pode consultar por
// Using the embedded image
$myHTML = '<img src="cid:img1">';
O MailQueue deixará todos os seus anexos intactos no seu sistema de arquivos. No entanto, às vezes você pode querer se livrar do arquivo depois de enviar o e-mail. O construtor recebe dois argumentos adicionais:
$myFile = new Attachment(Attachment::ATTACHED, $filename, $cid, $path, $mimeType, TRUE, TRUE);
O primeiro booleano fará com que o arquivo seja excluído após o envio do e-mail com sucesso. O segundo booleano informa se o arquivo pode ser excluído quando o envio falhou. Usando esses parâmetros você não precisa mais se preocupar com arquivos temporários. Especialmente quando se trata de filas e envios diferidos.
MailQueue suporta os chamados modos de correio. Eles dizem ao objeto mailer como geralmente tratar os e-mails. Isso é confortável quando você está testando uma configuração, quando está em um ambiente que possui endereços de e-mail reais (como ambientes de teste de aceitação do usuário) ou quando realmente enviar e-mails não faz muito sentido.
Estes modos estão disponíveis:
EmailQueue::DEFAULT - Esta é a operação normal. Todos os e-mails são enviados conforme definido.EmailQueue::BLOCK - Isso impedirá que qualquer e-mail seja enviado ou colocado na fila. O código de retorno é sempre TRUE.EmailQueue::REROUTE - Todos os e-mails serão enviados para outro endereço, geralmente um endereço de administrador ou desenvolvedor e os destinatários definidos do e-mail serão ignorados.EmailQueue::BCC - Os e-mails serão enviados aos destinatários pretendidos, mas endereços adicionais são definidos em BCC.Bloquear todos os e-mails a serem enviados ou enfileirados é bastante fácil:
$mailer->setMailMode(EmailQueue::BLOCK);
O mesmo método pode ser usado no objeto EmailConfig central.
Você precisa que uma configuração RerouteConfig seja definida na configuração principal. Você pode definir isso antecipadamente ao criar o objeto de configuração ou totalmente ao definir o modo de email:
use TgEmailConfigRerouteConfig;
// Create the config
$subjectPrefix = '[Rerouted]';
$recipients = array('[email protected]');
$rerouteConfig = new RerouteConfig($subjectPrefix, $recipients);
// And set the mail mode
$mailer->setMailMode(EmailQueue::REROUTE, $rerouteConfig);
Você precisa que uma configuração BccConfig seja definida na configuração principal. Você pode definir isso antecipadamente ao criar o objeto de configuração ou totalmente ao definir o modo de email:
use TgEmailConfigBccConfig;
// Create the config
$recipients = array('[email protected]');
$bccConfig = new BccConfig($recipients);
// And set the mail mode
$mailer->setMailMode(EmailQueue::BCC, $bccConfig);
Uma desvantagem de enviar e-mails diretamente do código do aplicativo é que isso consome muito tempo. Seu usuário precisa aguardar a conclusão do envio antes de ver qualquer resposta do seu aplicativo. Colocar e-mails na fila é a solução, pois o envio é adiado (preferível a um cron job) e o usuário recebe a resposta do aplicativo rapidamente.
Você precisará de um objeto TgDatabaseDatabase para enfileirar e-mails. Caso contrário, EmailQueue lançará exceções quando você tentar enfileirar e-mails. Consulte a documentação TgDatabaseDatabase sobre como criar o objeto Database . Configure o EmailsDAO e EmailQueue da seguinte maneira:
use TgEmailEmailsDAO;
$dao = new EmailsDAO($database);
$mailer = new EmailQueue($config, $dao);
O mailer criará automaticamente a tabela de filas se ela não existir.
Assim que o EmailsDAO estiver disponível, você poderá enfileirar e-mails facilmente:
// Create your email object here
$email = ...
// Queue it. Will return FALSE when sending fails
$rc = $mailer->queue($email);
Você pode processar a fila em outra chamada ou durante um cronjob:
$mailer->processQueue($maxSeconds);
O argumento $maxSeconds garantirá que o processamento pare quando o limite de tempo for atingido. O argumento é opcional e o padrão é 60 segundos.
Existem várias maneiras de criar endereços de e-mail. Todos os componentes de correspondência usam um objeto EmailAddress . Você pode usar este objeto como argumento sempre que endereços de e-mail forem esperados. Existem várias maneiras de criar tal objeto.
// From a string
$address = EmailAddress::from('[email protected]');
$address = EmailAddress::from('<[email protected]>');
$address = EmailAddress::from('John Doe <[email protected]>');
// From email string and name
$address = EmailAddress::from('[email protected]', 'John Doe');
// From another object
$obj = new stdClass;
$obj->name = 'John Doe';
$obj->email = '[email protected]';
$address = EmailAddress::from($obj);
// From another EmailAddress
$address = EmailAddress::from($anotherEmailAddressObject);
Isso significa que você pode usar estas opções ao criar e-mails:
$email->addTo('John Doe <[email protected]>');
$email->addTo('[email protected]', 'John Doe');
$email->addTo(array('John Doe <[email protected]>', $anotherEmailAddressObject, $obj);
Os objetos de configuração apresentados acima também podem ser criados usando strings JSON, objetos ou matrizes associativas. Os trechos a seguir descrevem os objetos JSON em notação curta.
SmtpConfig:
-----------
{
"host": "www.example.com",
"port": 587,
"debugLevel": 0,
"auth": true,
"secureOption": "starttls",
"charset": "utf8",
"credentials": {
"user": "username",
"pass": "password"
}
},
RerouteConfig:
--------------
{
"recipients": "[email protected]",
"subjectPrefix": "[Rerouted]"
},
BccConfig:
----------
{
"recipients": "[email protected]"
},
EmailConfig:
------------
{
"timezone": "Europe/Berlin",
"mailMode": "default",
"smtpConfig": {... see above ...},
"rerouteConfig": {... see above ...},
"bccConfig": {... see above ...},
"debugAddress": "[email protected]",
"defaultSender": "[email protected]",
"subjectPrefix": "[PHPUnitTest] "
}
Cada uma das classes de configuração fornece um método from() estático que usa esses tipos como argumento e retorna o próprio objeto de configuração:
$smtpConfig = SmtpConfig::from($jsonStringOrObjectOrAssocArray);
$rerouteConfig = RerouteConfig::from($jsonStringOrObjectOrAssocArray);
$bccConfig = BccConfig::from($jsonStringOrObjectOrAssocArray);
$emailConfig = EmailConfig::from($jsonStringOrObjectOrAssocArray);
É possível passar um array de objetos Email para as funções send() e queue() . No entanto, especialmente para enviar e-mails imediatamente, você deve estar ciente de que isso pode levar algum tempo. Uma estratégia melhor é enfileirar correspondências em massa.
A maioria dos testes do PHPUnit não serão executados quando não houver servidor ou banco de dados SMTP disponível. Os testes de unidade verificarão as variáveis de ambiente EMAIL_TEST_SMTP e EMAIL_DATABASE . Existe um script bash disponível, set-test-env.sh que cria essas variáveis para você. Copie-o para, por exemplo, set-local-test-env.sh e siga as instruções no arquivo.
Relate um bug, solicite uma melhoria ou pull request no GitHub Issue Tracker.
