Skip to content

Commit

Permalink
feature 2999: Documentation of include/functions_mail|metadata|picture
Browse files Browse the repository at this point in the history 
git-svn-id: http://piwigo.org/svn/trunk@25550 68402e56-0260-453c-a942-63ccdbb3a9ee
  • Loading branch information
@mistic100
mistic100 committed Nov 18, 2013
1 parent 0ed662e commit b8eeae3
Show file tree
Hide file tree
Showing 4 changed files with 119 additions and 65 deletions.
9 changes: 8 additions & 1 deletion include/functions.inc.php
View file
Expand Up @@ -103,12 +103,19 @@ function get_filename_wo_extension( $filename )
return ($pos===false) ? $filename : substr( $filename, 0, $pos);
}

/** no option for mkgetdir() */
define('MKGETDIR_NONE', 0);
/** sets mkgetdir() recursive */
define('MKGETDIR_RECURSIVE', 1);
/** sets mkgetdir() exit script on error */
define('MKGETDIR_DIE_ON_ERROR', 2);
/** sets mkgetdir() add a index.htm file */
define('MKGETDIR_PROTECT_INDEX', 4);
/** sets mkgetdir() add a .htaccess file*/
define('MKGETDIR_PROTECT_HTACCESS', 8);
define('MKGETDIR_DEFAULT', 7);
/** default options for mkgetdir() = MKGETDIR_RECURSIVE | MKGETDIR_DIE_ON_ERROR | MKGETDIR_PROTECT_INDEX */
define('MKGETDIR_DEFAULT', MKGETDIR_RECURSIVE | MKGETDIR_DIE_ON_ERROR | MKGETDIR_PROTECT_INDEX);

/**
* creates directory if not exists and ensures that directory is writable
*
Expand Down
108 changes: 73 additions & 35 deletions include/functions_mail.inc.php
View file
Expand Up @@ -21,8 +21,14 @@
// | USA. |
// +-----------------------------------------------------------------------+

/**
* @package functions\mail
*/


/**
* Returns the name of the mail sender
*
* @return string
*/
function get_mail_sender_name()
Expand All @@ -34,6 +40,7 @@ function get_mail_sender_name()

/**
* Returns the email of the mail sender
*
* @since 2.6
* @return string
*/
Expand All @@ -45,7 +52,7 @@ function get_mail_sender_email()
}

/**
* Returns an array of mail configuration parameters :
* Returns an array of mail configuration parameters.
* - send_bcc_mail_webmaster
* - mail_allow_html
* - use_smtp
Expand Down Expand Up @@ -79,9 +86,14 @@ function get_mail_configuration()
}

/**
* Returns an email address with an associated real name
* @param string name
* @param string email
* Returns an email address with an associated real name.
* Can return either:
* - email@domain.com
* - name <email@domain.com>
*
* @param string $name
* @param string $email
* @return string
*/
function format_email($name, $email)
{
Expand All @@ -104,10 +116,11 @@ function format_email($name, $email)
}

/**
* Returns the mail and the name from a formatted address
* Returns the email and the name from a formatted address.
* @since 2.6
* @param string|array $input
* @return array
*
* @param string|string[] $input - if is an array must contain email[, name]
* @return array email, name
*/
function unformat_email($input)
{
Expand Down Expand Up @@ -137,10 +150,12 @@ function unformat_email($input)
}

/**
* Return a clean array of hashmaps (email, name) from various inputs
* - comma separated list
* - array of emails
* - single hashmap (email[, name])
* Return a clean array of hashmaps (email, name) removing duplicates.
* It accepts various inputs:
* - comma separated list
* - array of emails
* - single hashmap (email[, name])
* - array of incomplete hashmaps
* @since 2.6
*
* @param mixed $data
Expand All @@ -163,7 +178,7 @@ function get_clean_recipients_list($data)
foreach ($data as &$item)
{
$item = array(
'email' => $item,
'email' => trim($item),
'name' => '',
);
}
Expand All @@ -184,12 +199,27 @@ function get_clean_recipients_list($data)
$data = explode(',', $data);
$data = array_map('unformat_email', $data);
}

return $data;

$existing = array();
foreach ($data as $i => $entry)
{
if (isset($existing[ $entry['email'] ])
{
unset($data[$i]);
}
else
{
$existing[ $entry['email'] ] = true;
}
}

return array_values($data);
}

/**
* Returns an email address list with minimal email string
* Returns an email address list with minimal email string.
* @deprecated 2.6
*
* @param string $email_list - comma separated
* @return string
*/
Expand All @@ -211,7 +241,8 @@ function get_strict_email_list($email_list)
}

/**
* Return an new mail template
* Return an new mail template.
*
* @param string $email_format - text/html or text/plain
* @return Template
*/
Expand All @@ -222,8 +253,9 @@ function &get_mail_template($email_format)
}

/**
* Return string email format (text/html or text/plain)
* @param bool is_html
* Return string email format (text/html or text/plain).
*
* @param bool $is_html
* @return string
*/
function get_str_email_format($is_html)
Expand All @@ -232,8 +264,9 @@ function get_str_email_format($is_html)
}

