CakeEmail¶

Choisir l’émetteur¶

Quand on envoie des emails de la part d’autre personne, c’est souvent une bonne idée de définir l’émetteur original en utilisant le header Sender. Vous pouvez faire ceci en utilisant sender():

$Email = new CakeEmail();
$Email->sender('[email protected]', 'MyApp emailer');

Configurations¶

La clés de configuration suivantes sont utilisées:

• 'from': Email ou un tableau d’emmeteur. Regardez CakeEmail::from().

• 'sender': Email ou un tableau d’émetteur réel. Regardez CakeEmail::sender().

• 'to': Email ou un tableau de destination. Regardez CakeEmail::to().

• 'cc': Email ou un tableau de copy carbon. Regardez CakeEmail::cc().

• 'bcc': Email ou un tableau de copy carbon blind. Regardez CakeEmail::bcc().

• 'replyTo': Email ou un tableau de repondre à cet e-mail. Regardez CakeEmail::replyTo().

• 'readReceipt': Adresse Email ou un tableau d’adresses pour recevoir un récepissé de lecture. Regardez CakeEmail::readReceipt().

• 'returnPath': Adresse Email ou un tableau des adresses à retourner si vous avez une erreur. Regardez CakeEmail::returnPath().

• 'messageId': ID du Message de l’e-mail. Regardez CakeEmail::messageId().

• 'subject': Sujet du message. Regardez CakeEmail::subject().

• 'message': Contenu du message. Ne définissez pas ce champ si vous utilisez un contenu rendu.

• 'headers': Headers à inclure. Regardez CakeEmail::setHeaders().

• 'viewRender': Si vous utilisez un contenu rendu, définissez le nom de classe de la vue. Regardez CakeEmail::viewRender().

• 'template': Si vous utilisez un contenu rendu, définissez le nom du template. Regardez CakeEmail::template().

• 'theme': Theme utilisé pour le rendu du template. Voir CakeEmail::theme().

• 'layout': Si vous utilisez un contenu rendu, définissez le layout à rendre. Si vous voulez rendre un template sans layout, définissez ce champ à null. Regardez CakeEmail::template().

• 'viewVars': Si vous utilisez un contenu rendu, définissez le tableau avec les variables devant être rendus dans la vue. Regardez CakeEmail::viewVars().

• 'attachments': Liste des fichiers à attacher. Regardez CakeEmail::attachments().

• 'emailFormat': Format de l’email (html, text ou both). Regardez CakeEmail::emailFormat().

• 'transport': Nom du Transport. Regardez CakeEmail::transport().

• 'helpers': Tableau de helpers utilisé dans le template d’email.

Toutes ces configurations sont optionnelles, excepté 'from'. Si vous mettez plus de configurations dans ce tableau, les configurations seront utilisées dans la méthode CakeEmail::config() et passées à la classe de transport config(). Par exemple, si vous utilisez le transport SMTP, vous devez passer le host, port et autres configurations.

Définir les headers¶

Dans CakeEmail, vous êtes libre de définir les headers que vous souhaitez. Si vous migrez pour utiliser CakeEmail, n’oubliez pas de mettre le préfixe X- dans vos headers.

Regardez CakeEmail::setHeaders() et CakeEmail::addHeaders()

Envoyer les emails templatés¶

Les Emails sont souvent bien plus que de simples messages textes. Afin de faciliter cela, CakePHP fournit une façon d’envoyer les emails en utilisant la view layer de CakePHP.

Les templates pour les emails se placent dans un dossier spécial appelé Emails dans le répertoire View de votre application. Les vues des emails peuvent aussi utiliser les layouts et éléments tout comme les vues normales:

$Email = new CakeEmail();
$Email->template('welcome', 'fancy')
    ->emailFormat('html')
    ->to('[email protected]')
    ->from('[email protected]')
    ->send();

Ce qui est au-dessus utilise app/View/Emails/html/welcome.ctp pour la vue, et app/View/Layouts/Emails/html/fancy.ctp pour le layout. Vous pouvez aussi envoyer des messages email templaté multipart:

$Email = new CakeEmail();
$Email->template('welcome', 'fancy')
    ->emailFormat('both')
    ->to('[email protected]')
    ->from('[email protected]')
    ->send();

Ceci utiliserait les fichiers de vue suivants:

