Introduction aux fonctions IMAP de PHP

Vieux Nicolas

Cet article a pour but de découvrir le fonctionnement et de permettre de consulter un ou plusieurs mails d'une messagerie via les primitives IMAP de PHP.

À la fin de ce cours, vous serez capable de créer un client Webmail léger mais fonctionnel.

Pour chaque nouvelle fonction, vous aurez les parties suivantes :

- description ;

- liste des paramètres ;

- valeurs de retour ;

- un exemple fonctionnel.

Commentez

- Titre : Introduction aux fonctions IMAP de PHP

- Auteur : Vieux Nicolas

- Parution : 11 juillet 2013

- Mise à jour : 11 juillet 2013

- Public visé :

- Licence : Les sources présentées sur cette page sont libres de droits et vous pouvez les utiliser à votre convenance. Par contre, la page de présentation constitue une œuvre intellectuelle protégée par les droits d'auteur. Copyright ® 2013 Vieux Nicolas. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Introduction

- I-A. Les protocoles de messagerie

- I-A-1. Exchange Server

- I-A-2. SMTP (Simple Mail Transfert Protocol)

- I-A-3. POP (Post Office Protocol)

- I-A-4. IMAP (Internet Message Access Protocol)

- I-B. Communications entre serveurs de messageries

- I-C. Les différences entre IMAP et POP

- II. Liste des fonctions

- III. États d'une session IMAP

- III-A. Types de réponses

- III-B. État non authentifié (non-authentificated)

- III-C. État authentifié (authentificated)

- III-D. État sélectionné (selected)

- III-E. État déconnexion (logout)

- III-F. Diagramme d'états-transitions

- III-G. Première connexion

- III-G-1. imap_open

- III-G-1-a. Description

- III-G-1-b. Liste des paramètres

- III-G-1-c. Valeurs de retour

- III-G-1-d. Exemple

- III-H. Test de la connexion et fermeture de celle-ci

- III-H-1. Description

- III-H-2. Liste des paramètres

- III-H-3. Valeurs de retour

- III-H-4. Exemple

- III-I. Récupérer des informations sur la boîte de messagerie

- III-I-1. Description

- III-I-2. Liste des paramètres

- III-I-3. Valeurs de retour

- III-I-4. Exemple

- III-J. Récupération de la liste des messages

- III-J-1. Description

- III-J-2. Liste des paramètres

- III-J-3. Valeurs de retour

- III-J-4. Exemple

- III-K. Télécharger le corps d'un message

- III-K-1. Description

- III-K-2. Liste des paramètres

- III-K-3. Valeurs de retour

- III-K-4. Exemple

- IV. Conclusion

- V. Remerciement

I - Introduction

Les fonctions ci-après vous permettront d'utiliser le protocole IMAP, mais aussi les protocoles NNTP, POP3 et les boîtes aux lettres locales.

Cependant, soyez prudent et lisez bien la documentation, car certaines fonctions IMAP de PHP ne fonctionnent pas correctement avec le protocole POP.

Voici la documentation du manuel : http://fr2.php.net/manual/fr/book.imap.php.

I-A - Les protocoles de messagerie

I-A-1 - Exchange Server

Exchange Server est un logiciel de messagerie créé par Microsoft pour concurrencer Lotus Domino d'IBM. Permettant d'envoyer et de recevoir des courriers électroniques et d'échanger d'autres formes de communication interactive par le biais de réseaux informatiques.

Microsoft Exchange Server représente 65 % du marché de la messagerie professionnelle en France.

C'est un produit de la gamme des serveurs Microsoft, conçu pour la messagerie électronique, mais aussi pour la gestion d'agenda, de contacts et de tâches, qui assure le stockage des informations et permet des accès à partir de clients mobiles (Outlook Mobile Access, Exchange Active Server Sync) et de clients Web (navigateurs tels que Internet Explorer, Mozilla Firefox, Safari (Apple)…).

Suivant la vague du cloud computing (Tutoriel pour débutant sur le cloud computing), Microsoft Exchange est, depuis 2009, disponible au travers d'une offre SaaS appelée Microsoft Online Services sous le nom d'Exchange Online.

I-A-2 - SMTP (Simple Mail Transfert Protocol)

