Code-Web.org

Introduction

Nous allons étudier, dans cette article, les fonctions IMAP de PHP. Avant d'aller plus loin, notez que de bonnes connaissances sur l'architecture client/serveur vous serons très utiles si vous souhaitez utiliser ces fonctions. Comme indiqué dans le titre de l'article, nous nous limiterons ici à une simple introduction. Ainsi, nous verrons comment établir la connexion au serveur puis comment récupérer la liste des messages disponibles sur celui-ci.

Quelques bases sur les serveurs de messageries

Comme tout serveur qui se respecte, les communications avec les serveurs de messageries se font selon un protocole bien définit. Dans notre cas, il existe deux protocoles :

• IMAP
• POP3

Avant d'établir une connexion à un serveur de messagerie, vous devez impérativement connaître le protocole que celui-ci utilise sans quoi la connexion en question échouerait.

Lors de l'établissement d'une connexion, vous pouvez sélectionner un dossier. Il s'agit du dossier dans lequel vous souhaitez lire les mails. Il est bien sur possible d'en changer au cours de la connexion. Au moment de la première connexion, il est impossible de connaître la liste exacte des dossiers disponibles sur le serveur puisque l'utilisateur du compte que nous allons utiliser peut en avoir créer comme bon lui semble. Toutefois, il existe toujours le dossier INBOX, qui correspond au dossier où les messages entrant arrivent par défaut. Nous sélectionnerons donc toujours ce dossier lors d'une première connexion.

Première connexion

La fonction imap_open

Avant d'entamer la connexion à proprement parlé, nous allons étudier la fonction imap_open. Cette fonction admet des paramètres bien particuliers que nous allons étudier ici. Vous pouvez consulter la documentation officielle de cette fonction si vous le souhaitez.

resource imap_open ( string $mailbox, string $username, string $password [, int $options [, int $n_retries]] )

Comme le montre la signature de cette fonction, trois paramètres sont obligatoires. Nous nous limiterons à ces paramètres, pour les autres je vous invite une nouvelle fois à vous reporter à la documentation officielle.

$mailbox

Il s'agit de la boîte mail que nous souhaitons consulter. C'est une chaîne de caractères constituée de :

• L'adresse du serveur, exemple : pop3.free.fr
• Du port utilisé, exemple : 143
• Du protocole, exemple : POP3
• Du dossier à utiliser par défaut, généralement INBOX

Cette chaîne de caractère doit être construire ainsi : {adresseServeur:port/protocole}Dossier

Un exemple sera certainement plus parlant. Imaginons que nous souhaitions établir une connexion sur le serveur pop3.free.fr sur le port 143 en utilisant le protocole POP3 (et en utilisant INBOX comme dossier par défaut), on passera en paramètre la chaîne suivante : {pop3.free.fr:143/pop3}INBOX

$username

Il s'agit du nom d'utilisateur utilisé pour s'identifier sur le serveur. Classiquement, on utilise l'adresse e-mail de l'utilisateur. Il peut également s'agir du nom seul (sans @domaine.ext). Exemple : mon.nom@free.fr

$password

Il s'agit du mot de passe à utiliser pour l'identification, une chaîne de caractère correspondant au mot de passe du l'utilisateur indiquée dans le paramètre précédent.

Première connexion, c'est parti!

Nous allons pouvoir établir notre première connexion au serveur pop3.free.fr (par exemple) avec le code suivant :

<?php
imap_open("{pop3.free.fr:143/pop3}INBOX","mon.nom@free.fr","monMDP");
?>

Ce code est incomplet. Il ne permet pas d'une part de savoir si la connexion a bien été établie et d'autre part il ne ferme pas la connexion. Nous allons donc utiliser la valeur renvoyée par imap_open() pour vérifier que la connexion a bien été établie. Pour cela il faut savoir que deux types de valeur sont possibles :

• Un booléen à FALSE indiquant que la connexion a échouée.
• Un type ressource contenant le lien vers la connexion au serveur. Il faudra conserver cette ressource pour la passer en paramètre à d'autres fonctions imap_*.

<?php
// Tentative de connexion
$imapLink = imap_open("{pop3.free.fr:143/pop3}INBOX","mon.nom@free.fr","monMDP");
 
// Test sur le retour de la fonction imap_open()
if(!$imapLink)
      // Echec
      echo "La connexion a échouée.";
else
{
      // Connexion établie
      echo "Connexion établie, fermeture de la connexion.";
 
      // On utilise imap_close() pour fermer la connexion.
      // On lui passe en paramètre la ressource retournée par imap_open()
      imap_close($imapLink);
}
?>

Pour tester ce code, pensez à remplacer les paramètres indiqués ici par ceux correspondant au serveur de votre choix et au compte correspondant. Si vous voyez enfin apparaître le texte "Connexion établie, fermeture de la connexion.", vous avez établie votre connexion à un serveur de messagerie avec succès.

Récupérer les informations concernant la boîte de messagerie

Une fois la connexion établie, nous allons récupérer quelques informations concernant la boîte de messagerie. Vous comprendrez pourquoi par la suite. Pour celà, nous utiliserons la fonction imap_check().

object imap_check ( resource $imap_stream )

Comme vous pouvez le voir, cette fonction n'accepte qu'un seul paramètre (obligatoire) qui correspond à la ressource retournée par imap_open(). imap_check() retourne également un objet ayant pour attributs les différentes informations recherchées.

