aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authormistic100 <mistic@piwigo.org>2013-11-19 18:45:48 +0000
committermistic100 <mistic@piwigo.org>2013-11-19 18:45:48 +0000
commit68bbe763cf0b0df337676a6dca6e2f9add089019 (patch)
tree01e65b0e3cec5af6fab72d0d8f41dc5867d87bf2
parent6f211a609ad750106a7366ac656b434825db0b20 (diff)
feature 2999: Documentation of include/functions_notification + clean code
git-svn-id: http://piwigo.org/svn/trunk@25578 68402e56-0260-453c-a942-63ccdbb3a9ee
-rw-r--r--include/functions_notification.inc.php438
1 files changed, 223 insertions, 215 deletions
diff --git a/include/functions_notification.inc.php b/include/functions_notification.inc.php
index 18378cbb4..b8e867030 100644
--- a/include/functions_notification.inc.php
+++ b/include/functions_notification.inc.php
@@ -21,139 +21,158 @@
// | USA. |
// +-----------------------------------------------------------------------+
-// +-----------------------------------------------------------------------+
-// | functions |
-// +-----------------------------------------------------------------------+
+/**
+ * @package functions\notification
+ */
+
+// TODO : use a cache for all data returned by custom_notification_query()
-/*
- * get standard sql where in order to
- * restict an filter caregories and images
- *
- * IMAGE_CATEGORY_TABLE muste named ic in the query
- *
- * @param none
+
+/**
+ * Get standard sql where in order to restrict and filter categories and images.
+ * IMAGE_CATEGORY_TABLE must be named "ic" in the query
*
- * @return string sql where
+ * @param string $prefix_condition
+ * @param string $img_field
+ * @param bool $force_one_condition
+ * @return string
*/
-function get_std_sql_where_restrict_filter($prefix_condition, $img_field='ic.image_id', $force_one_condition = false)
+function get_std_sql_where_restrict_filter($prefix_condition,
+ $img_field = 'ic.image_id',
+ $force_one_condition = false)
{
- return get_sql_condition_FandF
- (
- array
- (
- 'forbidden_categories' => 'ic.category_id',
- 'visible_categories' => 'ic.category_id',
- 'visible_images' => $img_field
- ),
- $prefix_condition,
- $force_one_condition
- );
+ return get_sql_condition_FandF(
+ array(
+ 'forbidden_categories' => 'ic.category_id',
+ 'visible_categories' => 'ic.category_id',
+ 'visible_images' => $img_field
+ ),
+ $prefix_condition,
+ $force_one_condition
+ );
}
-/*
- * Execute custom notification query
- *
- * @param string action ('count' or 'info')
- * @param string type of query ('new_comments', 'unvalidated_comments', 'new_elements', 'updated_categories', 'new_users')
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
+/**
+ * Execute custom notification query.
*
- * @return integer for action count
- * array for info
+ * @param string $action 'count', 'info'
+ * @param string $type 'new_comments', 'unvalidated_comments', 'new_elements', 'updated_categories', 'new_users'
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int|array int for action count array for info
*/
-function custom_notification_query($action, $type, $start, $end)
+function custom_notification_query($action, $type, $start=null, $end=null)
{
global $user;
switch($type)
{
case 'new_comments':
+ {
$query = '
FROM '.COMMENTS_TABLE.' AS c
- , '.IMAGE_CATEGORY_TABLE.' AS ic
- WHERE c.image_id = ic.image_id';
+ INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON c.image_id = ic.image_id
+ WHERE 1=1';
if (!empty($start))
{
- $query .= '
+ $query.= '
AND c.validation_date > \''.$start.'\'';
}
if (!empty($end))
{
- $query .= '
+ $query.= '
AND c.validation_date <= \''.$end.'\'';
}
- $query .= get_std_sql_where_restrict_filter('AND').'
-;';
+ $query.= get_std_sql_where_restrict_filter('AND');
break;
+ }
+
case 'unvalidated_comments':
+ {
$query = '
FROM '.COMMENTS_TABLE.'
WHERE 1=1';
if (!empty($start))
{
- $query .= ' AND date> \''.$start.'\'';
+ $query.= '
+ AND date > \''.$start.'\'';
}
if (!empty($end))
{
- $query .= ' AND date <= \''.$end.'\'';
+ $query.= '
+ AND date <= \''.$end.'\'';
}
- $query .= ' AND validated = \'false\'
-;';
+ $query.= '
+ AND validated = \'false\'';
break;
+ }
+
case 'new_elements':
+ {
$query = '
- FROM '.IMAGES_TABLE.' INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON image_id = id
+ FROM '.IMAGES_TABLE.'
+ INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON image_id = id
WHERE 1=1';
if (!empty($start))
{
- $query .= ' AND date_available > \''.$start.'\'';
+ $query.= '
+ AND date_available > \''.$start.'\'';
}
if (!empty($end))
{
- $query .= ' AND date_available <= \''.$end.'\'';
+ $query.= '
+ AND date_available <= \''.$end.'\'';
}
- $query .= get_std_sql_where_restrict_filter('AND', 'id').'
-;';
+ $query.= get_std_sql_where_restrict_filter('AND', 'id');
break;
+ }
+
case 'updated_categories':
+ {
$query = '
- FROM '.IMAGES_TABLE.' INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON image_id = id
+ FROM '.IMAGES_TABLE.'
+ INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON image_id = id
WHERE 1=1';
if (!empty($start))
{
- $query .= ' AND date_available > \''.$start.'\'';
+ $query.= '
+ AND date_available > \''.$start.'\'';
}
if (!empty($end))
{
- $query .= ' AND date_available <= \''.$end.'\'';
+ $query.= '
+ AND date_available <= \''.$end.'\'';
}
- $query .= get_std_sql_where_restrict_filter('AND', 'id').'
-;';
+ $query.= get_std_sql_where_restrict_filter('AND', 'id');
break;
+ }
+
case 'new_users':
+ {
$query = '
FROM '.USER_INFOS_TABLE.'
WHERE 1=1';
if (!empty($start))
{
- $query .= ' AND registration_date > \''.$start.'\'';
+ $query.= '
+ AND registration_date > \''.$start.'\'';
}
if (!empty($end))
{
- $query .= ' AND registration_date <= \''.$end.'\'';
+ $query.= '
+ AND registration_date <= \''.$end.'\'';
}
- $query .= '
-;';
break;
+ }
+
default:
- // stop this function and return nothing
- return;
- break;
+ return null; // stop and return nothing
}
switch($action)
{
case 'count':
+ {
switch($type)
{
case 'new_comments':
@@ -171,183 +190,166 @@ function custom_notification_query($action, $type, $start, $end)
case 'new_users':
$field_id = 'user_id';
break;
+ }
+ $query = 'SELECT COUNT(DISTINCT '.$field_id.') '.$query.';';
+ list($count) = pwg_db_fetch_row(pwg_query($query));
+ return $count;
+ break;
}
- $query = 'SELECT count(distinct '.$field_id.') as CountId
-'.$query;
- list($count) = pwg_db_fetch_row(pwg_query($query));
- return $count;
- break;
case 'info':
+ {
switch($type)
{
case 'new_comments':
- $fields = array('c.id');
+ $field_id = 'c.id';
break;
case 'unvalidated_comments':
- $fields = array('id');
+ $field_id = 'id';
break;
case 'new_elements':
- $fields = array('image_id');
+ $field_id = 'image_id';
break;
case 'updated_categories':
- $fields = array('category_id');
+ $field_id = 'category_id';
break;
case 'new_users':
- $fields = array('user_id');
+ $field_id = 'user_id';
break;
}
-
- $query = 'SELECT distinct '.implode(', ', $fields).'
-'.$query;
- $result = pwg_query($query);
-
- $infos = array();
-
- while ($row = pwg_db_fetch_assoc($result))
- {
- $infos[] = $row;
+ $query = 'SELECT DISTINCT '.$field_id.' '.$query.';';
+ $infos = array_from_query($query);
+ return $infos;
+ break;
}
- return $infos;
-
- break;
+ default:
+ return null; // stop and return nothing
}
-
- //return is done on previous switch($action)
}
/**
- * new comments between two dates, according to authorized categories
+ * Returns number of new comments between two dates.
*
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @param string forbidden categories (comma separated)
- * @return count comment ids
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int
*/
-function nb_new_comments($start, $end)
+function nb_new_comments($start=null, $end=null)
{
return custom_notification_query('count', 'new_comments', $start, $end);
}
/**
- * new comments between two dates, according to authorized categories
+ * Returns new comments between two dates.
*
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @param string forbidden categories (comma separated)
- * @return array comment ids
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int[] comment ids
*/
-function new_comments($start, $end)
+function new_comments($start=null, $end=null)
{
return custom_notification_query('info', 'new_comments', $start, $end);
}
/**
- * unvalidated at a precise date
- *
- * Comments that are registered and not validated yet on a precise date
+ * Returns number of unvalidated comments between two dates.
*
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @return count comment ids
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int
*/
-function nb_unvalidated_comments($start, $end)
+function nb_unvalidated_comments($start=null, $end=null)
{
return custom_notification_query('count', 'unvalidated_comments', $start, $end);
}
/**
- * new elements between two dates, according to authorized categories
+ * Returns number of new photos between two dates.
*
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @param string forbidden categories (comma separated)
- * @return count element ids
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int
*/
-function nb_new_elements($start, $end)
+function nb_new_elements($start=null, $end=null)
{
return custom_notification_query('count', 'new_elements', $start, $end);
}
/**
- * new elements between two dates, according to authorized categories
+ * Returns new photos between two dates.es
*
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @param string forbidden categories (comma separated)
- * @return array element ids
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int[] photos ids
*/
-function new_elements($start, $end)
+function new_elements($start=null, $end=null)
{
return custom_notification_query('info', 'new_elements', $start, $end);
}
/**
- * updated categories between two dates, according to authorized categories
+ * Returns number of updated categories between two dates.
*
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @param string forbidden categories (comma separated)
- * @return count element ids
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int
*/
-function nb_updated_categories($start, $end)
+function nb_updated_categories($start=null, $end=null)
{
return custom_notification_query('count', 'updated_categories', $start, $end);
}
/**
- * updated categories between two dates, according to authorized categories
+ * Returns updated categories between two dates.
*
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @param string forbidden categories (comma separated)
- * @return array element ids
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int[] categories ids
*/
-function updated_categories($start, $end)
+function updated_categories($start=null, $end=null)
{
return custom_notification_query('info', 'updated_categories', $start, $end);
}
/**
- * new registered users between two dates
+ * Returns number of new users between two dates.
*
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @return count user ids
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int
*/
-function nb_new_users($start, $end)
+function nb_new_users($start=null, $end=null)
{
return custom_notification_query('count', 'new_users', $start, $end);
}
/**
- * new registered users between two dates
+ * Returns new users between two dates.
*
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @return array user ids
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int[] user ids
*/
-function new_users($start, $end)
+function new_users($start=null, $end=null)
{
return custom_notification_query('info', 'new_users', $start, $end);
}
/**
- * There are new between two dates ?
+ * Returns if there was new activity between two dates.
*
- * Informations : number of new comments, number of new elements, number of
- * updated categories. Administrators are also informed about : number of
- * unvalidated comments, number of new users (TODO : number of unvalidated
- * elements)
+ * Takes in account: number of new comments, number of new elements, number of
+ * updated categories. Administrators are also informed about: number of
+ * unvalidated comments, number of new users.
+ * TODO : number of unvalidated elements
*
- * @param string start date (mysql datetime format)
- * @param string end date (mysql datetime format)
- *
- * @return boolean : true if exist news else false
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return boolean
*/
-function news_exists($start, $end)
+function news_exists($start=null, $end=null)
{
return (
(nb_new_comments($start, $end) > 0) or
@@ -359,12 +361,19 @@ function news_exists($start, $end)
/**
* Formats a news line and adds it to the array (e.g. '5 new elements')
+ *
+ * @param array $news
+ * @param int $count
+ * @param string $singular_key
+ * @param string $plural_key
+ * @param string $url
+ * @param bool $add_url
*/
-function add_news_line(&$news, $count, $singular_fmt_key, $plural_fmt_key, $url='', $add_url=false)
+function add_news_line(&$news, $count, $singular_key, $plural_key, $url='', $add_url=false)
{
if ($count > 0)
{
- $line = l10n_dec($singular_fmt_key, $plural_fmt_key, $count);
+ $line = l10n_dec($singular_key, $plural_key, $count);
if ($add_url and !empty($url) )
{
$line = '<a href="'.$url.'">'.$line.'</a>';
@@ -374,21 +383,20 @@ function add_news_line(&$news, $count, $singular_fmt_key, $plural_fmt_key, $url=
}
/**
- * What's new between two dates ?
+ * Returns new activity between two dates.
*
- * Informations : number of new comments, number of new elements, number of
- * updated categories. Administrators are also informed about : number of
- * unvalidated comments, number of new users (TODO : number of unvalidated
- * elements)
+ * Takes in account: number of new comments, number of new elements, number of
+ * updated categories. Administrators are also informed about: number of
+ * unvalidated comments, number of new users.
+ * TODO : number of unvalidated elements
*
- * @param string start date (mysql datetime format)
- * @param string end date (mysql datetime format)
- * @param bool exclude_img_cats if true, no info about new images/categories
- * @param bool add_url add html A link around news
- *
- * @return array of news
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @param bool $exclude_img_cats if true, no info about new images/categories
+ * @param bool $add_url add html link around news
+ * @return array
*/
-function news($start, $end, $exclude_img_cats=false, $add_url=false)
+function news($start=null, $end=null, $exclude_img_cats=false, $add_url=false)
{
$news = array();
@@ -425,10 +433,12 @@ function news($start, $end, $exclude_img_cats=false, $add_url=false)
}
/**
- * returns information about recently published elements grouped by post date
- * @param int max_dates maximum returned number of recent dates
- * @param int max_elements maximum returned number of elements per date
- * @param int max_cats maximum returned number of categories per date
+ * Returns information about recently published elements grouped by post date.
+ *
+ * @param int $max_dates maximum number of recent dates
+ * @param int $max_elements maximum number of elements per date
+ * @param int $max_cats maximum number of categories per date
+ * @return array
*/
function get_recent_post_dates($max_dates, $max_elements, $max_cats)
{
@@ -437,21 +447,17 @@ function get_recent_post_dates($max_dates, $max_elements, $max_cats)
$where_sql = get_std_sql_where_restrict_filter('WHERE', 'i.id', true);
$query = '
-SELECT date_available,
- COUNT(DISTINCT id) AS nb_elements,
- COUNT(DISTINCT category_id) AS nb_cats
+SELECT
+ date_available,
+ COUNT(DISTINCT id) AS nb_elements,
+ COUNT(DISTINCT category_id) AS nb_cats
FROM '.IMAGES_TABLE.' i INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON id=image_id
'.$where_sql.'
GROUP BY date_available
ORDER BY date_available DESC
LIMIT '.$max_dates.'
;';
- $result = pwg_query($query);
- $dates = array();
- while ($row = pwg_db_fetch_assoc($result))
- {
- $dates[] = $row;
- }
+ $dates = array_from_query($query);
for ($i=0; $i<count($dates); $i++)
{
@@ -459,25 +465,24 @@ SELECT date_available,
{ // get some thumbnails ...
$query = '
SELECT DISTINCT i.*
- FROM '.IMAGES_TABLE.' i INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON id=image_id
+ FROM '.IMAGES_TABLE.' i
+ INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON id=image_id
'.$where_sql.'
AND date_available=\''.$dates[$i]['date_available'].'\'
ORDER BY '.DB_RANDOM_FUNCTION.'()
LIMIT '.$max_elements.'
;';
- $dates[$i]['elements'] = array();
- $result = pwg_query($query);
- while ($row = pwg_db_fetch_assoc($result))
- {
- $dates[$i]['elements'][] = $row;
- }
+ $dates[$i]['elements'] = array_from_query($query);
}
if ($max_cats>0)
{// get some categories ...
$query = '
-SELECT DISTINCT c.uppercats, COUNT(DISTINCT i.id) AS img_count
- FROM '.IMAGES_TABLE.' i INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON i.id=image_id
+SELECT
+ DISTINCT c.uppercats,
+ COUNT(DISTINCT i.id) AS img_count
+ FROM '.IMAGES_TABLE.' i
+ INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON i.id=image_id
INNER JOIN '.CATEGORIES_TABLE.' c ON c.id=category_id
'.$where_sql.'
AND date_available=\''.$dates[$i]['date_available'].'\'
@@ -485,37 +490,37 @@ SELECT DISTINCT c.uppercats, COUNT(DISTINCT i.id) AS img_count
ORDER BY img_count DESC
LIMIT '.$max_cats.'
;';
- $dates[$i]['categories'] = array();
- $result = pwg_query($query);
- while ($row = pwg_db_fetch_assoc($result))
- {
- $dates[$i]['categories'][] = $row;
- }
+ $dates[$i]['categories'] = array_from_query($query);
}
}
+
return $dates;
}
-/*
- Call function get_recent_post_dates but
- the parameters to be passed to the function, as an indexed array.
-
-*/
+/**
+ * Returns information about recently published elements grouped by post date.
+ * Same as get_recent_post_dates() but parameters as an indexed array.
+ * @see get_recent_post_dates()
+ *
+ * @param array $args
+ * @return array
+ */
function get_recent_post_dates_array($args)
{
- return
- get_recent_post_dates
- (
- (empty($args['max_dates']) ? 3 : $args['max_dates']),
- (empty($args['max_elements']) ? 3 : $args['max_elements']),
- (empty($args['max_cats']) ? 3 : $args['max_cats'])
+ return get_recent_post_dates(
+ (empty($args['max_dates']) ? 3 : $args['max_dates']),
+ (empty($args['max_elements']) ? 3 : $args['max_elements']),
+ (empty($args['max_cats']) ? 3 : $args['max_cats'])
);
}
/**
- * returns html description about recently published elements grouped by post date
- * @param $date_detail: selected date computed by get_recent_post_dates function
+ * Returns html description about recently published elements grouped by post date.
+ * TODO : clean up HTML output, currently messy and invalid !
+ *
+ * @param array $date_detail returned value of get_recent_post_dates()
+ * @return string
*/
function get_html_description_recent_post_date($date_detail)
{
@@ -567,8 +572,10 @@ function get_html_description_recent_post_date($date_detail)
}
/**
- * returns title about recently published elements grouped by post date
- * @param $date_detail: selected date computed by get_recent_post_dates function
+ * Returns title about recently published elements grouped by post date.
+ *
+ * @param array $date_detail returned value of get_recent_post_dates()
+ * @return string
*/
function get_title_recent_post_date($date_detail)
{
@@ -583,15 +590,16 @@ function get_title_recent_post_date($date_detail)
return $title;
}
-if(!function_exists("strptime"))
+if (!function_exists('strptime'))
{
- function strptime($date, $fmt)
- {
- if ($fmt != '%Y-%m-%d %H:%M:%S')
- die('Invalid strptime format '.$fmt);
- list($y,$m,$d,$H,$M,$S) = preg_split('/[-: ]/', $date);
- $res = localtime( mktime($H,$M,$S,$m,$d,$y), true );
- return $res;
- }
- }
+ function strptime($date, $fmt)
+ {
+ if ($fmt != '%Y-%m-%d %H:%M:%S')
+ die('Invalid strptime format '.$fmt);
+ list($y,$m,$d,$H,$M,$S) = preg_split('/[-: ]/', $date);
+ $res = localtime( mktime($H,$M,$S,$m,$d,$y), true );
+ return $res;
+ }
+}
+
?> \ No newline at end of file