Le protocole SMTP, Simple Mail Transfer Protocol (littéralement « Protocole simple de transfert de courrier »), est un protocole de communication utilisé pour transférer le courrier électronique (courriel) vers les serveurs de messagerie électronique.

Comme son nom l'indique, SMTP est un protocole assez simple. On commence par spécifier l'expéditeur du message puis, le ou les destinataires d'un message, puis, en général après avoir vérifié leur existence, le corps du message est transféré. Il est possible de tester un serveur SMTP en utilisant la commande telnet sur le port 25 d'un serveur distant.

Le logiciel Sendmail est l'un des premiers serveurs de messagerie électronique à utiliser SMTP. Depuis, la plupart des clients de messagerie peuvent utiliser SMTP pour envoyer les messages. Certains nouveaux serveurs sont apparus, comme Postfix, Qmail et Exchange de Microsoft (qui accomplit également d'autres fonctions).

Comme le protocole utilisait du texte en ASCII (7 bits), il ne fonctionnait pas pour l'envoi de n'importe quels octets dans des fichiers binaires. Pour pallier ce problème, des standards comme MIME ont été développés pour permettre le codage des fichiers binaires au travers de SMTP. Aujourd'hui, la plupart des serveurs SMTP acceptent le MIME sur 8 bits, ce qui permet de transférer des fichiers binaires presque aussi facilement que du texte simple.

SMTP utilise TCP pour le transfert des données.

SMTP ne permet pas de récupérer à distance des courriels arrivés dans une boîte aux lettres sur un serveur. Les standards Post Office Protocol (POP) et IMAP ont été créés dans ce but.

I-A-3 - POP (Post Office Protocol)

Le protocole POP (Post Office Protocol), en français le protocole du bureau de poste, est un protocole qui permet de récupérer les courriers électroniques situés sur un serveur de messagerie électronique.

Cette opération nécessite une connexion à un réseau TCP/IP. Le port utilisé est le 110.

Après la création de POP3 le protocole POP3S a vu le jour pour sécuriser la communication avec le serveur. POP3S utilise le port 995.

POP3 et POP3S utilisent tous deux le protocole de transfert TCP.

I-A-4 - IMAP (Internet Message Access Protocol)

Le protocole IMAP, Internet Message Access Protocol est un protocole qui permet de récupérer les courriers électroniques déposés sur des serveurs de messagerie. Son but est donc similaire à POP3, l'autre principal protocole de relève du courrier. Mais contrairement à ce dernier, il a été conçu pour permettre de laisser les messages sur le serveur (nous verrons le fonctionnement et les différences plus tard).

Il comporte des fonctionnalités avancées comme la possibilité de créer des dossiers ou de manipuler les messages directement sur le serveur. Il offre aussi la possibilité de trier ses courriels sur le serveur. Le langage Sieve a été conçu pour permettre de filtrer des messages sur des serveurs sur lesquels l'utilisateur n'a pas le droit d'exécuter des tâches.

Le fait que les messages soient archivés sur le serveur fait que l'utilisateur peut y accéder depuis n'importe où sur le réseau et que l'administrateur peut facilement faire des copies de sauvegarde.

IMAP utilise le port TCP 143. L'utilisation de TLS permet l'accès sécurisé au serveur. La RFC 2595, qui décrit le fonctionnement de TLS avec IMAP, déconseille l'utilisation du port 993 qui avait été préalablement enregistré pour IMAPS (IMAP over SSL).

I-B - Communications entre serveurs de messageries

Comme tout serveur, les communications entre serveurs de messageries et postes se font via un protocole bien défini. Dans notre cas, il existe deux protocoles :

- IMAP ;

- POP3.

Donc avant d'établir une connexion à un serveur de messagerie, vous devez impérativement connaître le protocole que celui-ci utilise, sinon ce n'est pas la peine de continuer, car la connexion échouerait.

Quand vous allez établir une connexion, vous pouvez sélectionner un dossier. Il s'agit du dossier dans lequel vous souhaitez lire les mails. Vous pouvez donc créer autant de variables que vous voulez contenant des noms de dossiers différents pour changer de dossier 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éés autant que bon lui semble.

Il existe un dossier INBOX, qui correspond au dossier où les messages entrants arrivent par défaut. Nous sélectionnerons donc toujours ce dossier lors d'une première connexion.