• app/View/Emails/text/welcome.ctp

• app/View/Layouts/Emails/text/fancy.ctp

• app/View/Emails/html/welcome.ctp

• app/View/Layouts/Emails/html/fancy.ctp

Quand on envoie les emails templatés, vous avez la possibilité d’envoyer soit text, html soit both.

Vous pouvez définir des variables de vue avec CakeEmail::viewVars():

$Email = new CakeEmail('templated');
$Email->viewVars(array('value' => 12345));

Dans votre email template, vous pouvez utiliser ceux-ci avec:

<p>Ici est votre valeur: <b><?php echo $value; ?></b></p>

Vous pouvez aussi utiliser les helpers dans les emails, un peu comme vous pouvez dans des fichiers normaux de vue. Par défaut, seul HtmlHelper est chargé. Vous pouvez chargez des helpers supplémentaires en utilisant la méthode helpers():

$Email->helpers(array('Html', 'Custom', 'Text'));

Quand vous définissez les helpers, assurez vous d’inclure “Html” ou il sera retiré des helpers chargés dans votre template d’email.

Si vous voulez envoyer un email en utilisant templates dans un plugin, vous pouvez utiliser la syntaxe de plugin familière pour le faire:

$Email = new CakeEmail();
$Email->template('Blog.new_comment', 'Blog.auto_message')

Ce qui est au-dessus utiliserait les templates à partir d’un plugin de Blog par exemple.

Envoyer les pièces jointes¶

Vous pouvez aussi attacher des fichiers aux messages d’email. Il y a quelques formats différents qui dépendent de quel type de fichier vous avez, et comment vous voulez que les noms de fichier apparaissent dans le mail de réception du client:

1. Chaîne de caractères: $Email->attachments('/full/file/path/file.png') va attacher ce fichier avec le nom file.png.

2. Tableau: $Email->attachments(array('/full/file/path/file.png')) aura le même comportement qu’en utilisant une chaîne de caractères.

3. Tableau avec clé: $Email->attachments(array('photo.png' => '/full/some_hash.png')) va attacher some_hash.png avec le nom photo.png. Le récipiendaire va voir photo.png, pas some_hash.png.

4. Tableaux imbriqués:

   $Email->attachments(array(
       'photo.png' => array(
           'file' => '/full/some_hash.png',
           'mimetype' => 'image/png',
           'contentId' => 'my-unique-id'
       )
   ));
   

   Ce qui est au-dessus va attacher le fichier avec différent mimetype et avec un content ID personnalisé (Quand vous définissez le content ID, la pièce jointe est transformée en inline). Le mimetype et contentId sont optionels dans ce formulaire.

4.1. Quand vous utilisez contentId, vous pouvez utiliser le fichier dans

corps HTML comme <img src="cid:my-content-id">.

4.2. Vous pouvez utiliser l’option contentDisposition pour désactiver le

header Content-Disposition pour une pièce jointe. C’est utile pour l’envoi d’invitations ical à des clients utilisant outlook.

4.3 Au lieu de l’option file, vous pouvez fournir les contenus de

fichier en chaîne en utilisant l’option data. Cela vous permet d’attacher les fichiers sans avoir besoin de chemins de fichier vers eux.

Utiliser les transports¶

Les Transports sont des classes destinées à envoyer l’email selon certain protocoles ou méthodes. CakePHP supporte les transports Mail (par défaut), Debug et SMTP.

Pour configurer votre méthode, vous devez utiliser la méthode CakeEmail::transport() ou avoir le transport dans votre configuration.

App::uses('AbstractTransport', 'Network/Email');

class ExempleTransport extends AbstractTransport {

    public function send(CakeEmail $Email) {
        // magique à l'intérieur!
    }

}

$yourInstance = $Email->transport('your')->transportClass();
$yourInstance->myCustomMethod();
$Email->send();

Faciliter les règles de validation des adresses¶

CakeEmail::emailPattern($pattern = null)¶

Si vous avez des problèmes de validation lors de l’envoi vers des adresses non conformes, vous pouvez faciliter le patron utilisé pour valider les adresses email. C’est parfois nécessaire quand il s’agit de certains ISP Japonais.

$email = new CakeEmail(“default”);

// Relax le patron d'email, ainsi vous pouvez envoyer // vers des adresses non conformes $email->emailPattern($newPattern);