MIME::Lite

MIME::Lite a été initié en 1997 par Eryq, l'auteur des MIME::Tools. Le code est désormais maintenu par Yves Orton (demerphq).

Il faut savoir que MIME::Lite est une sous-branche de la branche MIME::* mais aussi une branche sœur (et non pas fille) des MIME::Tools. Par conséquent, elle n'en hérite pas et les objets MIME::Lite n'héritent donc pas des objets MIME::Entity. C'est assurément un manque mais, vous allez le voir, MIME::Lite sait faire plein de choses tout seul et se suffit bien souvent à lui-même.

Le principe général du module est simple : chaque objet MIME::Lite symbolise une partie MIME (section du courriel limitée par un boundary, cf. l'exemple de message MIME plus haut). Ainsi un bon nombre des méthodes de l'API tournent autour de l'initialisation, l'alimentation, la modification, l'accès aux attributs d'un objet MIME::Lite, attributs qui figureront pour la plupart les en-têtes, le texte, les fichiers joints du futur message.

Valeurs globales

Le comportement global du module au cours d'un script est configurable à travers quelques éléments de l'interface publique du module.

Il y a pour cela plusieurs méthodes de classe mais j'y reviendrai lors de l'évocation de ces méthodes. Il y a aussi des variables d'environnement mais leur positionnement par défaut est satisfaisant pour la majorité des emplois, à part pour une. Cependant cette variable est positionnée de façon à maintenir une compatibilité ascendante et la documentation vous suggère de la laisser en l'état. De toute façon, la fonctionnalité qui en découlait est accessible d'une autre façon au prix de quelques lignes de code supplémentaires deci-delà. (il s'agit de $MIME::Lite::AUTO_CONTENT_TYPE qui, lorsqu'elle est vraie, demande au module de déterminer le type de fichier, l'attribut content-type, à partir du nom du fichier joint)

Du reste de l'API, on peut retenir en particulier les méthodes qui suivent.

La méthode `new()`

Bien sûr, dans le cas d'un module orienté objet, il y a besoin d'un constructeur.

    $mime = MIME::Lite->new();

Cette méthode ne prend pas nécessairement d'argument. Dans ce cas, elle crée simplement un objet qui va nous permettre d'appeler des méthodes par la suite. Lorsqu'on fournit des arguments à cette méthode, ils ne lui sont en fait pas destinés. Le module suppose que, lorsque des arguments sont envoyés à la méthode new(), on lui demande en fait de construire un objet et que cet objet appelle la méthode build() avec les dits arguments.

La méthode `build()`

Les données passées en argument à cette méthode déterminent de quoi sera fait le message MIME (en-têtes, texte, pièces jointes).

Ces données sont parfois pré-traitées, pour appliquer notamment des comportements par défaut (vous permettant de ne pas avoir à tout savoir des spécifications MIME), avant de produire le message MIME dans son intégralité.

build() peut être appelée en tant que méthode d'instance ou méthode de classe. Dans le premier cas, le message est formé à partir des arguments, dans le second, un objet est créé préalablement avec new(), le message est ensuite formé avec build() et l'objet est finalement retourné.

Le nombre et le type des arguments qu'accepte cette méthode est assez conséquent. En voici une synthèse :

Les en-têtes de courriel
Toutes les en-têtes classiques sont acceptées comme argument, néanmoins l'auteur du module a prévu de considérer comme en-tête de courriel tout argument à cette méthode qui se terminerait par les deux points :.
```
    "X-Bizarre-Header:" => "valeur" # sera accepté
```
Il vous suffit donc de renseigner ces en-têtes à l'appel (direct ou implicite) de la méthode build() pour qu'ils figurent dans le courriel. A noter que les valeurs données aux en-têtes par le biais de cette méthode le sont après que le module a positionné les en-têtes MIME. Autrement dit, vous avez la possibilité de maîtriser ce qui est produit dans ce domaine (ou de faire des erreurs. A manipuler avec précaution donc...)
Data, FH et Path
Ce sont les trois options pour fournir les données à proprement parler (message, fichiers). Data est utilisé pour un scalaire ou une référence à une liste de scalaires (qui seront simplement concaténés). FH est (étonnamment ! ;-) utilisé avec un descripteur de fichier (FileHandle en anglais). Enfin Path convient à tout ce qui est ouvrable au sens de la fonction open(), c'est à dire un grand nombre de choses, mais principalement un fichier ou une commande.

Dans ce dernier cas, il est bon de connaître un autre argument, ReadNow, qui va lire une fois pour toutes le fichier ou la sortie de la commande, lui évitant d'être lu et lu et lu... à chaque appel de la méthode build().
Type
Cet argument va vous permettre de spécifier à quel type MIME la pièce jointe correspond. La chose est généralement assez triviale à déterminer mais vous pouvez vous référer à un lien, que j'ai fait figurer à la fin de cet article, vers une page qui les recense.

