repo_zf1/documentation/manual/fr/module_specs/Zend_Mail_Read.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.mail.read">
    <title>Lire des courriels</title>

    <para>
        <classname>Zend_Mail</classname> peut lire des courriels provenant de différents stockages
        locaux ou distants. Tous bénéficient de la même <acronym>API</acronym> pour compter et extraire les messages,
        certains implémentent des interfaces additionnelles pour des fonctionnalités moins communes.
        Pour une vue d'ensemble des fonctionnalités des stockages implémentés voir la table
        suivante.
    </para>

    <table id="zend.mail.read.table-1">
        <title>Vue d'ensemble des fonctionnalités de lecture de courriels</title>

        <tgroup cols="5">
            <thead>
                <row>
                    <entry>Fonctionnalité</entry>
                    <entry>Mbox</entry>
                    <entry>Maildir</entry>
                    <entry>Pop3</entry>
                    <entry>IMAP</entry>
                </row>
            </thead>

            <tbody>
                <row>
                    <entry>Type de stockage</entry>
                    <entry>local</entry>
                    <entry>local</entry>
                    <entry>distant</entry>
                    <entry>distant</entry>
                </row>

                <row>
                    <entry>Extraction des messages</entry>
                    <entry>Oui</entry>
                    <entry>Oui</entry>
                    <entry>Oui</entry>
                    <entry>Oui</entry>
                </row>

                <row>
                    <entry>Extraction des parties mimes</entry>
                    <entry>émulé</entry>
                    <entry>émulé</entry>
                    <entry>émulé</entry>
                    <entry>émulé</entry>
                </row>

                <row>
                    <entry>Dossiers</entry>
                    <entry>Oui</entry>
                    <entry>Oui</entry>
                    <entry>Non</entry>
                    <entry>Oui</entry>
                </row>

                <row>
                    <entry>Créer des messages/dossiers</entry>
                    <entry>Non</entry>
                    <entry>A faire</entry>
                    <entry>Non</entry>
                    <entry>A faire</entry>
                </row>

                <row>
                    <entry>Flags</entry>
                    <entry>Non</entry>
                    <entry>Oui</entry>
                    <entry>Non</entry>
                    <entry>Oui</entry>
                </row>

                <row>
                    <entry>Quota</entry>
                    <entry>Non</entry>
                    <entry>Oui</entry>
                    <entry>Non</entry>
                    <entry>Non</entry>
                </row>
            </tbody>
        </tgroup>
    </table>

    <sect2 id="zend.mail.read-example">
        <title>Exemple simple avec Pop3</title>

        <programlisting language="php"><![CDATA[
$mail = new Zend_Mail_Storage_Pop3(array('host'     => 'localhost',
                                         'user'     => 'test',
                                         'password' => 'test'));

echo $mail->countMessages() . " messages trouvés\n";
foreach ($mail as $message) {
    echo "Mail from '{$message->from}': {$message->subject}\n";
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.mail.read-open-local">
        <title>Ouvrir un stockage local</title>

        <para>
            Mbox et Maildir sont les deux formats supportés pour le stockage local des courriels,
            tous les deux dans leurs formats le plus simple.
        </para>

        <para>
            Si vous voulez lire un fichier Mbox, vous devez juste donner le nom du fichier au
            constructeur de <classname>Zend_Mail_Storage_Mbox</classname>:
        </para>

        <programlisting language="php"><![CDATA[
$mail =
    new Zend_Mail_Storage_Mbox(array('filename' => '/home/test/mail/inbox'));
]]></programlisting>

        <para>Maildir est très similaire mais nécessite un nom de dossier :</para>

        <programlisting language="php"><![CDATA[
$mail =
    new Zend_Mail_Storage_Maildir(array('dirname' => '/home/test/mail/'));
]]></programlisting>

        <para>
            Ces deux constructeurs lèvent une exception
            <classname>Zend_Mail_Exception</classname> si le stockage ne peut pas être lu.
        </para>
    </sect2>

    <sect2 id="zend.mail.read-open-remote">
        <title>Ouvrir un stockage distant</title>

        <para>
            Pour les stockages distants les deux protocoles les plus populaires sont supportés
            : Pop3 et Imap. Les deux nécessitent au moins un hôte et un utilisateur pour se
            connecter et s'identifier. Le mot de passe par défaut est une chaîne vide et le port par
            défaut celui donné dans la <acronym>RFC</acronym> du protocole.
        </para>

        <programlisting language="php"><![CDATA[
// connexion à Pop3
$mail = new Zend_Mail_Storage_Pop3(array('host'     => 'exemple.com'
                                         'user'     => 'test',
                                         'password' => 'test'));

// connexion à Imap
$mail = new Zend_Mail_Storage_Imap(array('host'     => 'exemple.com'
                                         'user'     => 'test',
                                         'password' => 'test'));

// exemple à un port non standard
$mail = new Zend_Mail_Storage_Pop3(array('host'     => 'exemple.com',
                                         'port'     => 1120
                                         'user'     => 'test',
                                         'password' => 'test'));
]]></programlisting>

        <para>
            Pour ces deux stockages <acronym>SSL</acronym> et TLS sont supportés. Si vous utilisez <acronym>SSL</acronym> le port
            par défaut change comme indiqué dans la <acronym>RFC</acronym>.
        </para>

        <programlisting language="php"><![CDATA[
// exemples pour Zend_Mail_Storage_Pop3,
// identique à Zend_Mail_Storage_Imap

// utiliser SSL avec un port différent
// (par défaut 995 pour Pop3 et 993 pour Imap)
$mail = new Zend_Mail_Storage_Pop3(array('host'     => 'exemple.com'
                                         'user'     => 'test',
                                         'password' => 'test',
                                         'ssl'      => 'SSL'));

// utiliser TLS
$mail = new Zend_Mail_Storage_Pop3(array('host'     => 'exemple.com'
                                         'user'     => 'test',
                                         'password' => 'test',
                                         'ssl'      => 'TLS'));
]]></programlisting>

        <para>
            Les deux constructeurs peuvent lever une exception
            <classname>Zend_Mail_Exception</classname> ou
            <classname>Zend_Mail_Protocol_Exception</classname>(étendant
            <classname>Zend_Mail_Exception</classname>), en fonction du type de l'erreur.
        </para>
    </sect2>

    <sect2 id="zend.mail.read-fetching">
        <title>Extraire des messages et autres méthodes simples</title>

        <para>
            Dès que vous avez ouvert l'accès, les messages peuvent être extraits. Vous devez
            fournir un numéro de message, qui est un compteur qui démarre à 1 pour le premier
            message. Pour extraire le message vous utilisez la méthode <methodname>getMessage()</methodname>
            :
        </para>

        <programlisting language="php"><![CDATA[
$message = $mail->getMessage($numeroDeMessage);
]]></programlisting>

        <para>
            L'accès sous forme de tableau est aussi supporté, mais cet méthode d'accès ne
            supporte pas les paramètres additionnels qui aurait pu être ajouté à
            <methodname>getMessage()</methodname>. Tant que vous n'en n'avez pas besoin et que vous pouvez vivre
            avec les valeurs par défaut, vous pouvez utiliser :
        </para>

        <programlisting language="php"><![CDATA[
$message = $mail[$numeroDeMessage];
]]></programlisting>

        <para>
            Pour itérer tous les messages, l'interface <code>Iterator</code> est implémentée
            :
        </para>

        <programlisting language="php"><![CDATA[
foreach ($mail as $numeroDeMessage => $message) {
    // faire qqch ...
}
]]></programlisting>

        <para>
            Pour compter les messages dans le stockage, vous pouvez soit utiliser la méthode
            <methodname>countMessages()</methodname> ou utiliser l'accès de type tableau :
        </para>

        <programlisting language="php"><![CDATA[
// par méthode
$maxMessage = $mail->countMessages();

// type tableau
$maxMessage = count($mail);
]]></programlisting>

        <para>
            Pour supprimer un mail vous pouvez utiliser la méthode
            <methodname>removeMessage()</methodname> ou l'accès de type tableau :
        </para>

        <programlisting language="php"><![CDATA[
// méthode
$mail->removeMessage($numeroDeMessage);

// type tableau
unset($mail[$messageNum]);
]]></programlisting>
    </sect2>

    <sect2 id="zend.mail.read-message">
        <title>Travailler avec les messages</title>

        <para>
            Après avoir extrait les messages avec <methodname>getMessage()</methodname> vous voulez
            extraire les en-têtes, le contenu ou une partie d'un message multipart. Tous les
            en-têtes peuvent être accédés via les propriétés ou la méthode <methodname>getHeader()</methodname>
            si vous voulez plus de contrôle ou avoir accès à des en-têtes peu communs. Les noms des
            en-têtes gérés en interne avec une casse minuscule, ainsi la casse du nom de l'en-tête
            importe peu. En outre les en-têtes avec un tiret-bas peuvent être écrit avec la <ulink
            url="http://en.wikipedia.org/wiki/CamelCase">notation Camel</ulink>. Si aucun en-tête
            n'est trouvé pour les deux notations, une exception est levée. Pour éviter ceci, la
            méthode <methodname>headerExists()</methodname> peut être utilisée pour vérifier l'existence d'un
            en-tête.
        </para>

        <programlisting language="php"><![CDATA[
// récupérer l'objet message
$message = $mail->getMessage(1);

// afficher le sujet du message
echo $message->subject . "\n";

// récupérer l'en-tête content-type
$type = $message->contentType;

// vérifier si CC est spécifié :
if( isset($message->cc) ) { // ou $message->headerExists('cc');
    $cc = $message->cc;
}
]]></programlisting>

        <para>
            Si vous avez plusieurs en-têtes avec le même nom, par exemple les en-têtes
            "Received", vous pourriez les vouloir sous la forme d'un tableau plutôt qu'en tant que
            chaîne. Ceci est possible avec la méthode <methodname>getHeader()</methodname>.
        </para>

        <programlisting language="php"><![CDATA[
// récupérer l'en-tête comme une propriété - le résultat est toujours
// une chaîne, avec de nouvelles lignes entre chaque occurence
// dans le message
$received = $message->received;

// la même chose avec la méthode getHeader()
$received = $message->getHeader('received', 'string');

// ou mieux un tableau avec une entrée pour chaque occurence
$received = $message->getHeader('received', 'array');
foreach ($received as $line) {
    // faire qqch
}

// si vous ne définissez pas de format vous récupérerez la représentation
// interne (chaîne pour en-têtes uniques, tableau pour en-têtes multiples
$received = $message->getHeader('received');
if (is_string($received)) {
    // seulement un en-tête received trouvé dans le message
}
]]></programlisting>

        <para>
            La méthode <methodname>getHeaders()</methodname> retourne tous les headers sous forme de
            tableau avec des clés en minuscules et des valeurs en tant que tableau pour des en-têtes
            multiples ou une chaîne pour des en-têtes uniques.
        </para>

        <programlisting language="php"><![CDATA[
// récupère tous les en-têtes
foreach ($message->getHeaders() as $name => $value) {
    if (is_string($value)) {
        echo "$name: $value\n";
        continue;
    }
    foreach ($value as $entry) {
        echo "$name: $entry\n";
    }
}
]]></programlisting>

        <para>
            Si vous n'avez pas de message de type multipart, extraire le contenu est facilité
            avec <methodname>getContent()</methodname>. A la différence des en-têtes, le contenu est seulement
            extrait en cas de besoin (alias late-fetch).
        </para>

        <programlisting language="php"><![CDATA[
// affiche le contenu du message
echo '<pre>';
echo $message->getContent();
echo '</pre>';
]]></programlisting>

        <para>
            Vérifier si un message est de type multipart est réalisé avec la méthode
            <methodname>isMultipart()</methodname>. Si vous avez un message de type multipart vous pouvez
            récupérer une instance de <classname>Zend_Mail_Part</classname> avec la méthode
            <methodname>getPart()</methodname>. <classname>Zend_Mail_Part</classname> est la classe de base de
            <classname>Zend_Mail_Message</classname>, donc vous avez les mêmes méthodes :
            <methodname>getHeader()</methodname>, <methodname>getHeaders()</methodname>, <methodname>getContent()</methodname>,
            <methodname>getPart()</methodname>, <methodname>isMultipart()</methodname> et les propriétés pour les
            en-têtes.
        </para>

        <programlisting language="php"><![CDATA[
// récupérer la première partie non-multipart
$part = $message;
while ($part->isMultipart()) {
    $part = $message->getPart(1);
}
echo 'Le type de cette partie est '
   . strtok($part->contentType, ';')
   . "\n";
echo "Contenu :\n";
echo $part->getContent();
]]></programlisting>

        <para>
            <classname>Zend_Mail_Part</classname> implémente aussi
            <classname>RecursiveIterator</classname>, qui rend facile le scan de toutes les parties. Et pour
            un affichage facile, il implémente de plus la méthode magique <methodname>__toString()</methodname>
            qui retourne le contenu.
        </para>

        <programlisting language="php"><![CDATA[
// affiche la première partie de type text/plain=
$foundPart = null;
foreach (new RecursiveIteratorIterator($mail->getMessage(1)) as $part) {
    try {
        if (strtok($part->contentType, ';') == 'text/plain') {
            $foundPart = $part;
            break;
        }
    } catch (Zend_Mail_Exception $e) {
        // ignore
    }
}
if (!$foundPart) {
    echo 'Aucune partie "plain text" trouvés';
} else {
    echo "Partie \"plain text\" : \n" . $foundPart;
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.mail.read-flags">
        <title>Vérifier les drapeaux ("flags")</title>

        <para>
            Maildir et IMAP supporte l'enregistrement de drapeaux. La classe
            <classname>Zend_Mail_Storage</classname> possède des constantes pour tous les drapeaux
            maildir et IMAP connus, nommés
            <classname>Zend_Mail_Storage::FLAG_&lt;nomdudrapeau&gt;</classname>. Pour vérifier les
            drapeaux <classname>Zend_Mail_Message</classname> possède une méthode
            <methodname>hasFlag()</methodname>. Avec <methodname>getFlags()</methodname> vous récupérez tous les drapeaux
            existants.
        </para>

        <programlisting language="php"><![CDATA[
// trouvé les messages non lus
echo "Emails non lus :\n";
foreach ($mail as $message) {
    if ($message->hasFlag(Zend_Mail_Storage::FLAG_SEEN)) {
        continue;
    }
    // marque les emails récents/nouveaux
    if ($message->hasFlag(Zend_Mail_Storage::FLAG_RECENT)) {
        echo '! ';
    } else {
        echo '  ';
    }
    echo $message->subject . "\n";
}

// vérifie les drapeaux connus
$flags = $message->getFlags();
echo "Le message est marqué comme : ";
foreach ($flags as $flag) {
    switch ($flag) {
        case Zend_Mail_Storage::FLAG_ANSWERED:
            echo 'Réponse ';
            break;
        case Zend_Mail_Storage::FLAG_FLAGGED:
            echo 'Marqués ';
            break;

        // ...
        // vérifie d'autres drapeaux
        // ...

        default:
            echo $flag . '(drapeau inconnu) ';
    }
}
]]></programlisting>

        <para>
            Comme IMAP autorise les drapeaux définis par client ou l'utilisateur, vous pouvez
            obtenir ces drapeaux même s'ils n'ont pas de constante dans
            <classname>Zend_Mail_Storage</classname>. Au lieu de cela ils sont retournés comme une
            chaîne et peuvent être vérifiés de la même manière avec <methodname>hasFlag()</methodname>.
        </para>

        <programlisting language="php"><![CDATA[
// Vérifie le message avec les drapeaux $EstUnSpam, $SpamTeste
if (!$message->hasFlag('$SpamTeste')) {
    echo 'ce message n\'est pas considéré comme un spam';
} else if ($message->hasFlag('$EstUnSpam')) {
    echo 'ce message est un spam';
} else {
    echo 'ce message est sûr';
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.mail.read-folders">
        <title>Utiliser les dossiers</title>

        <para>
            Tous les stockages, excepté Pop3, supportent les dossiers, également appelés
            boîtes aux lettres. L'interface implémentée par tous les stockages supportant les
            dossiers s'appelle <classname>Zend_Mail_Storage_Folder_Interface</classname>. En outre
            toutes ces classes ont un paramètre facultatif additionnel appelé <property>folder</property>,
            qui est le dossier choisi après ouverture, dans le constructeur.
        </para>

        <para>
            Pour les stockages locaux vous devez employer les classes séparées appelées
            <classname>Zend_Mail_Storage_Folder_Mbox</classname> ou
            <classname>Zend_Mail_Storage_Folder_Maildir</classname>. Tous les deux ont besoin d'un
            paramètre nommé <property>dirname</property> avec le nom du dossier de base. Le format pour le
            maildir est comme définie dans maildir++ (avec un point comme délimiteur par défaut),
            Mbox est une hiérarchie de dossiers avec des fichiers Mbox. Si vous n'avez pas un
            dossier de Mbox appelé INBOX dans votre dossier de base Mbox vous devez placer un autre
            dossier dans le constructeur.
        </para>

        <para>
            <classname>Zend_Mail_Storage_Imap</classname> supporte déjà des dossiers par
            défaut. Exemples pour ouvrir ces stockages :
        </para>

        <programlisting language="php"><![CDATA[
// mbox avec dossiers
$mail = new Zend_Mail_Storage_Folder_Mbox(
            array('dirname' => '/home/test/mail/')
        );

// mbox avec un dossier par défaut nommé INBOX, fontionne aussi
// avec Zend_Mail_Storage_Folder_Maildir et Zend_Mail_Storage_Imap
$mail = new Zend_Mail_Storage_Folder_Mbox(
            array('dirname' => '/home/test/mail/', 'folder'  => 'Archive')
        );

// maildir avec dossiers
$mail = new Zend_Mail_Storage_Folder_Maildir(
            array('dirname' => '/home/test/mail/')
        );

// maildir avec deux-points comme délimiteur,
// comme suggéré dans Maildir++
$mail = new Zend_Mail_Storage_Folder_Maildir(
            array('dirname' => '/home/test/mail/', 'delim'   => ':')
        );

// imap est le même avec ou sans dossier
$mail = new Zend_Mail_Storage_Imap(array('host'     => 'example.com',
                                         'user'     => 'test',
                                         'password' => 'test'));
]]></programlisting>

        <para>
            Avec la méthode <methodname>getFolders($root = null)</methodname> vous pouvez obtenir la
            hiérarchie des dossiers en commençant par le dossier racine ou le dossier fourni. Elle
            est retournée comme instance de <classname>Zend_Mail_Storage_Folder</classname>, qui
            implémente <classname>RecursiveIterator</classname> et tous ses enfants sont également des
            instances de <classname>Zend_Mail_Storage_Folder</classname>. Chacune de ces instances à
            des noms locaux et globaux retournés par les méthodes <methodname>getLocalName()</methodname> et
            <methodname>getGlobalName()</methodname>. Le nom global est le nom absolu du dossier racine
            (délimiteurs y compris), le nom local est le nom dans le dossier parent.
        </para>

        <table id="zend.mail.read-folders.table-1">
            <title>Noms de dossiers</title>

            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Nom global</entry>
                        <entry>Nom local</entry>
                    </row>
                </thead>

                <tbody>
                    <row>
                        <entry>/INBOX</entry>
                        <entry>INBOX</entry>
                    </row>

                    <row>
                        <entry>/Archive/2005</entry>
                        <entry>2005</entry>
                    </row>

                    <row>
                        <entry>List.ZF.General</entry>
                        <entry>General</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            Si vous employez l'itérateur, la clé de l'élément courant est le nom local. Le nom
            global est également retourné par la méthode magique <methodname>__toString()</methodname>. Quelques
            dossiers peuvent ne pas être sélectionnables, ce qui veut dire qu'ils ne peuvent pas
            stocker des messages et les choisir entraînerait une erreur. Ceci peut être vérifié avec
            la méthode <methodname>isSelectable()</methodname>. Ainsi il est très facile de produire l'arbre
            entier dans une vue :
        </para>

        <programlisting language="php"><![CDATA[
$folders = new RecursiveIteratorIterator(
                    $this->mail->getFolders(),
                    RecursiveIteratorIterator::SELF_FIRST
                );
echo '<select name="folder">';
foreach ($folders as $localName => $folder) {
    $localName = str_pad('', $folders->getDepth(), '-', STR_PAD_LEFT)
               . $localName;
    echo '<option';
    if (!$folder->isSelectable()) {
        echo ' disabled="disabled"';
    }
    echo ' value="' . htmlspecialchars($folder) . '">'
        . htmlspecialchars($localName) . '</option>';
}
echo '</select>';
]]></programlisting>

        <para>
            Les dossiers choisis courants sont retournés par la méthode
            <methodname>getCurrentFolder()</methodname>. Changer de dossier est fait avec la méthode
            <methodname>selectFolder()</methodname>, qui a besoin du nom global comme paramètre. Si vous voulez
            éviter d'écrire des délimiteurs vous pouvez également employer les propriétés d'une
            instance de <classname>Zend_Mail_Storage_Folder</classname> :
        </para>

        <programlisting language="php"><![CDATA[
// selon votre stockage et ses réglages $rootFolder->Archive->2005
// est la même chose que :
//   /Archive/2005
//  Archive:2005
//  INBOX.Archive.2005
//  ...
$folder = $mail->getFolders()->Archive->2005;
echo 'Le précédent dossier était '
   . $mail->getCurrentFolder()
   . "Le nouveau dossier est $folder\n";
$mail->selectFolder($folder);
]]></programlisting>
    </sect2>

    <sect2 id="zend.mail.read-advanced">
        <title>Utilisation avancée</title>

        <sect3 id="zend.mail.read-advanced.noop">
            <title>Utiliser NOOP</title>

            <para>
                Si vous employez un stockage distant et avez une longue tâche vous pourriez
                devoir maintenir la connexion persistante par l'intermédiaire du noop :
            </para>

            <programlisting language="php"><![CDATA[
foreach ($mail as $message) {

    // faire qqch...

    $mail->noop(); // maintient la connexion

    // faire autre chose...

    $mail->noop(); // maintient la connexion
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.mail.read-advanced.extending">
            <title>Mettre en cache des instances</title>

            <para>
                <classname>Zend_Mail_Storage_Mbox</classname>,
                <classname>Zend_Mail_Storage_Folder_Mbox</classname>,
                <classname>Zend_Mail_Storage_Maildir</classname> et
                <classname>Zend_Mail_Storage_Folder_Maildir</classname> implémentant les méthodes
                magiques <methodname>__sleep()</methodname> et <methodname>__wakeup()</methodname>, ce qui veut dire qu'ils
                sont sérialisable. Ceci évite d'analyser les dossiers ou l'arbre des dossiers plus
                d'une fois. L'inconvénient est que votre stockage de Mbox ou de Maildir ne doit pas
                changer. Quelques contrôles faciles sont faits, comme ré-analyser le dossier courant
                de Mbox si le temps de modification change ou ré-analysé la structure du dossier si
                un dossier a disparu (ce qui a toujours comme conséquence une erreur, mais vous
                pouvez rechercher un autre dossier après). Il est meilleur si vous avez quelque
                chose comme un fichier de signal pour des changements et la vérifiez avant
                d'employer l'instance caché.
            </para>

            <programlisting language="php"><![CDATA[
// il n'y a pas de gestionnaire spécifique de cache utilisé ici,
// changer le code pour utiliser votre gestionnaire de cache
$signal_file = '/home/test/.mail.last_change';
$mbox_basedir = '/home/test/mail/';
$cache_id = 'exemple de mail en cache ' . $mbox_basedir . $signal_file;

$cache = new Your_Cache_Class();
if (!$cache->isCached($cache_id) ||
    filemtime($signal_file) > $cache->getMTime($cache_id)) {
    $mail = new Zend_Mail_Storage_Folder_Pop3(
                array('dirname' => $mbox_basedir)
            );
} else {
    $mail = $cache->get($cache_id);
}

// faire qqch ...

$cache->set($cache_id, $mail);
]]></programlisting>
        </sect3>

        <sect3>
            <title>Étendre les classes de protocoles</title>

            <para>
                Les stockages distants utilisent deux classes :
                <classname>Zend_Mail_Storage_&lt;NOM&gt;</classname> et
                <classname>Zend_Mail_Protocol_&lt;NOM&gt;</classname>. La classe de protocole
                traduit les commandes et les réponses de protocole et issu de ou pour <acronym>PHP</acronym>, comme des
                méthodes pour les commandes ou les variables avec différentes structures pour les
                données. L'autre/classe principale met en application l'interface commune.
            </para>

            <para>
                Si vous avez besoin de fonctionnalités additionnelles de protocole vous pouvez
                étendre la classe de protocole et l'employer dans le constructeur de la classe
                principale. Supposer par exemple que nous devons joindre différents ports avant que
                nous puissions nous relier à POP3.
            </para>

            <programlisting language="php"><![CDATA[
Zend_Loader::loadClass('Zend_Mail_Storage_Pop3');

class Example_Mail_Exception extends Zend_Mail_Exception
{}

class Example_Mail_Protocol_Exception extends Zend_Mail_Protocol_Exception
{}

class Example_Mail_Protocol_Pop3_Knock extends Zend_Mail_Protocol_Pop3
{
    private $host, $port;

    public function __construct($host, $port = null)
    {
        // pas d'auto-connexion dans cette classe
        $this->host = $host;
        $this->port = $port;
    }

    public function knock($port)
    {
        $sock = @fsockopen($this->host, $port);
        if ($sock) {
            fclose($sock);
        }
    }

    public function connect($host = null, $port = null, $ssl = false)
    {
        if ($host === null) {
            $host = $this->host;
        }
        if ($port === null) {
            $port = $this->port;
        }
        parent::connect($host, $port);
    }
}

class Example_Mail_Pop3_Knock extends Zend_Mail_Storage_Pop3
{
    public function __construct(array $params)
    {
        // ... vérifier les $params ici ! ...
        $protocol =
            new Example_Mail_Protocol_Pop3_Knock($params['host']);

        // faire votre fonction "spéciale"
        foreach ((array)$params['knock_ports'] as $port) {
            $protocol->knock($port);
        }

        // récupérer l'état coorect
        $protocol->connect($params['host'], $params['port']);
        $protocol->login($params['user'], $params['password']);

        // initialise le parent
        parent::__construct($protocol);
    }
}

$mail = new Example_Mail_Pop3_Knock(
            array('host'        => 'localhost',
                                   'user'        => 'test',
                                   'password'    => 'test',
                                   'knock_ports' => array(1101,
                                                          1105,
                                                          1111))
        );
]]></programlisting>

            <para>
                Comme vous voyez nous supposons toujours que nous sommes reliés, identifiés
                et, si supporté, un dossier est choisi dans le constructeur de la classe principale.
                Ainsi si vous assignez votre propre classe de protocole vous devez toujours vous
                assurer que c'est fait ou la prochaine méthode échouera si le serveur ne la permet
                pas dans l'état actuel.
            </para>
        </sect3>

        <sect3 id="zend.mail.read-advanced.quota">
            <title>Utilisation des Quotas (avant 1.5)</title>

            <para>
                <classname>Zend_Mail_Storage_Writable_Maildir</classname> supporte les quotas
                Maildir++. Ceci est désactivé par défaut, mais il est possible de l'utiliser
                manuellement, si la vérification automatique n'est pas souhaitée (ce qui veut dire
                que <methodname>appendMessage()</methodname>, <methodname>removeMessage()</methodname> et
                <methodname>copyMessage()</methodname> ne vérifie pas et n'ajoute pas d'entrée dans le fichier
                de contrôle de la taille du dossier de mails). Si vous l'activez une exception sera
                levée si vous tentez d'écrire dans le dossier de mails et qu'il a déjà atteint son
                quota.
            </para>

            <para>
                Il existe trois méthodes pour les quotas : <methodname>getQuota()</methodname>,
                <methodname>setQuota()</methodname> et <methodname>checkQuota()</methodname>:
            </para>

            <programlisting language="php"><![CDATA[
$mail = new Zend_Mail_Storage_Writable_Maildir(
            array('dirname' => '/home/test/mail/')
        );
$mail->setQuota(true); // true pour activer, false pour désactiver
echo 'La vérification du quota est maintenant ',
     $mail->getQuota() ? 'active' : 'inactive',
     "\n";
// la vérification du quota peut être utilisée
// si celle-ci est désactivée
echo 'Vous êtes ',
     $mail->checkQuota() ? 'hors quota' : 'dans le quota',
     "\n";
]]></programlisting>

            <para>
                <methodname>checkQuota()</methodname> peut aussi retournée une réponse plus détaillée
                :
            </para>

            <programlisting language="php"><![CDATA[
$quota = $mail->checkQuota(true);
echo 'Vous êtes ',
     $quota['over_quota'] ? 'hors quota' : 'dans le quota',
     "\n";
echo 'Vous avez ',
     $quota['count'],
     ' de ',
     $quota['quota']['count'],
     ' messages et vous utilisez ';
echo $quota['size'], ' de ', $quota['quota']['size'], ' octets';
]]></programlisting>

            <para>
                Si vous voulez spécifier votre propre quota plutôt que d'utiliser celui
                spécifié dans le fichier de contrôle de la taille du dossier de mails, vous pouvez
                le faire avec <methodname>setQuota()</methodname> :
            </para>

            <programlisting language="php"><![CDATA[
// le nombre de messages et la taille en octet sont supportés,
// l'ordre est important
$quota = $mail->setQuota(array('size' => 10000, 'count' => 100));
]]></programlisting>

            <para>
                Pour ajouter vos propres vérifications de quota, utilisez des caractères
                uniques en tant que clé et ils seront préservés (mais évidemment non vérifié). Il
                est aussi possible d'étendre
                <classname>Zend_Mail_Storage_Writable_Maildir</classname> pour définir votre propre
                quota seulement si le fichier de contrôle de la taille du dossier de mails est
                absent (qui peut se produire dans Maildir++) :
            </para>

            <programlisting language="php"><![CDATA[
class Exemple_Mail_Storage_Maildir extends Zend_Mail_Storage_Writable_Maildir {
    // getQuota est appelé avec $fromStorage = true
    // par la vérification de quota
    public function getQuota($fromStorage = false) {
        try {
            return parent::getQuota($fromStorage);
        } catch (Zend_Mail_Storage_Exception $e) {
            if (!$fromStorage) {
                // Erreur inconnue
                throw $e;
            }
            // le fichier de contrôle de la taille du dossier de mails
            // doit être absent

            list($count, $size) = get_un_autre_quota();
            return array('count' => $count, 'size' => $size);
        }
    }
}
]]></programlisting>
        </sect3>
    </sect2>
</sect1>