Grâce au code suivant, nous allons récupérer les informations concernant les boîte de messagerie située sur le serveur pop3.free.fr.

<?php
// Tentative de connexion
$imapLink = imap_open("{pop3.free.fr:143/pop3}INBOX","mon.nom@free.fr","monMDP");
 
// Test sur le retour de la fonction imap_open()
if(!$imapLink)
      // Echec
      die("La connexion a échouée."); // Fin du script
 
// Connexion établie
echo "Connexion établie, lecture des informations :<br />";
 
// On récupére les informations
$mailBoxInfos = imap_check($imapLink);
 
// On affiche ces informations
echo '<pre>';
print_r($mailBoxInfos);
echo '</pre>';
 
// On utilise imap_close() pour fermer la connexion.
imap_close($imapLink);
 
?>

Une nouvelle, fois, n'oubliez pas de remplacer les paramètres pour vos tests.

Si tout a bien fonctionné, vous devriez vous apparaître quelque chose comme ceci :

Connexion établie, lecture des informations :
stdClass Object
(
    [Date] => Sat, 10 Nov 2007 21:29:32 +0100 (CET)
    [Driver] => pop3
    [Mailbox] => {pop3.free.fr:143/pop3/user="mon.nom@free.fr"}INBOX
    [Nmsgs] => 9
    [Recent] => 9
)

L'objet retourné contient donc 5 attributs :

• Date, qui correspond à la date de dernière modification du contenu de la boîte de messagerie.
• Driver, qui correspond au protocole utilisé.
• Mailbox, la boîte de messagerie courante.
• Nmsgs, qui correspond au nombre de message dans le dossier courant (INBOX) dans la boîte courante.
• Recent, le nombre de nouveaux messages, non lus.

C'est l'attribut Nmsgs qui nous intéressera pour obtenir la liste des messages présents dans le dossier INBOX. Vous allez comprendre tout de suite.

Récupération de la liste des messages

Nous y voilà! Avec tout ce nous avons vu et les informations que nous sommes en mesure de récupérer sur le serveur, nous allons enfin pouvoir récupérer la liste des messages présents sur le serveur dans le dossier courant, INBOX.

Pour cela, nous allons utiliser la fonction :

array imap_fetch_overview ( resource $imap_stream, string $sequence [, int $options] )

Là encore nous ne parlerons que des paramètres obligatoires.

$imap_stream

Il s'agit toujours de la ressource contenant le lien vers la connexion au serveur de messagerie.

$sequence

Vous devrez indiquer dans ce paramètre, sous la forme d'une chaîne de caractère, le numéro du message de départ et le numéro du message de fin que vous souhaitez obtenir. Les messages, sur le serveur, sont numérotés de 0 à NombreDeMessageTotal. Pour obtenir la liste complète des messages présents dans le dossier courant, il nous faut donc connaître à l'avance le nombre de messages qu'il contient. C'est précisément ce que nous avons fait avec la fonction imap_check au paragraphe précédent.

En somme nous devons indiquer l'interval de messages que nous souhaitons obtenir. L'intérêt de ce système n'est peut être pas évident au premier abord mais imaginons que nous ayons mis en place un système de pagination dans notre liste de messages. Il serait totalement inutile de télé charger les informations concernant tout les message alors que seul ceux qui seront affichés sur la page courante nous intéresse.

La syntaxe de ce paramètre est la suivante : NumDepart:NumFin

Pour obtenir les messages du numéro 0 au numéro 10 on passera donc en paramètre la chaîne suivante : 0:10

Voici maintenant le dernier code que nous verrons dans cet article, il affiche la liste des messages présents sur le serveur. Pour en savoir plus sur ces informations, reportez-vous à la documentation officielle.

<?php
// Tentative de connexion
$imapLink = imap_open("{pop3.free.fr:143/pop3}INBOX","mon.nom@free.fr","monMDP");
 
// Test sur le retour de la fonction imap_open()
if(!$imapLink)
      // Echec
      die("La connexion a échouée."); // Fin du script
 
// Connexion établie
echo "Connexion établie, lecture des messages :<br />";
 
// On récupère les informations
$mailBoxInfos = imap_check($imapLink);
 
// On récupère la liste des messages
$mailList = imap_fetch_overview($imapLink,"0:".$mailBoxInfos->Nmsgs);
 
// On affiche la liste des messages
echo '<pre>';
print_r($mailList);
echo '</pre>';
 
// On utilise imap_close() pour fermer la connexion.
imap_close($imapLink);
 
?>

Pour aller plus loin

Comme très souvent, rien ne vaut la documentation officielle de PHP. Malheureusement, il existe très peu de tutoriaux sur le sujet et il sera probablement difficile d'en trouver de bien complets. Cela-dit, rien ne vous empêche de faire vos propres test ou encore de regarder dans les sources de clients de messagerie tels que Horde.

Conclusion

J'espère simplement que cette petite introduction, si légère soit-elle, vous aura donné l'envie de développer un bon p'tit client de messagerie en PHP. Si c'est le cas, n'hésitez pas à m'en parler par mail, je consacrerait avec plaisir un article à vos développements. Mais, et je le rappel une nouvelle fois, les commentaires ne sont pas un espace publicitaire!