laravel-mail-templates/README.md

138 lines
3.1 KiB
Markdown

# Mail Templates
Ce package Laravel permet d'envoyer des templates mail via Sendinblue, Bluesquare Mail, et d'autres fournisseurs au besoin.
## Installation
Ajouter à `composer.json` :
```
"require": {
"bluesquare/laravel-mail-templates": "^1.1"
},
"repositories": [
{
"type": "vcs",
"url": "https://git.bluesquare.io/bluesquare/laravel-mail-templates"
}
]
```
Puis installer le package ainsi :
```bash
composer update bluesquare/laravel-mail-templates
```
## Configuration
Par défaut, ces variables sont indispensables dans le `.env`:
```dotenv
MAIL_TEMPLATES_PROVIDER=sendinblue
MAIL_TEMPLATES_API_KEY=your_api_key
```
Par défaut, `MAIL_FROM_NAME` et `MAIL_FROM_ADDRESS` sont utilisés pour l'expéditeur, mais peuvent être personnalisés ainsi :
```dotenv
MAIL_TEMPLATES_FROM_NAME="Bluesquare"
MAIL_TEMPLATES_FROM_ADDRESS="contact@bluesquare.io"
```
Il est aussi possible d'utiliser un endpoint personnalisé pour le provider choisi :
```dotenv
MAIL_TEMPLATES_API_URL=http://laravel.test/api/mails/template
```
## Utilisation
Créer une notification :
```bash
php artisan make:notification MyAwesomeNotification
```
Ajouter `MailTemplatesChannel` dans la méthode `via()` :
```php
return [MailTemplatesChannel::class];
```
Ajouter une méthode 'toTemplate()', en spécifiant le template et les paramètres souhaités :
```php
public function toTemplate($notifiable)
{
return (new MailTemplate('invoice-available'))
->addParameter('price', '$100');
}
```
Exemple avancé :
```php
public function toTemplate($notifiable)
{
return (new MailTemplate("my-template-name"))
->sender("john.doe@gmail.com", "John OPTIONAL") // OPTIONAL
->replyTo("jean.grey@gmail.com", "Jean OPTIONAL") // OPTIONAL
->recipients([
[
"elvis@gmail.com",
[
"name" => "Elvis" // OPTIONAL,
"parameters" => ["key" => "value"] // OPTIONAL
]
],
[
"robert@gmail.com"
]
])
->addRecipient("edward@gmail.com") // OPTIONAL
->parameters(["key" => "value", "key" => "value"]) // OPTIONAL
->addParameter("key", "value") // OPTIONAL
;
}
```
> Le `$notifiable` est automatiquement ajouté comme destinataire.
## Mapping
Lors d'une transition d'un provider à l'autre, les ID / noms de templates peuvent varier.
Pour cette raison, il est possible de mapper les templates selon le provider.
Avant tout, publier le fichier de config via :
```bash
php artisan vendor:publish
```
Ensuite, mapper les templates dans `config/mail_templates.php` :
```php
'map' => [
'sendinblue' => [
// Nom utilisé dans la notification => ID réel du template sur Sendinblue
'template-1' => '1',
'template-2' => '3',
],
//...
]
```
## Tests
Il est possible de rediriger tous les mails vers une adresse :
```dotenv
MAIL_TEMPLATES_REDIRECT="contact@bluesquare.io"
```
Ou de logger les templates au lieu de les envoyer :
```dotenv
MAIL_TEMPLATES_PROVIDER=logs
```