/
jmailer.gtw
324 lines (243 loc) · 9.89 KB
/
jmailer.gtw
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
~~LANG:FR@frman:classes-utiles/jmailer~~
jMailer is an object to send emails. It is based on the
[[https://github.com/PHPMailer/PHPMailer|PHPMailer]] class.
Here are its features:
* support **attachments**
* **HTML** or **TEXT** email
* **Multiple recipients**
* **Multiple sending** channel (mail(), sendmail)
* **SMTP authentication** support
You can find many PHPMailer use cases over the web. So, we won't document all of the features.
jMailer brings some additional features, and ease configuration through the
main configuration file:
* default configuration of jMailer is stored in the configuration file of the application
* you can use jTpl templates to generate your emails content.
* errors messages are localized in properties files (jLocale)
* errors are raised and logged through exceptions.
===== Configuration file =====
jMailer options shall be edited in @@F@var/config/localconfig.ini.php@@, in a
@@[mailer]@@ section.
==== Main configuration options ====
* @@webmasterEmail@@: default sender email.
* @@webmasterName@@: default sender name.
* @@mailerType@@: indicates how to send mails (default: "mail")
* "mail": PHP mail function
* "sendmail": use the server program
* "smtp": direct connection to an SMTP host
* @@hostname@@: used in @@Message-Id@@ and @@Received@@ headers, and also as
default @@HELO@@ string. If empty, the value returned by @@$_SERVER['SERVER_NAME']@@ is used
or 'localhost.localdomain'.
* @@sendmailPath@@: path to sendmail program
jMailer uses also general parameters @@locale@@ and @@charset@@ to setup the
language and charset of emails.
Of course, you can change all of these parameters directly with properties and
methods of jMailer class. See reference documentation.
Note about the @@webmasterEmail@@: If you don't use the smtp mailer, be sure the web server
is allowed to send emails with the given Email. Else some mail servers may
reject emails sent by your application or mark them as spam. For example, if
your web server is public, you should set correcly the
[[https://en.wikipedia.org/wiki/Sender_Policy_Framework|DNS SPF record]] for your
domain name. This record should content the IP of your web server.
See the configuration manager of your domain name provider.
==== SMTP configuration options ====
If you choose to send mail with a specific SMTP server, you should indicate how to connect to it
by creating a profile into @@F@var/config/profiles.ini.php@@. The profile name must start
with @@smtp:@@, following by a name of your choice.
Example:
<code ini>
[smtp:mymailer]
host = localhost
; usually 587, 465 or 25 (unsecure)
port = 587
; secured connection or not (possible value: "", "ssl", "tls" or "unencrypted")
secure_protocol = tls
timeout = 20
; indicate if a username/password is required
auth_enabled = on
username = "me@foo"
password = thepassword
</code>
When secure_protocol is empty, PHPMailer tries to secure the connection with TLS.
The "unencrypted" value allows to force PHPMailer to not tries TLS, and connect with
an unencrypted channel. This value should be used only on local network.
Then you must indicate the profile name into the @@smtpProfile@@ parameter of the section @@[mailer]@@ into
@@F@var/config/localconfig.ini.php@@:
<code ini>
[mailer]
webmasterEmail = webmaster@foo.com
mailerType = smtp
smtpProfile = mymailer
</code>
You can still configure the SMTP parameters like in Jelix 1.6, although it is a deprecated way : do not create a profile,
do not set @@smtpProfile@@, and add these parameters into the @@[mailer]@@ section:
<code ini>
[mailer]
webmasterEmail = webmaster@foo.com
mailerType = smtp
; deprecated parameters for smtp configuration
smtpHost = localhost
smtpPort = 465
smtpSecure = ssl
smtpHelo=
smtpTimeout = 20
smtpAuth = on
smtpUsername = "me@foo"
smtpPassword = thepassword
</code>
===== Sending a simple mail =====
Sending a text email.
<code php>
$mail = new jMailer();
$mail->Subject = 'Subject';
$mail->Body = 'Text content';
$mail->AddAddress('recipientId@exemple.com' , 'recipient name');
$mail->Send();
</code>
===== Sending a mail using a template =====
You can use the powerful template engine of Jelix to send an email. You have
to create a template in your module. In this template, you can use meta values
to specify your email parameters.
Example, in @@modules/mymodule/templates/supermail.tpl@@:
<code html>
{meta Subject 'Super mail.'}
{meta Priority 1}
{meta From 'your name<your@email.com>'}
{meta Sender 'your@email.com'}
{meta ReplyTo array('your name<your@email.com>')}
{meta to array($name.'<'.$email.'>')}
{meta cc array('titi <titi@example.com>')}
{meta bcc array('tutu <tutu@example.com>')}
Hello {$name},
Here is an email generated by jMailer and Jelix.
</code>
And in your PHP code :
<code php>
$mail = new jMailer();
$tpl = $mail->Tpl('mymodule~supermail');
$tpl->assign('name', 'Mister Toto');
$tpl->assign('email', 'toto@example.com');
$mail->Send();
</code>
Notice that @@C@jMailer@@ will create template variables corresponding to some
PHPMailer properties, so you can use it them anywhere in the template
<code html>
{meta Subject 'Super mail.'}
{meta Priority 1}
{meta From 'your name<your@email.com>'}
{meta Sender 'your@email.com'}
{meta ReplyTo array('your name<your@email.com>')}
{meta to array($name.'<'.$email.'>')}
{meta cc array('titi <titi@example.com>', 'tutu <tutu@example.com>')}
Hello {$name},
Here is an email generated by jMailer and Jelix.
This email is send to :
{foreach $cc as $person}
- {$person[0]}
{/foreach}
</code>
===== Sending an HTML email =====
You have to call the @@M@isHTML@@ method like in this example:
<code php>
$mail = new jMailer();
$mail->isHTML(true);
$mail->Body = "<p>My <strong>HTML</strong> email !</p>";
$mail->AddAddress('toto@example.com' , 'Toto');
$mail->Send();
</code>
An alternative way is to give a template with HTML content, and so you have
to indicate @@true@@ to the method @@M@Tpl@@.
<code php>
$tpl = $mail->Tpl('mymodule~htmlmail', true);
</code>
PHPMailer include the HTML content in the email, but also a plain text version
of the content, by removing HTML elements and their attributes, CSS,
javascript code. jMailer improves the process by keeping links of the @@<a>@@
elements, between parenthesis after the label of the link, except if there
is a class or an attribute named @@notexpandlink@@.
You can provide your own HTML to text converter, by indicating it as the third
parameter to @@Tpl()@@. It should be a @@callable@@ type:
<code>
$tpl = $mail->Tpl(
'mymodule~supermail',
true,
function ($html) {
// ... convert to text
return $text;
}
);
</code>
Your HTML may content some images with the @@<img>@@ element. If the @@src@@
attribute is not an URL, then PHPMailer considers it as a file to include
into the mail. The path to the image may be a full path. But if it is a
relative path, you should indicate the base directory of all images to resolve
paths.
In this example, images referred into the HTML are in the @@www/images/@@
of the application:
<code>
$tpl = $mail->Tpl(
'mymodule~supermail',
true,
null,
jApp::wwwPath('images/')
);
</code>
===== Sending an attachment =====
You can add attachment easily in your email, by giving the path of the file
stored somewhere on the hard drive. You can also indicate an other name for the
file.
<code php>
$mail = new jMailer();
$mail->AddAttachment(jApp::varPath('original_filename.pdf'), 'new_filename.pdf');
...
$mail->Send();
</code>
===== Advanced features =====
Since jMailer inherits from the PHPmailer class, read [[https://phpmailer.github.io/PHPMailer/|the API documentation of PHPMailer]]
to know more about its features.
===== Testing the configuration =====
If you want to test the configuration of jMailer, you can launch the command `php console.php mailer:test`. Give an
email address to this command, and an email will be send to it.
```
php console.php mailer:test john.doe@example.com
```
===== Debug mode =====
In some environment for tests, like on your computer, you may not want to
send emails. Set @@mailerType@@ to @@file@@ and all emails generated by
jMailer will be stored into files, into your @@var/mails/@@ directory.
On a demo server, you may want to send emails, but you want to debug or
have more controls on sent emails.
If you want for example to have a copy of all emails into files, set
@@copyToFiles = on@@ in the @@mailer@@ section.
Starting with Jelix 1.6.17, you can force receivers, so all emails will be
send to them instead of receivers indicated to jMailer by the application.
To activate this feature, set @@debugModeEnabled = on@@, and list
receivers into @@debugReceivers@@. Here, all emails will be sent only to
Bob and Joe:
<code ini>
debugModeEnabled = on
debugReceivers[] = bob@foo.local
debugReceivers[] = joe@foo.local
</code>
You have also additional features:
<code ini>
; Prefix to add to subject of mails, in debug mode.
debugSubjectPrefix = "[DEMO] "
; Introduction inserted at the beginning of the messages in debug mode
debugBodyIntroduction = "This is a mail from test. Here are real headers: "
; type of receivers set into the email
; 1: only addresses from debugReceivers
; 2: only email address of the authenticated user, or addresses from debugReceivers
; if the user isn't authenticated
; 3: both, addresses from debugReceivers and address of the authenticated user
debugReceiversType = 3
; Receivers for 'To' having these emails will not be replaced by debugReceivers
; Receivers for 'Cc' and 'Bcc' having these emails will not be removed
debugReceiversWhiteList[] = john@foo.local
</code>
You can also debug the SMTP communication. Use the `debugSmtpLevel` configuration parameter to sets the level
of debug. Output will be done into log files. Levels:
* `0`: No output
* `1`: Commands
* `2`: Data and commands
* `3`: like 2 plus connection status
* `4`: Low-level data output