Il y a trois valeurs spéciales qui sont prévues par l'auteur du module. TEXT qui est la valeur par défaut si rien n'est spécifié (et si la valeur globale $MIME::Lite::AUTO_CONTENT_TYPE n'est pas modifiée). Dans le courriel, elle figurera en tant que text/plain. AUTO cherchera à établir le type en fonction du nom du fichier joint avec application/octet-stream comme défaut. Reste BINARY qui est une autre manière de renseigner application/octet-stream.
Encoding
Ici on va dire comment sont encodées les données (ou comment on souhaite les voir encodées). Ce paramètre est censé, à la différence des précédents, être optionnel parce que le module a prévu de deviner quel doit être l'encodage si rien n'est précisé. Mais il semble clair que l'on ne puisse complètement se fier à ses choix, particulièrement pour le texte (et particulièrement pour nous français encore une fois). Donc, apprenez à savoir quoi faire de qui, à quel fichier appliquer quel encodage, le module vous demande (relativement) peu d'efforts, mais faites-en ici, c'est nécessaire (et plutôt simple de surcroît).
Filename
Cet argument sert à donner un nom au fichier envoyé, ainsi point de . ou \ ou encore de / ici, juste un nom (et pas un chemin). Cet argument est notamment utile dans le cas où vous voulez faire apparaître à votre destinataire un nom de fichier différent de celui du fichier sur votre disque.

    $mime = MIME::Lite->build(
        From     => 'toi@toncheztoi.org',
        To       => 'moi@monchezmoi.org',
        Subject  => "Re: Hier soir !",
        Type     => 'TEXT',
        Encoding => 'quoted-printable',
        Data     => "C'était très bien, je te raconterai..."
    );

    $mime->build(
        From     => 'president@monassoce.org',
        To       => 'tresorier@monassoce.org',
        Subject  => "nouvelle acquisition pour l'asociation",
        X-Mailer => 'moncourriel.pl v1.1',
        Type     => 'image/jpeg',
        Encoding => 'base64',
        Path     => "/home/president/bureaux_hors_de_prix.jpg",
        Filename => "nos_futurs_locaux.jpg",
    );

La méthode `attach()`

La méthode attach() est celle qui va être utilisée après build() ou new() pour ajouter une partie de message MIME, sous la forme d'un objet MIME::Lite, à une autre partie MIME (ou la concaténation d'autres parties de message). Cette méthode prend un objet MIME::Lite en argument et l'ajoute à l'objet qui invoque attach(). Là aussi, il y a moyen de cumuler plusieurs actions en une seule invocation. Si on fournit les mêmes types d'arguments que ceux donnés à build() (toujours sous forme d'un hachage), attach() va automatiquement créer un objet MIME::Lite (avec la méthode new()), construire la partie de message MIME (en passant les arguments à build()), et l'attacher à l'objet qui a invoqué attach(). La partie MIME (un objet MIME::Lite) créée au long de ce processus est retournée par attach(). (cette méthode permet d'automatiser d'autres choses mais je vous engage à apprendre à faire sans au début, simplement pour apprendre à faire les choses bien. Prendre des raccourcis est bon lorsque l'on a conscience des étapes que l'on a sautées...)

    $mime = MIME::Lite->build(
        From     => 'toi@toncheztoi.org',
        To       => 'moi@monchezmoi.org',
        Subject  => "Re: Hier soir !",
        Type     => 'TEXT',
        Encoding => 'quoted-printable',
        Data     => "C'était très bien, je te raconterai...\nRegarde en attendant !"
    );

    $mime->attach(
        Type     => 'image/pjpeg',
        Encoding => 'base64',
        Path     => '/home/toi/photo/dream_team_soiree.jpg',
        Filename => 'soiree_hier.jpg'
    );

Les attributs

MIME::Lite possède toute une batterie de méthodes pour renseigner, lire, modifier les atributs des objets MIME::Lite après leur création. Il est inapproprié (autant qu'inutile) de les lister toutes. En voici un rapide survol.

Les méthodes `add()` et `attr()`.

Ces deux méthodes servent à la même chose : positionner la valeur d'une en-tête. L'une (attr()) est destinée à traiter les en-têtes (attributs) MIME, l'autre (add()) est destinée à s'occuper des autres.

    $mime->add("X-Mailer" => "moncourriel.pl v1.1");

    $mime->attr("content-type" => "text/plain");

add() a une syntaxe spéciale lorsqu'on a plusieurs occurrences de la même en-tête :

    $mime->add("X-Mailer" => ["moncourriel.pl v1.1", "MIME::Lite 2.117"]);

attr() prévoit comment préciser un sous-champ MIME :

    $mime->attr("content-type.charset" => "iso-8859-1");

La méthode `field_order()`

Cette méthode permet de préciser dans quel ordre vont figurer les en-têtes du courriel.

    $mime->field_order("from", "to", "subject", "X-Mailer");

Cette méthode est aussi une méthode de classe. Utilisée comme telle, elle modifie le comportement du module pendant toute l'exécution du script.

La méthode `get()`

get() est utilisée pour les en-têtes non-MIME. Elle permet de retrouver la valeur d'un champ. Lorsqu'un champ a plusieurs valeurs, il est possible de les avoir toutes ou de les récupérer individuellement grâce à leur indice.

    $field = $mime->get("from");        # retourne la valeur du champ 'from'
    $field = $mime->get("X-Mailer");    # retourne "moncourriel.pl v1.1"
    $field = $mime->get("X-Mailer, 1"); # retourne "MIME::Lite 2.117"
    @field = $mime->get("X-Mailer");    # une liste contenant "moncourriel.pl v1.1" et "MIME::Lite 2.117"

La méthode `replace()`

Cette méthode remplace toutes les occurrences d'un champ par la valeur fournie. Elle est notamment utile pour faire disparaître certains champs MIME du rendu final.

    $mime->replace("content-length" => $length);

Pour faire disparaître cet attribut MIME du courriel que va recevoir votre correspondant.

    $mime->replace("content-length" => '');

La méthode `sign()`

D'autres méthodes (nombreuses) existent aussi pour manipuler le message lui-même. J'ai retenu la méthode sign(). Elle permet d'ajouter une signature sans que vous ayez vous-même à le faire (en la concaténant au reste du message comme vu dans l'article précédent).

