readme.md 5.03 KB
Newer Older
1
Module Unicaen Mail
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
2
3
4
5
6
7
8
=======================
------------------------

Description
-----------
Le module **unicaen/mail** est en charge de l'envoi et du stockage des courriers électroniques.

9
Le module fournit un menu dans Administration > Mail permettant d'accéder au listing des mails et des actions liées à ceux-ci.
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
10
11
12
13
14
15
16

Description du fonctionnement
============================

Les mails
----------

17
Les entités **Mail** sont stockés en base avec les informations suivantes :
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
18
19
20
21
* destinataire (redirection ou pas)
* date d'envoi
* status
* sujet/corps
22
* mots clefs
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
23

24
**MailService** est en chage de faire l'envoi et l'enregistrement en base.
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
25

26
Exemple d'utilisation sans utilisation d'un template :
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
27
28
29
30
```php
$mail = $this->getMailService()->sendMail('john.doe@aol.com', 'Reunion importante', 'Bonjour nous avons ...');
```

31
Exemple d'utilisation avec utilisation d'un template + entité liée : 
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
32
```php
33
34
35
$rendu = $this->getRenduService()->generateRenduByTemplateCode('MON TEMPLATE', ['VAR1' => $var1, 'VAR2' => $var2, ...]);
$mail = $this->getMailService()->sendMail('john.doe@aol.com', $rendu->getSujet(), $rendu->getCorps());
$mail->addMotsClefs(['MON_ENTITE', 'MON_TEMPLATE']);
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
$this->getMailService()->update($mail);
```

Aides de vue founies
--------------------

```php
'view_helpers' => [
    'invokables' => [
        'mail' => MailViewHelper::class,
        'mails' => MailsViewHelper::class,
    ],
],
```

51
52
`$this->mail($monMail)` : Affiche un mail généré avec la description à gauche et le texte généré à droite.
`$this->mails($monTableauDeMail)` : Affiche une table avec une ligne par mail et founi les actions associées (affiachage, réenvoi, suppression).
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
53

54
55
56
57
58
59
60
61
***Attention !!!*** l'aide `mails` peut recevoir un tableau permettant d'ajuster les droits des actions.
```php 
$options['droits'][
    'afficher' => Boolean, 
    'reenvoyer' => Boolean, 
    'supprimer' => Boolean
    ]
```
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
62
63
64
65

Configuration
=============

66
La configuration locale à fournir est disponible dans [mail/config/unicaen-mail.local.php.dist]
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
67
68
69
70
71
72
73
74

```php
<?php
/**
 * Configuration locale du module UnicaenMail.
 */
return [
    'unicaen-mail' => [
Thibaut Vallee's avatar
Thibaut Vallee committed
75
76
77
78
79
80

        /**
         * Classe de entité
         **/
        'mail_entity_class' => Mail::class,
        
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
81
82
83
84
        /**
         * Options concernant l'envoi de mail par l'application
         */
        'transport_options' => [
Thibaut Vallee's avatar
Thibaut Vallee committed
85
            'host' => 'smtp.XXXX.fr',
Thibaut Vallee's avatar
Thibaut Vallee committed
86
            'port' => 25,
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
87
88
89
90
        ],
        /**
         * Adresses des redirection si do_not_send est à true
         */
Thibaut Vallee's avatar
Thibaut Vallee committed
91
        'redirect_to' => ['john-doe@mail.fr', ],
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
92
93
94
95
96
        'do_not_send' => true,
        
        /**
         * Configuration de l'expéditeur
         */
Thibaut Vallee's avatar
Thibaut Vallee committed
97
        'subject_prefix' => '[Mon App]',
Thibaut Vallee's avatar
Thibaut Vallee committed
98
        'from_name' => 'Mon application',
Thibaut Vallee's avatar
Thibaut Vallee committed
99
        'from_email' => 'ne-pas-repondre@mail.fr'
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
100
101
102
103
104
105
106
107
108
109
110
111
112
    ],
];
```

Tables pour les données du modules
==================================

**N.B.** Le script permettant de créer les tables est fourni dans le fichier [mail/SQL/001_tables.sql]

**unicaen_mail_mail** : table stockant les mails

| Column | Type | Obligatoire | Unique | Description |
|---|---|---|---|---|
113
| id | int | true | true | identifiant numerique du mail |
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
114
| date_envoi | timestamp| true | false | date de l'envoi du mail |
115
116
117
| status_envoi | varchar(256) | true | false | statut "indicatif" de l'envoi : FAILED, SUCCESS, PENDING |
| destinataires | text | true | false | chaîne de caractères concaténant les adresses des destinataires |
| destinataires_initials | text | false | false | Null si le mail n'as pas été redirigé. Sinon chaînes de caractères concaténant les adresse des destinataires initiaux du mail|
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
118
119
| sujet | text | false | false | sujet du mail |
| corps | text | false | false | corps du mail |
120
| mots_clefs | text | false | false | champ libre permettant d'associer des mots clefs aux mails (ie. id d'une entité, mots clés de recherche ...)|
121
| log | text | false | false | Log du mail |
Jean-Philippe Metivier's avatar
Jean-Philippe Metivier committed
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

Privilèges associés au module
=============================

**N.B.** Le script permettant de créer les tables est fourni dans le fichier [mail/SQL/002_privileges.sql]

```php
const MAIL_INDEX                            = 'mail-mail_index';
const MAIL_AFFICHER                         = 'mail-mail_afficher';
const MAIL_TEST                             = 'mail-mail_test';
const MAIL_REENVOI                          = 'mail-mail_reenvoi';
const MAIL_SUPPRIMER                        = 'mail-mail_supprimer';
```

***Attention !!!*** Penser à donner les privilèges aux rôles adéquats.
137
138
139
140
141
142
143
144
145

Dépendances exterieurs
======================

Dépendance à **UnicaenPrivilège**
----------------------------------
1. Dans **vendor/unicaen/mail/config/merged/mail.config.php** : `UnicaenPrivilege\Guard\PrivilegeController` pour les gardes liées aux actions.
Peut être directement remplacer par l'equivalent fournit par `unicaen/auth`.

146
1. Dans **vendor/unicaen/mail/src/UnicaenMail/Provider/Privilege/MailPrivileges.php** : `UnicaenPrivilege\Provider\Privilege\Privileges` classe mère des privilèges du module. 
147
148
Peut être directement remplacer par l'equivalent fournit par `unicaen/auth`.