php email
v1.0.5
Proporciona una forma orientada a objetos de enviar y poner en cola correos electrónicos.
En casi todos los proyectos es necesario enviar correos electrónicos, por ejemplo para el registro de usuarios o para las funciones de restablecimiento de contraseña. La mayoría de los correos electrónicos enviados son muy fáciles. No se requieren funciones sofisticadas como cifrado PGP, etc. Esta biblioteca ofrece una forma de crear dichos correos electrónicos sin configurar PHPMailer (la biblioteca subyacente), enviar múltiples correos electrónicos e incluso posponer el envío de correos electrónicos utilizando una cola respaldada por una base de datos, y todo en un forma orientada a objetos.
Las características son:
EmailQueue .Este proyecto tiene licencia GNU LGPL 3.0.
composer install technicalguru/email
Puede descargar los paquetes de código fuente desde la página de lanzamiento de GitHub.
La clase central para la configuración es EmailConfig . Contiene toda la información necesaria. Comencemos con el 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]');
Las líneas anteriores crean la configuración y le indican que use la zona horaria Europe/Berlin cuando necesite crear marcas de tiempo. Esto es necesario principalmente cuando los correos electrónicos están en cola y es necesario registrar la marca de tiempo. Este valor es opcional y el valor predeterminado es UTC .
A continuación, se configura una dirección de remitente predeterminada. El remitente predeterminado se utilizará cuando un correo electrónico específico a enviar no define una dirección de remitente. La creación de direcciones de correo electrónico se explica más adelante.
El prefijo de asunto se utiliza en cada correo electrónico que se enviará más tarde. Los sujetos tendrán el prefijo de esta cadena. El valor predeterminado es NULL y no modificará el asunto.
Solo se requiere una dirección de depuración cuando necesita enviar un correo de prueba.
Todavía necesitamos decir dónde está ubicado nuestro servidor SMTP. Así es como estableces estos 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);
La mayoría de las opciones se explican por sí solas. $auth le dice al PHPMailer subyacente si debe autenticarse con las credenciales de usuario dadas. $secureOption está definido por PHPMailer y tendrá el valor smtps o starttls . Consulte la documentación de PHPMailer para obtener más información.
Todas las propiedades se pueden configurar mediante un definidor:
use TgEmailConfigSmtpConfig;
$smtpConfig = new SmtpConfig();
$smtpConfig->setHost('smtp.example.com');
$smtpConfig->setPort(587);
// continue setup...
Las credenciales de autenticación también se pueden configurar mediante la interfaz TgUtilsAuthCredentialsProvider del paquetetechnicalguru technicalguru/utils :
// Define here your provider
$provider = ...;
// Tell SMTP config
$smtpConfig->setCredentialsProvider($provider);
Ahora es el momento de crear nuestro objeto MailQueue central:
use TgEmailEmailQueue;
$mailer = new EmailQueue($config);
Estás listo envía tu primer correo electrónico.
Existe una forma rápida y sencilla de comprobar si su configuración funciona correctamente:
$email = $mailer->createTestMail();
$rc = $mailer->send($email);
Hemos configurado los requisitos mínimos para enviar un correo electrónico:
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);
Eso es todo. El fragmento de código anterior es todo lo que necesitaría en el código de su aplicación para poder enviar correos electrónicos. La configuración y la configuración estarán ocultas en algún lugar de la configuración de su infraestructura.
Adjuntar archivos o incrustar imágenes es sencillo. Necesitará tener el archivo disponible y legible en el sistema de archivos:
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);
Tenga en cuenta el tercer parámetro de las imágenes incrustadas. Define una identificación única dentro de su correo electrónico HTML a la que puede hacer referencia mediante
// Using the embedded image
$myHTML = '<img src="cid:img1">';
MailQueue dejará todos sus archivos adjuntos intactos en su sistema de archivos. Sin embargo, a veces es posible que desee deshacerse del archivo después de enviar el correo electrónico. El constructor toma dos argumentos adicionales:
$myFile = new Attachment(Attachment::ATTACHED, $filename, $cid, $path, $mimeType, TRUE, TRUE);
El primer booleano hará que el archivo se elimine después de que el correo electrónico se haya enviado correctamente. El segundo booleano indica si el archivo se puede eliminar cuando falla el envío. Con estos parámetros ya no necesita preocuparse por los archivos temporales. Especialmente cuando se trata de colas y envíos diferidos.
MailQueue admite los llamados modos de correo. Le dicen al objeto de envío cómo tratar generalmente los correos electrónicos. Esto resulta cómodo cuando estás probando una configuración, cuando estás en un entorno que tiene direcciones de correo electrónico reales (como entornos de prueba de aceptación del usuario) o cuando enviar correos electrónicos no tiene mucho sentido.
Estos modos están disponibles:
EmailQueue::DEFAULT : esta es la operación normal. Todos los correos electrónicos se envían según lo definido.EmailQueue::BLOCK : esto evitará que se envíe o ponga en cola cualquier correo. El código de retorno siempre es VERDADERO.EmailQueue::REROUTE : todos los correos electrónicos se enviarán a otra dirección, generalmente una dirección de administrador o desarrollador, y se ignoran los destinatarios definidos del correo electrónico.EmailQueue::BCC : los correos electrónicos se enviarán a los destinatarios previstos, pero se configurarán direcciones adicionales en CCO.Bloquear todos los correos electrónicos que se enviarán o estarán en cola es bastante fácil:
$mailer->setMailMode(EmailQueue::BLOCK);
Se puede utilizar el mismo método en el objeto central EmailConfig .
Necesita establecer una configuración RerouteConfig en la configuración principal. Puede configurar esto por adelantado al crear el objeto de configuración, o todos juntos al configurar el modo de correo:
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);
Necesita establecer una configuración BccConfig en la configuración principal. Puede configurar esto por adelantado al crear el objeto de configuración, o todos juntos al configurar el modo de correo:
use TgEmailConfigBccConfig;
// Create the config
$recipients = array('[email protected]');
$bccConfig = new BccConfig($recipients);
// And set the mail mode
$mailer->setMailMode(EmailQueue::BCC, $bccConfig);
Una desventaja de enviar correos electrónicos directamente desde el código de la aplicación es que lleva mucho tiempo. Su usuario debe esperar a que se complete el envío antes de poder ver cualquier respuesta de su aplicación. La solución es poner en cola los correos electrónicos, ya que el envío se difiere (preferible a un trabajo cron) y el usuario recibe rápidamente la respuesta de su solicitud.
Necesitará un objeto TgDatabaseDatabase para poner en cola los correos electrónicos. De lo contrario, EmailQueue generará excepciones cuando intente poner en cola los correos electrónicos. Consulte la documentación TgDatabaseDatabase sobre cómo crear el objeto Database . Configure los EmailsDAO y EmailQueue correspondientes de la siguiente manera:
use TgEmailEmailsDAO;
$dao = new EmailsDAO($database);
$mailer = new EmailQueue($config, $dao);
El remitente creará automáticamente la tabla de cola si no existe.
Una vez que EmailsDAO esté disponible, podrá poner en cola fácilmente los correos electrónicos:
// Create your email object here
$email = ...
// Queue it. Will return FALSE when sending fails
$rc = $mailer->queue($email);
Puedes procesar la cola en otra llamada o durante un cronjob:
$mailer->processQueue($maxSeconds);
El argumento $maxSeconds garantizará que el procesamiento se detenga cuando se alcance el límite de tiempo. El argumento es opcional y su valor predeterminado es 60 segundos.
Hay varias formas de crear direcciones de correo electrónico. Todos los componentes de correo utilizan un objeto EmailAddress . Puede utilizar este objeto como argumento siempre que se esperen direcciones de correo electrónico. Existen varias formas de crear un objeto de este tipo.
// 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);
Esto significa que puede utilizar estos tipos al crear correos electrónicos:
$email->addTo('John Doe <[email protected]>');
$email->addTo('[email protected]', 'John Doe');
$email->addTo(array('John Doe <[email protected]>', $anotherEmailAddressObject, $obj);
Los objetos de configuración presentados anteriormente también se pueden crear utilizando cadenas JSON, objetos o matrices asociativas. Los siguientes fragmentos describen los objetos JSON en notación breve.
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 una de las clases de configuración proporciona un método estático from() que toma estos tipos como argumento y devuelve el objeto de configuración en sí:
$smtpConfig = SmtpConfig::from($jsonStringOrObjectOrAssocArray);
$rerouteConfig = RerouteConfig::from($jsonStringOrObjectOrAssocArray);
$bccConfig = BccConfig::from($jsonStringOrObjectOrAssocArray);
$emailConfig = EmailConfig::from($jsonStringOrObjectOrAssocArray);
Es posible pasar una serie de objetos Email a las funciones send() y queue() . Sin embargo, especialmente para enviar correos electrónicos inmediatamente, debe tener en cuenta que esto puede llevar algún tiempo. Una mejor estrategia es poner en cola los correos masivos.
La mayoría de las pruebas de PHPUnit no se ejecutarán cuando no haya un servidor SMTP o una base de datos disponible. Las pruebas unitarias comprobarán las variables de entorno EMAIL_TEST_SMTP y EMAIL_DATABASE . Hay un script bash disponible, set-test-env.sh que crea esas variables por usted. Cópielo, por ejemplo, en set-local-test-env.sh y siga las instrucciones del archivo.
Informe un error, solicite una mejora o una solicitud de extracción en GitHub Issue Tracker.