/**
* Switch language to specified language
* Switch language to specified language.
* All entries are push on language stack
*
* @param string $language
*/
function switch_lang_to($language)
Expand Down Expand Up @@ -295,7 +328,8 @@ function switch_lang_to($language)
}

/**
* Switch back language pushed with switch_lang_to function
* Switch back language pushed with switch_lang_to() function.
* @see switch_lang_to()
*/
function switch_lang_back()
{
Expand All @@ -317,8 +351,9 @@ function switch_lang_back()
}

/**
* Send a notification email to all administrators
* Send a notification email to all administrators.
* current user (if admin) is not notified
*
* @param string|array $subject
* @param string|array $content
* @param boolean $send_technical_details - send user IP and browser
Expand Down Expand Up @@ -375,7 +410,7 @@ function pwg_mail_notification_admins($subject, $content, $send_technical_detail
}

/**
* Send a email to all administrators
* Send a email to all administrators.
* current user (if admin) is excluded
* @see pwg_mail()
* @since 2.6
Expand Down Expand Up @@ -424,12 +459,12 @@ function pwg_mail_admins($args=array(), $tpl=array())
}

/**
* Send an email to a group
* Send an email to a group.
* @see pwg_mail()
*
* @param int $group_id
* @param array $args - as in pwg_mail()
* @option string language_selected - filters users of the group by language
* o language_selected: filters users of the group by language [default value empty]
* @param array $tpl - as in pwg_mail()
* @return boolean
*/
Expand Down Expand Up @@ -508,9 +543,9 @@ function pwg_mail_group($group_id, $args=array(), $tpl=array())
}

/**
* sends an email, using Piwigo specific informations
* Sends an email, using Piwigo specific informations.
*
* @param string|string[] $to
* @param string|array $to
* @param array $args
* o from: sender [default value webmaster email]
* o Cc: array of carbon copy receivers of the mail. [default value empty]
Expand Down Expand Up @@ -593,7 +628,10 @@ function pwg_mail($to, $args=array(), $tpl=array())
$Bcc = get_clean_recipients_list(@$args['Bcc']);
if ($conf_mail['send_bcc_mail_webmaster'])
{
$Bcc[] = get_webmaster_mail_address();
$Bcc[] = array(
'email' => get_webmaster_mail_address(),
'name' => '',
);
}
if (!empty($Bcc))
{
Expand Down Expand Up @@ -821,7 +859,7 @@ function pwg_mail($to, $args=array(), $tpl=array())
if ($pre_result)
{
$ret = $mail->send();
if (!$ret and (!ini_get('display_errors') || is_admin()))
if (!$ret and (!ini_get('display_errors') or is_admin()))
{
trigger_error('Mailer Error: ' . $mail->ErrorInfo, E_USER_WARNING);
}
Expand Down Expand Up @@ -858,9 +896,10 @@ function pwg_send_mail($result, $to, $subject, $content, $headers)
}

/**
* Moves CSS rules contained in the <style> tag to inline CSS
* (for compatibility with Gmail and such clients)
* Moves CSS rules contained in the <style> tag to inline CSS.
* Used for compatibility with Gmail and such clients
* @since 2.6
*
* @param string $content
* @return string
*/
Expand All @@ -874,12 +913,11 @@ function move_css_to_body($content)
}

/**
* Saves a copy of the mail if _data/tmp
* @param boolean $result
* @param string $to
* @param array $args
* Saves a copy of the mail if _data/tmp.
*
* @param boolean $success
* @param PHPMailer $mail
* @return boolean $result
* @param array $args
*/
function pwg_send_mail_test($success, $mail, $args)
{
Expand Down
18 changes: 12 additions & 6 deletions include/functions_metadata.inc.php
View file
Expand Up @@ -22,10 +22,15 @@
// +-----------------------------------------------------------------------+

/**
* returns informations from IPTC metadata, mapping is done at the beginning
* of the function
* @package functions\metadata
*/


/**
* returns informations from IPTC metadata, mapping is done in this function.
*
* @param string $filename
* @param array $map
* @return array
*/
function get_iptc_data($filename, $map)
Expand Down Expand Up @@ -80,9 +85,9 @@ function get_iptc_data($filename, $map)
}

/**
* return a cleaned IPTC value
* return a cleaned IPTC value.
*
* @param string value
* @param string $value
* @return string
*/
function clean_iptc_value($value)
Expand Down Expand Up @@ -127,10 +132,10 @@ function clean_iptc_value($value)
}

/**
* returns informations from EXIF metadata, mapping is done at the beginning
* of the function
* returns informations from EXIF metadata, mapping is done in this function.
*
* @param string $filename
* @param array $map
* @return array
*/
function get_exif_data($filename, $map)
Expand Down Expand Up @@ -180,4 +185,5 @@ function get_exif_data($filename, $map)

return $result;
}

?>

0 comments on commit b8eeae3

Please sign in to comment.