I-C - Les différences entre IMAP et POP

POP et Imap sont tous deux des protocoles permettant de récupérer les courriers électroniques situés sur un serveur de messagerie électronique avec quelques différences.

La principale différence entre les deux est que :

- POP (POP3) :

- il télécharge le message complet depuis le serveur jusque votre client mail ;

- IMAP :

- il télécharge seulement les en-têtes (le nom de l'expéditeur, l'objet et diverses informations concernant l'e‑mail),

- l'inconvénient est qu'IMAP requiert une connexion permanente. Cependant de nombreux clients de messagerie proposent un mode hors ligne pour pallier ce problème. D'autre part, il limite l'utilisation de la capacité du réseau, car il permet de ne récupérer qu'une partie des messages (par exemple les en-têtes, sans le corps du message). Les messages peuvent être déplacés ou effacés sans être entièrement récupérés par le client,

- avec IMAP tout est répercuté sur le serveur. Supprimer, répondre à un message côté client avec IMAP, la suppression, la réponse ou autres seront également sur le serveur.

De nos jours beaucoup d'antivirus vérifient les pièces jointes avant de les télécharger.

II - Liste des fonctions

- imap_8bit - convertit une chaîne à 8 bits en une chaîne encodée en Quoted-Printable.

- imap_alerts - retourne toutes les alertes.

- imap_append - ajoute un message dans une boîte aux lettres.

- imap_base64 - décode un texte encodé en BASE64.

- imap_binary - convertit une chaîne à 8 bits en une chaîne à base64.

- imap_body - lit le corps d'un message.

- imap_bodystruct - lit la structure d'une section du corps d'un mail.

- imap_check - vérifie la boîte aux lettres courante.

- imap_clearflag_full - supprime un flag (drapeau) sur un message.

- imap_close - termine un flux IMAP.

- imap_create - alias de imap_createmailbox.

- imap_createmailbox - crée une nouvelle boîte aux lettres.

- imap_delete - marque le fichier pour l'effacement, dans la boîte aux lettres courante.

- imap_deletemailbox - efface une boîte aux lettres.

- imap_errors - retourne toutes les erreurs IMAP survenues.

- imap_expunge - efface tous les messages marqués pour l'effacement.

- imap_fetch_overview - lit le sommaire des en-têtes de messages.

- imap_fetchbody - retourne une section extraite du corps d'un message.

- imap_fetchheader - retourne l'en-tête d'un message.

- imap_fetchmime - récupère les en-têtes MIME pour une section particulière du message.

- imap_fetchstructure - lit la structure d'un message.

- imap_fetchtext - alias de imap_body.

- imap_gc - efface le cache IMAP.

- imap_get_quota - lit les quotas des boîtes aux lettres ainsi que des statistiques sur chacune d'elles.

- imap_get_quotaroot - lit les quotas de chaque utilisateur.

- imap_getacl - retourne le ACL pour la boîte aux lettres.

- imap_getmailboxes - liste les boîtes aux lettres, et retourne les détails de chacune.

- imap_getsubscribed - liste toutes les boîtes aux lettres souscrites.

- imap_header - alias de imap_headerinfo.

- imap_headerinfo - lit l'en-tête du message.

- imap_headers - retourne les en-têtes de tous les messages d'une boîte aux lettres.

- imap_last_error - retourne la dernière erreur survenue.

- imap_list - lit la liste des boîtes aux lettres.

- imap_listmailbox - alias de imap_list.

- imap_listscan - lit la liste des boîtes aux lettres, et y recherche une chaîne.

- imap_listsubscribed - alias de imap_lsub.

- imap_lsub - liste toutes les boîtes aux lettres enregistrées.

- imap_mail_compose - crée un message MIME.

- imap_mail_copy - copie les messages spécifiés dans une boîte aux lettres.

- imap_mail_move - déplace des messages dans une boîte aux lettres.

- imap_mail - envoie un message mail.

- imap_mailboxmsginfo - lit les informations à propos de la boîte aux lettres courante.

- imap_mime_header_decode - décode les éléments MIME d'un en-tête.

- imap_msgno - retourne le numéro de séquence du message pour un UID donné.

- imap_num_msg - retourne le nombre de messages dans la boîte aux lettres courante.

- imap_num_recent - retourne le nombre de messages récents dans la boîte aux lettres courante.

- imap_open - ouvre un flux IMAP vers une boîte aux lettres.

- imap_ping - vérifie que le flux IMAP est toujours actif.

- imap_qprint - convertit une chaîne à guillemets en une chaîne à 8 bits.

- imap_rename - alias de imap_renamemailbox.

- imap_renamemailbox - renomme une boîte aux lettres.

- imap_reopen - rouvre un flux IMAP vers une nouvelle boîte aux lettres.

- imap_rfc822_parse_adrlist - analyse une adresse e‑mail.

- imap_rfc822_parse_headers - analyse un en-tête mail.

- imap_rfc822_write_address - retourne une adresse e‑mail formatée correctement.

- imap_savebody - sauvegarde une partie spécifique du corps dans un fichier.

- imap_scan - alias de imap_listscan.

- imap_scanmailbox - alias de imap_listscan.

- imap_search - retourne un tableau de messages après recherche.

- imap_set_quota - modifie le quota d'une boîte aux lettres.

- imap_setacl - modifie le ACL de la boîte aux lettres.

- imap_setflag_full - positionne un drapeau sur un message.

- imap_sort - trie des messages.

- imap_status - retourne les informations de statut sur une boîte aux lettres.

- imap_subscribe - souscrit à une boîte aux lettres.

- imap_thread - retourne l'arbre des messages organisés par thread.

- imap_timeout - configure ou retourne le timeout.

- imap_uid - retourne l'UID d'un message.

- imap_undelete - enlève la marque d'effacement d'un message.

- imap_unsubscribe - termine la souscription à une boîte aux lettres.

- imap_utf7_decode - décode une chaîne encodée en UTF-7 modifié.

- imap_utf7_encode - convertit une chaîne ISO-8859-1 en texte UTF-7 modifié.

- imap_utf8 - convertit du texte au format MIME en UTF-8.

III - États d'une session IMAP

Une session IMAP peut se trouver dans quatre états différents.
Les commandes sont valides seulement dans certains états (voir ci-dessous).
Exemple si un client qui tente d'exécuter une commande qui n'est pas valide dans l'état actuel commet une erreur de protocole. Dans une telle situation, le serveur répondra par une réponse NO ou BAD (suivant l'implémentation). Et dans le cas où l'opération s'est déroulée avec succès OK.