Avec une chaine comme paramètre :

    $mime->sign(Data => "--\npresident\@monassoce.org\nwww.monassoce.org");

Avec un fichier comme paramètre :

    $mime->sign(Path => "/home/president/.sig");

Le rendu

Il y a aussi les méthodes qui s'occupent du rendu, il en existe deux familles : celles qui retournent une valeur et celles qui l'impriment.

Les méthodes `as_string()`, `body_as_string()` et `header_as_string()`

Ces méthodes retournent, respectivement, le rendu (la sortie) complet du message, son corps et l'ensemble de ses en-têtes.

    $mess = $mime->as_string();
    $body = $mime->body_as_string();
    $headers = $mime->header_as_string();

Des équivalences existent pour chacune de ces méthodes dans l'autre famille de méthodes.

L'envoi

La dernière famille de méthodes est celle qui (enfin, après tout ce travail ;-) envoie le message.

Vous n'avez guère que deux choix en la matière : passer par votre propre serveur SMTP[3] (Sendmail, Postfix, Qmail...), ou vous adresser au travers du réseau à un autre qui acceptera de le faire.

La méthode `send()`

Cette méthode est une couche d'indirection pour toutes les méthodes d'envoi prévues dans le module.

Elle peut être invoquée sans argument et envoie à ce moment le message à sendmail avec les arguments -t -oi -oem.

Autrement on peut utiliser l'argument sendmail avec les options désirées

    $mime->send('sendmail', '/usr/lib/sendmail -t -oi -oem');

ou l'argument smtp avec le nom du serveur

    $mime->send('smtp', 'smtp.monfai.com');

ou enfin l'argument sub avec une référence à une subroutine ainsi que les arguments

    $mime->send('sub', \&SUBROUTINE, @arg);

Enfin, il est possible d'utiliser cette méthode comme méthode de classe et (vous me voyez venir ;-) modifier les options de l'envoi de message pour tous les messages, durant toute l'exécution du script.

    MIME::Lite->send('smtp', 'smtp.monfai.com');

Envoi de courriels avec Perl (2)

Chapeau

Introduction

Alors pourquoi MIME::Lite ?

MIME

MIME::Lite

Valeurs globales

La méthode `new()`

La méthode `build()`

La méthode `attach()`

Les attributs

Les méthodes `add()` et `attr()`.

La méthode `field_order()`

La méthode `get()`

La méthode `replace()`

La méthode `sign()`

Le rendu

Les méthodes `as_string()`, `body_as_string()` et `header_as_string()`

L'envoi

La méthode `send()`

Le castel gascon

Premièrement un peu d'ordre

Pourquoi tout cela ?

Le code

le rendu

Explication de texte

MIME::Lite ou Net::SMTP ?

Conclusion

Références de l'article:

Notes de l'article :

Auteur

Envoi de courriels avec Perl (2)

Chapeau

Introduction

Alors pourquoi MIME::Lite ?

MIME

MIME::Lite

Valeurs globales

La méthode new()

La méthode build()

La méthode attach()

Les attributs

Les méthodes add() et attr().

La méthode field_order()

La méthode get()

La méthode replace()

La méthode sign()

Le rendu

Les méthodes as_string(), body_as_string() et header_as_string()

L'envoi

La méthode send()

Le castel gascon

Premièrement un peu d'ordre

Pourquoi tout cela ?

Le code

le rendu

Explication de texte

MIME::Lite ou Net::SMTP ?

Conclusion

Références de l'article:

Notes de l'article :

Auteur

La méthode `new()`

La méthode `build()`

La méthode `attach()`

Les méthodes `add()` et `attr()`.

La méthode `field_order()`

La méthode `get()`

La méthode `replace()`

La méthode `sign()`

Les méthodes `as_string()`, `body_as_string()` et `header_as_string()`

La méthode `send()`