php email
v1.0.5
Fournit un moyen orienté objet pour envoyer et mettre en file d’attente des e-mails.
Il est nécessaire d'envoyer des e-mails dans presque tous les projets, par exemple pour l'enregistrement des utilisateurs ou pour les fonctions de réinitialisation de mot de passe. La plupart des e-mails envoyés sont très simples. Des fonctionnalités sophistiquées telles que le cryptage PGP, etc. ne sont pas requises. Cette bibliothèque offre un moyen de créer de tels e-mails sans configurer PHPMailer (la bibliothèque sous-jacente), d'envoyer plusieurs e-mails et même de différer l'envoi d'e-mails en utilisant une file d'attente sauvegardée par une base de données - et le tout dans un manière orientée objet.
Les fonctionnalités sont :
EmailQueue .Ce projet est sous licence GNU LGPL 3.0.
composer install technicalguru/email
Vous pouvez télécharger les packages de code source à partir de la page de version GitHub.
La classe centrale pour la configuration est EmailConfig . Il contient toutes les informations nécessaires. Commençons par le squelette de base :
use TgEmailEmailConfig;
$config = new EmailConfig();
$config->setTimezone('Europe/Berlin');
$config->setDefaultSender('John Doe <[email protected]>');
$config->setSubjectPrefix('[MyAppName] ');
$config->setDebugAddress('[email protected]');
Les lignes ci-dessus créent la configuration et lui indiquent d'utiliser le fuseau horaire Europe/Berlin lorsqu'il a besoin de créer des horodatages. Cela est principalement nécessaire lorsque les e-mails sont en file d'attente et que l'horodatage doit être enregistré. Cette valeur est facultative et la valeur par défaut est UTC .
Ensuite, une adresse d'expéditeur par défaut est configurée. L'expéditeur par défaut sera utilisé lorsqu'un e-mail spécifique à envoyer ne définit pas d'adresse d'expéditeur. La création d'adresses e-mail est expliquée plus en détail ci-dessous.
Le préfixe d'objet est utilisé sur chaque e-mail à envoyer ultérieurement. Les sujets seront préfixés par cette chaîne. La valeur par défaut est NULL et ne modifiera pas le sujet.
Une adresse de débogage est requise uniquement lorsque vous devez envoyer un courrier test.
Nous devons encore indiquer où se trouve notre serveur SMTP. Voici donc comment définir ces valeurs :
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 plupart des options s’expliquent d’elles-mêmes. $auth indique à PHPMailer sous-jacent s'il doit s'authentifier avec les informations d'identification de l'utilisateur données. $secureOption est défini par PHPMailer et doit avoir la valeur smtps ou starttls . Consultez la documentation PHPMailer pour plus d'informations.
Toutes les propriétés peuvent être définies à l'aide d'un setter :
use TgEmailConfigSmtpConfig;
$smtpConfig = new SmtpConfig();
$smtpConfig->setHost('smtp.example.com');
$smtpConfig->setPort(587);
// continue setup...
Les informations d'authentification peuvent également être définies à l'aide de l'interface TgUtilsAuthCredentialsProvider du package technicalguru/utils :
// Define here your provider
$provider = ...;
// Tell SMTP config
$smtpConfig->setCredentialsProvider($provider);
Il est maintenant temps de créer notre objet central MailQueue :
use TgEmailEmailQueue;
$mailer = new EmailQueue($config);
Vous êtes prêt à envoyer votre premier e-mail.
Il existe un moyen simple et rapide de vérifier si votre configuration fonctionne correctement :
$email = $mailer->createTestMail();
$rc = $mailer->send($email);
Nous avons configuré la configuration minimale requise pour envoyer un 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);
C'est ça. L'extrait de code ci-dessus est tout ce dont vous auriez besoin dans le code de votre application pour envoyer des e-mails. La configuration et l'installation doivent être enfouies quelque part dans la configuration de votre infrastructure.
Joindre des fichiers ou intégrer des images est simple. Vous devrez avoir le fichier disponible et lisible sur le système de fichiers :
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);
Notez le troisième paramètre des images intégrées. Il définit un identifiant unique dans votre e-mail HTML que vous pouvez référencer en
// Using the embedded image
$myHTML = '<img src="cid:img1">';
La MailQueue laissera toutes vos pièces jointes intactes sur votre système de fichiers. Cependant, vous souhaiterez parfois vous débarrasser du fichier après avoir envoyé l'e-mail. Le constructeur prend deux arguments supplémentaires :
$myFile = new Attachment(Attachment::ATTACHED, $filename, $cid, $path, $mimeType, TRUE, TRUE);
Le premier booléen déclenchera la suppression du fichier une fois l'e-mail envoyé avec succès. Le deuxième booléen indique si le fichier peut être supprimé en cas d'échec de l'envoi. En utilisant ces paramètres, vous n'avez plus besoin de vous soucier des fichiers temporaires. Surtout lorsqu'il s'agit de files d'attente et d'envois différés.
MailQueue prend en charge ce que l'on appelle les modes de messagerie. Ils indiquent à l'objet mailer comment traiter généralement les e-mails. Cela est pratique lorsque vous testez une configuration, lorsque vous êtes dans un environnement doté de véritables adresses e-mail (comme les environnements de test d'acceptation utilisateur) ou lorsque l'envoi d'e-mails n'a pas beaucoup de sens.
Ces modes sont disponibles :
EmailQueue::DEFAULT - Il s’agit du fonctionnement normal. Tous les e-mails sont envoyés comme défini.EmailQueue::BLOCK - Cela empêchera l'envoi ou la mise en file d'attente de tout courrier. Le code retour est toujours VRAI.EmailQueue::REROUTE - Tous les e-mails seront envoyés à une autre adresse, généralement une adresse d'administrateur ou de développeur et les destinataires définis de l'e-mail sont ignorés.EmailQueue::BCC - Les e-mails seront envoyés à leurs destinataires prévus mais des adresses supplémentaires sont définies sur BCC.Bloquer tous les e-mails à envoyer ou à mettre en file d'attente est assez simple :
$mailer->setMailMode(EmailQueue::BLOCK);
La même méthode peut être utilisée sur l'objet central EmailConfig .
Vous devez définir une configuration RerouteConfig dans la configuration principale. Vous pouvez définir cela dès le départ lors de la création de l'objet de configuration, ou ensemble lors de la définition du mode courrier :
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);
Vous avez besoin qu'une configuration BccConfig soit définie dans la configuration principale. Vous pouvez définir cela dès le départ lors de la création de l'objet de configuration, ou ensemble lors de la définition du mode courrier :
use TgEmailConfigBccConfig;
// Create the config
$recipients = array('[email protected]');
$bccConfig = new BccConfig($recipients);
// And set the mail mode
$mailer->setMailMode(EmailQueue::BCC, $bccConfig);
L’un des inconvénients de l’envoi d’e-mails directement à partir du code de l’application est que cela prend du temps. Votre utilisateur doit attendre la fin de l'envoi avant de pouvoir voir la réponse de votre candidature. La mise en file d'attente des e-mails est la solution car l'envoi est différé (préférable à une tâche cron) et l'utilisateur reçoit rapidement la réponse de sa candidature.
Vous aurez besoin d'un objet TgDatabaseDatabase pour mettre les e-mails en file d'attente. Sinon, EmailQueue lèvera des exceptions lorsque vous tenterez de mettre des e-mails en file d'attente. Veuillez vous référer à la documentation TgDatabaseDatabase pour savoir comment créer l'objet Database . Configurez les EmailsDAO et EmailQueue correspondants comme suit :
use TgEmailEmailsDAO;
$dao = new EmailsDAO($database);
$mailer = new EmailQueue($config, $dao);
Le logiciel de messagerie créera automatiquement la table de file d'attente si elle n'existe pas.
Une fois que l' EmailsDAO est disponible, vous pouvez facilement mettre les e-mails en file d'attente :
// Create your email object here
$email = ...
// Queue it. Will return FALSE when sending fails
$rc = $mailer->queue($email);
Vous pouvez traiter la file d'attente lors d'un autre appel ou lors d'une tâche cron :
$mailer->processQueue($maxSeconds);
L'argument $maxSeconds garantira que le traitement s'arrête lorsque le délai est atteint. L'argument est facultatif et la valeur par défaut est 60 secondes.
Il existe plusieurs façons de créer des adresses e-mail. Tous les composants de messagerie utilisent un objet EmailAddress . Vous pouvez utiliser cet objet comme argument partout où des adresses e-mail sont attendues. Plusieurs manières existent pour créer un tel objet.
// 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);
Cela signifie que vous pouvez utiliser ces saveurs lors de la création d'e-mails :
$email->addTo('John Doe <[email protected]>');
$email->addTo('[email protected]', 'John Doe');
$email->addTo(array('John Doe <[email protected]>', $anotherEmailAddressObject, $obj);
Les objets de configuration présentés ci-dessus peuvent également être créés à l'aide de chaînes JSON, d'objets ou de tableaux associatifs. Les extraits suivants décrivent les objets JSON en notation courte.
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] "
}
Chacune des classes de configuration fournit une méthode statique from() qui prend ces types comme argument et renvoie l'objet de configuration lui-même :
$smtpConfig = SmtpConfig::from($jsonStringOrObjectOrAssocArray);
$rerouteConfig = RerouteConfig::from($jsonStringOrObjectOrAssocArray);
$bccConfig = BccConfig::from($jsonStringOrObjectOrAssocArray);
$emailConfig = EmailConfig::from($jsonStringOrObjectOrAssocArray);
Il est possible de passer un tableau d'objets Email aux fonctions send() et queue() . Cependant, surtout pour l'envoi immédiat d'e-mails, vous devez savoir que cela peut prendre un certain temps. Une meilleure stratégie consiste à mettre en file d’attente les envois de masse.
La plupart des tests PHPUnit ne seront pas exécutés lorsqu'aucun serveur SMTP ou base de données n'est disponible. Les tests unitaires vérifieront les variables d'environnement EMAIL_TEST_SMTP et EMAIL_DATABASE . Un script bash est disponible, set-test-env.sh , qui crée ces variables pour vous. Copiez-le par exemple dans set-local-test-env.sh et suivez les instructions du fichier.
Signalez un bug, demandez une amélioration ou une pull request sur le GitHub Issue Tracker.