III-A - Types de réponses

Il y a trois réponses de commande possibles :
- " OK : indique que l'opération s'est déroulée avec succès ;
- " NO : indique que l'opération a échoué ;
- " BAD : indique une erreur de protocole, comme une commande non reconnue ou une erreur de syntaxe.

III-B - État non authentifié (non-authentificated)

Dans l'état non authentifié, le client doit fournir une authentification correcte avant que la plupart des commandes ne soient permises. Le serveur entre dans cet état lorsqu'une connexion qui n'a pas été préauthentifiée commence.

III-C - État authentifié (authentificated)

Dans l'état authentifié, le client est authentifié et doit sélectionner une boîte aux lettres à laquelle accéder avant que les commandes opérant sur les messages soient autorisées. Le serveur entre dans cet état lorsqu'une connexion préauthentifiée est ouverte, lorsqu'une authentification correcte a été fournie ou encore lorsqu'une erreur s'est produite lors de la sélection de la boîte aux lettres.

III-D - État sélectionné (selected)

Dans l'état sélectionné, une boîte aux lettres à laquelle il est possible d'accéder a été sélectionnée. Le serveur entre dans cet état lorsqu'une boîte aux lettres a été correctement sélectionnée.

III-E - État déconnexion (logout)

Dans l'état déconnexion, la connexion se termine et le serveur ferme cette connexion. Le serveur entre dans cet état suite à une requête d'un client ou suite à une décision unilatérale.

III-F - Diagramme d'états-transitions

(1) connexion sans préauthentification (OK greeting).
(2) connexion préauthentifiée (PREAUTH greeting).
(3) connexion rejetée (BYE greeting).
(4) commande LOGIN ou AUTHENTICATE complétée avec succès.
(5) commande SELECT ou EXAMINE complétée avec succès.
(6) commande CLOSE, ou échec de la commande SELECT ou EXAMINE.
(7) commande LOGOUT, arrêt du serveur, ou fermeture de connexion .Utilisation.

