Differences

dev:send_emails_with_piwigo [2023/05/04 16:29] plg removed		— (current)
Line 1:		Line 1:
-	====== Send emails with Piwigo ======
-	<WRAP center round important 60%>
-	This page only applies to Piwigo 2.6 and newer.
-	</WRAP>
-
-	===== Introduction =====
-	Piwigo integrates a powerful mailing function compatible with standard PHP **mail()** function and SMTP servers. It is base on [[https://github.com/Synchro/PHPMailer|PHPMailer]] and [[http://www.pelagodesign.com/sidecar/emogrifier/|Emogrifier]] libraries.
-
-	There are four functions to send emails:
-	* **pwg_mail()** - the main one
-	* **pwg_mail_admins()** - to send emails to all admins
-	* **pwg_mail_groups()** - to send emails to a specific group
-	* **pwg_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:
-	<code php>array(
-	'name' => 'Name',
-	'email' => 'name@domain.com',
-	)</code>
-	* 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 email
-	* ''content_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 emails
-	* ''theme'' - //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 ==
-	<code php>
-	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',
-	)
-	);
-	</code>
-
-	===== 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 use
-	* ''dirname'' - path to your template directory
-	* ''assign'' - 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:
-	<code>
-	some/template/directory
-	+-- text
-	|-- html
-	|   |-- a-template-file.tpl
-	|   +-- another-template-file.tpl
-	+-- plain
-	|-- a-template-file.tpl
-	+-- another-template-file.tpl
-	</code>
-
-	In this configuration:\\
-	''filename = a-template-file''\\
-	''dirname = some/template/directory''
-
-	== Example ==
-	<code php>
-	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,
-	),
-	)
-	);
-	</code>
-
-	**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:
-
-	<code php>
-	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
-	);
-	}
-	</code>
-
-	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