Voir la source de API d'envoi de mails

[[Catégorie:Développement de modules]]
[[Catégorie:API Ovidentia]]

L'envoi des mails s'appuie sur la configuration SMTP renseignée par l'administrateur du site.
Avant d'utiliser les fonctions disponibles, un fichier PHP doit être inclut :

<source lang="php">
global $babInstallPath;
include_once $babInstallPath."utilit/mailincl.php";
</source>

==bab_mail()==
Retourne un objet permettant de définir le contenu d'un mail et ses destinataires.
Si l'administrateur du site a désactivé l'envoi de mails, la fonction bab_mail() renverra un booléen à la valeur false.

Exemple d'intégration en PHP :
<source lang="php">
$mail = bab_mail();
if(!$mail) {
       return true;
} else {
       ...
}
</source>

===mailFrom()===
Cette méthode est disponible sur l'objet renvoyé par bab_mail().
Elle permet de définir l'expéditeur du mail.
:'''mailFrom($expediteur_mail, $expediteur_nom)'''
* '''$expediteur_mail'''
*: e-mail de l'expéditeur
* '''$expediteur_nom'''
*: nom de l'expéditeur

===mailTo()===
Cette méthode est disponible sur l'objet renvoyé par bab_mail().
Elle permet de définir le destinataire du mail. Elle peut être exécuté plusieurs fois pour définir plusieurs destinataires.
:'''mailTo($destinataire_mail, $destinataire_nom)'''
* '''$destinataire_mail'''
*: e-mail du destinataire
* '''$destinataire_nom'''
*: nom du destinataire

===mailCc()===
Cette méthode est disponible sur l'objet renvoyé par bab_mail().
Elle permet de définir un destinataire supplémentaire en mode CC (copie) du mail. Elle peut être exécutée plusieurs fois pour définir plusieurs destinataires.
:'''mailCc($destinataire_mail, $destinataire_nom)'''
* '''$destinataire_mail'''
*: e-mail du destinataire
* '''$destinataire_nom'''
*: nom du destinataire

===mailBcc()===
Cette méthode est disponible sur l'objet renvoyé par bab_mail().
Elle permet de définir un destinataire supplémentaire en mode BCC (copie cachée) du mail. Elle peut être exécutée plusieurs fois pour définir plusieurs destinataires.
$mail->mailBcc($destinataire_mail, $destinataire_nom);
:'''mailBcc($destinataire_mail, $destinataire_nom)'''
* '''$destinataire_mail'''
*: e-mail du destinataire
* '''$destinataire_nom'''
*: nom du destinataire

===ClearTo()===
Cette méthode est disponible sur l'objet renvoyé par bab_mail().
Elle permet de supprimer (réinitialiser) les destinataires.

===ClearCc()===
Cette méthode est disponible sur l'objet renvoyé par bab_mail().
Elle permet de supprimer (réinitialiser) les destinataires.

===ClearBcc()===
Cette méthode est disponible sur l'objet renvoyé par bab_mail().
Elle permet de supprimer (réinitialiser) les destinataires.

===mailReplyTo()===
Cette méthode est disponible sur l'objet renvoyé par bab_mail().
Elle permet de définir le destinataire dans le cas d'une réponse au mail. Elle peut être exécutée plusieurs fois pour définir plusieurs destinataires.
Cette fonction est optionnelle.
:'''mailReplyTo($destinataire_mail, $destinataire_nom)'''
* '''$destinataire_mail'''
*: e-mail du destinataire
* '''$destinataire_nom'''
*: nom du destinataire

===ClearReplyTo()===
Cette méthode est disponible sur l'objet renvoyé par bab_mail().
Elle permet de supprimer (réinitialiser) les destinataires dans le cas d'une réponse au mail.

===setPriority()===
Cette méthode est disponible sur l'objet renvoyé par bab_mail().
Elle permet de définir la priorité du mail.
Cette fonction est optionnelle.
:'''setPriority($priorite)'''
* '''$priorite'''
*: entier compris entre 1 et 5 :
1 étant une priorité haute
3 étant une priorité normale
5 étant une priorité faible

===mailSubject()===
Cette méthode est disponible sur l'objet renvoyé par bab_mail().
Elle permet de définir le sujet du mail.
:'''mailSubject($sujet)'''
* '''$sujet'''
*: sujet du mail

===mailBody()===
Cette méthode est disponible sur l'objet renvoyé par bab_mail().
Elle permet de définir le contenu du mail.
:'''mailBody($contenu, $format)'''
* '''$contenu'''
*: contenu du mail
* '''$format'''
*: paramètre optionnel indiquant le format du contenu (html ou plain) (HTML par défaut)

===mailAltBody()===
Cette méthode est disponible sur l'objet renvoyé par bab_mail().
Elle permet de définir le contenu alternatif du mail, c'est à dire le contenu en mode texte qui sera visible si le destinataire choisit de ne pas afficher le mail en mode HTML.
:'''mailAltBody($contenu)'''
* '''$contenu'''
*: contenu du mail

===mailTemplate()===
Cette méthode est disponible sur l'objet renvoyé par bab_mail().
Elle permet d'envoyer le mail en tenant compte du template du site Ovidentia (mailtemplate.html).
:'''mailTemplate($contenu)'''
* '''$contenu'''
*: contenu du mail

Exemple d'intégration en PHP :
<source lang="php">
global $babInstallPath;
include_once $babInstallPath."utilit/mailincl.php";

$mail = bab_mail();
if(!$mail) {
	//L'administrateur a désactivé l'envoi des mails
} else {
	$mail->mailFrom($expediteurmail, $expediteur);
	$mail->mailTo($destinatairemail, $destinataire);
	$mail->mailSubject($sujet);
	$mail->mailBody($mail->mailTemplate($contenu));
	$mail->send();
}
</source>

===mailFileAttach()===
Cette méthode est disponible sur l'objet renvoyé par bab_mail().
Elle permet d'attacher une pièce jointe au mail. Elle peut être exécutée plusieurs fois pour attacher plusieurs fichiers.
:'''mailFileAttach($cheminfichier, $nomfichier, $typefichier)'''
* '''$cheminfichier'''
*: chemin système d'accès au fichier
* '''$nomfichier'''
*: nom du fichier
* '''$typefichier'''
*: type mime du fichier

===send()===
Cette méthode est disponible sur l'objet renvoyé par bab_mail().
Elle permet d'envoyer le mail. Elle doit donc être appelée après avoir configuré le mail.

cette méthode retourne false, s'il est impossible d'envoyer le message. 


===ErrorInfo()===
Cette méthode retourne un message d'erreur ou false si il n'y a pas d'erreur, le message d'erreur est déclenché par la méthode send()

exemple :

<source lang="php">

if (false === $mail->send()) {
     $babBody->addError($mail->ErrorInfo());
}

</source>


Le message peut être un message non traduit renvoyé pas le serveur SMTP





== Événements ==

{{Warning|Depuis la version 7.2.0 d'Ovidentia}}

[[API du gestionnaire d'événement]]

{|class="prettytable"
|'''Événement'''
|'''Parent'''
|'''Description'''
|-
|bab_eventMail
|bab_event
|Événement principal utilisé dans l'API de la messagerie, il regroupe tout les évènements appelés lors de l'envoi des email
|-
|bab_eventBeforeMailSent
|bab_eventMail
|Événement déclenché avant l'envoi d'un email, il permet d'annuler l'envoi avec la méthode <code>cancel()</code>
|-
|bab_eventAfterMailSent
|bab_eventMail
|Événement déclenché après l'envoi d'un email, il permet de récupérer un plus le statut de l'envoi
|}