III-G - Première connexion

III-G-1 - imap_open

III-G-1-a - Description

imap_open - ouvre un flux IMAP vers une boîte aux lettres.

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 :
- $mailbox ;
- $username ;
- $password.

Les trois premiers suffisent à une bonne prise en main pour les autres voici la documentation :

http://fr.php.net/imap_open.

III-G-1-b - Liste des paramètres

$mailbox

Un nom de boîte aux lettres est constitué d'une adresse de serveur, et d'une adresse de boîte sur ce serveur. Le mot réservé INBOX représente la boîte aux lettres de l'utilisateur courant. Les noms de boîtes aux lettres qui contiennent des caractères spéciaux (en dehors de l'espace ASCII) doivent être encodés avec imap_utf7_encode().

L'adresse du serveur, mise entre accolades '{' et '}', est constituée du nom du serveur ou de son adresse IP, d'une spécification de protocole (commençant par '/') et d'un port optionnel (spécifié avec ':').

Cette partie est obligatoire dans les paramètres de la boîte aux lettres.

Tous les noms commençant par { sont des noms distants et sont sous la forme "{" nom_systeme_distant [":" port] [flags] "}" [nom_mailbox] où :

- remote_system_name : Nom de domaine Internet ou une adresse IP de serveur entouré de guillemets ;

- port : numéro de port TCP (optionnel), la valeur par défaut est la valeur du port pour ce service ;

- flags : optionnel, voir la documentation http://fr.php.net/imap_open;

- mailbox_name : nom de la mailbox distante, par défaut : INBOX.

Exemples

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ères doit être construite 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ères correspondant au mot de passe de l'utilisateur indiqué dans le paramètre précédent.

III-G-1-c - Valeurs de retour

Retourne un flux IMAP en cas de succès, ou FALSE si une erreur survient.

III-G-1-d - Exemple

<?php
/*
$mailbox = '{' adresse du serveur ':' numéro de port '/' protocole '}' nom du dossier (par défaut INBOX)
$username = mon.nom@free.fr
$password = monMDP
*/
/* Avec variable */
imap_open("{pop3.free.fr:143/pop3}INBOX","mon.nom@free.fr","monMDP");

/* Sans variable en « dur » */
imap_open("{$mailbox}INBOX","$username","$password");
?>

III-H - Test de la connexion et fermeture de celle-ci

III-H-1 - Description

bool imap_close ( resource $imap_stream [, int $flag = 0 ] )

Termine un flux IMAP.

http://fr2.php.net/manual/fr/function.imap-close.php.

III-H-2 - Liste des paramètres

imap_stream : un flux IMAP retourné par la fonction imap_open().

Pour le flag se reporter à la documentation :
http://fr2.php.net/manual/fr/function.imap-close.php.

III-H-3 - Valeurs de retour

Cette fonction retourne TRUE en cas de succès ou FALSE si une erreur survient.

III-H-4 - Exemple

<?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) // Échec
{
echo "La connexion a échoué.";
}
else // Connexion établie
{
echo "Connexion établie.";

// On utilise imap_close() pour fermer la connexion avec en paramètre la ressource retournée par imap_open()
$imapClose = imap_close($imapLink);

if(!$imapClose) // Échec
{
echo "La fermeture a échoué.";
}
else
{
echo "Fermeture de la connexion réussie.";
}
}
?>

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 établi votre connexion à un serveur de messagerie avec succès.

III-I - Récupérer des informations sur la boîte de messagerie

III-I-1 - Description

Object imap_check ( resource $imap_stream ).

Vérifie les informations de la boîte aux lettres courante.

http://fr.php.net/manual/fr/function.imap-check.php.

III-I-2 - Liste des paramètres

imap_stream : un flux IMAP retourné par la fonction imap_open().

III-I-3 - Valeurs de retour

Retourne les informations dans un objet contenant les propriétés suivantes :

- Date - date de dernière modification du contenu de la boîte aux lettres en accord avec la »RFC2822 ;

- Driver - protocole utilisé pour accéder à la boîte aux lettres : POP3, IMAP, NNTP ;

- Mailbox - nom de la boîte aux lettres ;

- Nmsgs - nombre de messages de la boîte aux lettres ;

