This page only applies to Piwigo 2.6 and newer.
Introduction
Piwigo integrates a powerful mailing function compatible with standard PHP mail() function and SMTP servers. It is base on PHPMailer and Emogrifier libraries.
There are four functions to send emails:
pwg_mail()- the main onepwg_mail_admins()- to send emails to all adminspwg_mail_groups()- to send emails to a specific grouppwg_mail_notification_admins()- dedicated to administrative emails
Basic usage
pwg_mail() takes three parameters, for basic usage you only need to use the first and the second one.
The first parameter is the recipient(s) of the mail, it can be either:
- a single email:
name@domain.com - a single email with associated name:
Name <name@ domain.com> - a comma separated list of emails (with or without associated names)
- a hashmap containing email and name keys:
array(
'name' => 'Name',
'email' => 'name@domain.com',
)
- an array of hashmaps containing email and name keys
The second parameter is an array of options:
from- sender of the email [defaults to webmaster email and gallery name]Cc- carbon copy recipients as array [defaults to empty]Bcc- blind carbon copy recipients as array [defaults to empty]subject- subject of the email [defaults to 'Piwigo']content- content of the emailcontent_format- text/html or text/plain [defaults to 'text/plain']email_format- text/html or text/plain [defaults to 'text/html'] will be forced to 'text/plain' if webmaster disabled HTML emailstheme- clear or dark [defaults to $conf['mail_theme']]mail_title- main title in email corpus [defaults to $conf['gallery_title']]mail_subtitle- subtitle in email corpus [defaults to subject]]
About mail_title and mail_subtitle
If you set subject to [something] something else and leave
mail_title and mail_subtitle empty, you will get:
mail_title = something
mail_subtitle = something else
This is for backward compatibility only.
Example
include_once(PHPWG_ROOT_PATH . 'include/functions_mail.inc.php');
pwg_mail(
array(
'name' => 'Username',
'email' => 'name@domain.com',
),
array(
'content' => $content
'content_format' => 'text/plain',
'subject' => 'Sample mail',
)
);
Email with template
Instead of providing the content parameter you can use the third parameter of pwg_mail() which allows you to manipulate the mail template. Options are:
filename- name of .tpl file to usedirname- path to your template directoryassign- array of variables to pass to the template
About filename and dirname
Each mail template file must be available in both text/plain and text/html formats and you must respect the following files hierarchy:
some/template/directory
+-- text
|-- html
| |-- a-template-file.tpl
| +-- another-template-file.tpl
+-- plain
|-- a-template-file.tpl
+-- another-template-file.tpl
In this configuration:
filename = a-template-file
dirname = some/template/directory
Example
include_once(PHPWG_ROOT_PATH . 'include/functions_mail.inc.php');
pwg_mail(
array(
'name' => 'Username',
'email' => 'name@domain.com',
),
array(
'subject' => 'Sample mail',
),
array(
'filename' => 'a-template-file',
'dirname' => PHPWG_ROOT_PATH . 'some/template/directory',
'assign' => array(
'USERNAME' => $user['username'],
'MY_VAR' => 1234,
),
)
);
Note: If you use the template system AND provide a content it will be available on the {$CONTENT} template variable (after converting line-breaks and links if content_type='text/plain').
Using prefilters
From Piwigo 2.6 it is possible to apply prefilters on emails template.
One does have to know that emails do not use the same instance of the
Template class as the rest of Piwigo, and theses instances are cached
(if multiple pwg_mail() are called in the same script).
We added a new trigger before_parse_mail_template in order to access
theses instances. Usually there are two instances, one for text/plain
and one for text/html, but if the language is changed with
switch_lang_to() there will be more.
Here is an example of how to change the contact link in the footer of the email:
add_event_handler('before_parse_mail_template', 'my_mail_template', EVENT_HANDLER_PRIORITY_NEUTRAL, 2);
function my_mail_template($cache_key, $content_type)
{
global $conf_mail;
$template = &$conf_mail[$cache_key]['theme'];
if ($content_type == 'text/html')
{
$template->set_prefilter('mail_footer', 'my_mail_template_prefilter_html');
}
else
{
$template->set_prefilter('mail_footer', 'my_mail_template_prefilter_plain');
}
}
function my_mail_template_prefilter_html($content)
{
return str_replace(
'mailto:{$CONTACT_MAIL}?subject={\'A comment on your site\'|translate|escape:url}',
'http://new-url-to-contact-page',
$content
);
}
function my_mail_template_prefilter_plain($content)
{
return str_replace(
'{$CONTACT_MAIL}',
'http://new-url-to-contact-page',
$content
);
}
Note that you may have to use two different prefilters for HTML and plain text.
You can apply these prefilters on:
- mail_header
- mail_footer
- css
- (any template file provided with the third parameter of pwg_mail())
Other functions
pwg_mail_admins() parameters are exactly the same as pwg_mail() except the first one which is not present.
Likewise, pwg_mail_group() parameters are the same except the first one which is the group identifier.
pwg_mail_notification_admins() takes three parameters:
subject- string or array of get_l10n_args()content- string or array of get_l10n_args()send_technical_details- set it true to include user IP and UserAgent in the mail
Some little functions may be useful too:
- get_str_email_format
- switch_lang_to
- switch_lang_back
- set_make_full_url
- unset_make_full_url