- Recent - nombre de messages récents de la boîte aux lettres.

Retourne FALSE si une erreur survient.

III-I-4 - Exemple

<?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) // Échec
{
echo "La connexion a échoué.";
}
else // Connexion établie
{
echo "Connexion établie.";

// On récupère les informations
$mailBoxInfos = imap_check($imapLink);

if(!$mailBoxInfos) // Échec
{
echo "La récupération a échoué.";
}
else // On affiche ces informations
{
echo "Lecture des informations...";
echo '<pre>';
print_r($mailBoxInfos);
// var_dump($mailBoxInfos);
echo '</pre>';
}

// On utilise imap_close() pour fermer la connexion avec en paramètre la ressource retournée par imap_open()
$imapClose = imap_close($imapLink);

if(!$imapClose) // Échec
{
echo "La fermeture a échoué.";
}
else
{
echo "Fermeture de la connexion réussie.";
}
}
?>

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 établi votre connexion à un serveur de messagerie, vous avez lu des informations, avec succès.

(*) Avec le print_r ou le var_dump vous obtiendrez un objet contenant ceci :

Connexion établie.

Lecture des informations ...
/* print_r */
stdClass Object
(
[Date] => Mon, 24 Jun 2013 14:51:32 +0100 (CET)
[Driver] => pop3
[Mailbox] => {pop3.free.fr:143/pop3/user="mon.nom@free.fr"}INBOX
[Nmsgs] => 9
[Recent] => 9
)
/* var_dump */
object(stdClass)(5)
{
["Date"]=>
string(37) "Mon, 24 Jun 2013 14:51:54 +0100 (CET)"
["Driver"]=>
string(4) "imap"
["Mailbox"]=>
string(54)
"{www.example.com:143/imap/user="foo@example.com"}INBOX"
["Nmsgs"]=>
int(1)
["Recent"]=>
int(0)
}

III-J - Récupération de la liste des messages

III-J-1 - Description

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

Lit les s des courriers électroniques de la séquence sequence et retourne un sommaire de leur contenu.

http://fr.php.net/manual/fr/function.imap-fetch-overview.php.

III-J-2 - Liste des paramètres

imap_stream

Un flux IMAP retourné par la fonction imap_open().

sequence

Une description de la séquence du message. Vous pouvez énumérer les messages désirés avec la syntaxe X,Y, ou récupérer tous les messages d'un intervalle, avec la syntaxe X:Y.

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

options

sequence va contenir une séquence d'indice de message ou d'UID, si flags contient FT_UID.

III-J-3 - Valeurs de retour

Retourne un tableau d'objets décrivant l'en-tête de chaque message. L'objet ne définira une propriété que si elle existe. Les propriétés possibles sont :

- subject : le sujet du message ;

- from : l'expéditeur ;

- to : le destinataire ;

- date : la date d'expédition ;

- message_id : l'identification du message ;

- references : la référence sur l'id de ce message ;

- in_reply_to : la réponse à cet identifiant de message ;

- size : la taille en octets ;

- uid : UID du message dans la boîte aux lettres ;

- msgno : le numéro de séquence du message dans la boîte ;

- recent : ce message est récent ;

- flagged : ce message est marqué ;

- answered : ce message a donné lieu à une réponse ;

- deleted : ce message est marqué pour l'effacement ;

- seen : ce message est déjà lu ;

- draft : ce message est un brouillon.

III-J-4 - Exemple

<?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) // Échec
{
echo "La connexion a échoué.";
}
else // Connexion établie
{
echo "Connexion établie.";

// On récupère les informations
$mailBoxInfos = imap_check($imapLink);

if(!$mailBoxInfos) // Échec
{
echo "La récupération a échoué.";
}
else // On affiche ces informations
{
echo "Lecture des informations...";
echo '<pre>';
print_r($mailBoxInfos);
// var_dump($mailBoxInfos);
echo '</pre>';

// On récupère la liste des messages
$mailList = imap_fetch_overview($imapLink,"0:".$mailBoxInfos->Nmsgs);

if(isset($mailList) // La variable existe
{
echo "Récupération de la liste des messages...";
echo '<pre>';
print_r($mailList);
echo '</pre>';
}
else
{
echo "La récupération de la liste des messages a échoué.";
}
}

// On utilise imap_close() pour fermer la connexion avec en paramètre la ressource retournée par imap_open()
$imapClose = imap_close($imapLink);

if(!$imapClose) // Échec
{
echo "La fermeture a échoué.";
}
else
{
echo "Fermeture de la connexion réussie.";
}
}
?>

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, (*), Récupération de la liste des messages…, [Votre_Liste], fermeture de la connexion. », vous avez établi votre connexion à un serveur de messagerie, vous avez lu des informations et récupéré la liste des messages, avec succès.

III-K - Télécharger le corps d'un message

III-K-1 - Description

bool imap_body ( resource $imap_stream , int $msg_number [, int $options = 0 ] ).

imap_body() retourne le corps du message numéro msg_number de la boîte aux lettres courante.

imap_body() va retourner une copie brute du corps du message. Pour extraire les sous-parties MIME du message, utilisez imap_fetchstructure() pour analyser la structure, et imap_fetchbody() pour extraire une copie d'une des sous-parties.

http://fr.php.net/manual/fr/function.imap-body.php.

III-K-2 - Liste des paramètres

imap_stream

Un flux IMAP retourné par la fonction imap_open().

msg_number

Le numéro du message.

options

Le paramètre options optionnel est un masque qui peut contenir les valeurs suivantes :

- FT_UID - msg_number est un UID ;

- FT_PEEK - ne pas lever le drapeau \Seen (Message lu) s'il n'est pas déjà levé ;

- FT_INTERNAL - la chaîne renvoyée est au format interne, et ne va pas canoniser les CRLF.

III-K-3 - Valeurs de retour

Retourne le corps du message spécifié, sous la forme d'une chaîne de caractères.

III-K-4 - Exemple

<?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) // Échec
{
echo "La connexion a échoué.";
}
else // Connexion établie
{
echo "Connexion établie.";

// On récupère les informations
$mailBoxInfos = imap_check($imapLink);

if(!$mailBoxInfos) // Échec
{
echo "La récupération a échoué.";
}
else // On affiche ces informations
{
echo "Lecture des informations &#8230;";
echo '<pre>';
print_r($mailBoxInfos);
// var_dump($mailBoxInfos);
echo '</pre>';

// On récupère la liste des messages
$mailList = imap_fetch_overview($imapLink,"0:".$mailBoxInfos->Nmsgs);

if(isset($mailList) // La variable existe
{
echo "Récupération de la liste des messages...";
echo '<pre>';
print_r($mailList);
echo '</pre>';

$nombreMessage = imap_num_msg($imapLink); // Retourne le nombre de messages dans la boîte aux lettres courante

while($nombreMessage > 0) // Si seulement il y a des messages on les affiche
{
$corpsMail = imap_body($imapLink, $nombreMessage);
if($corpsMail == null)
{
echo "Le corps du message est vide...";
}
else
{
echo 'Récupération du corps du '.$nombreMessage.' message...';
echo '<pre>';
print_r($corpsMail);
echo '</pre>';
$nombreMessage--;
}
}
}
else
{
echo "La récupération de la liste des messages a échoué.";
}
}

// On utilise imap_close() pour fermer la connexion avec en paramètre la ressource retournée par imap_open()
$imapClose = imap_close($imapLink);

if(!$imapClose) // Échec
{
echo "La fermeture a échoué.";
}
else
{
echo "Fermeture de la connexion réussie.";
}
}
?>

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, (*), Récupération de la liste des messages …, [Votre_Liste], fermeture de la connexion. », vous avez établi votre connexion à un serveur de messagerie, vous avez lu des informations et récupéré la liste des messages, avec succès.

IV - Conclusion

Vous voici prêt à créer un Webmail avec IMAP.

Pour vous améliorer, rien de mieux que la documentation officielle donnée au début de l'article :

- http://fr.php.net/manual/fr/book.imap.php.

Si vous voulez en savoir un peu plus sur les protocoles de messagerie, je vous conseille les trois cours suivants :

- Le protocole de messagerie IMAP ;

- Le protocole de messagerie POP3 ;

- Le protocole de messagerie SMTP.

V - Remerciement

Merci à :

- Claude Leloup d'avoir relu et corrigé ce cours ;

- Djibril, zoom61 et bovino de m'avoir guidé pour la création mise en place de ce cours.