From 68bbe763cf0b0df337676a6dca6e2f9add089019 Mon Sep 17 00:00:00 2001 From: mistic100 Date: Tue, 19 Nov 2013 18:45:48 +0000 Subject: feature 2999: Documentation of include/functions_notification + clean code git-svn-id: http://piwigo.org/svn/trunk@25578 68402e56-0260-453c-a942-63ccdbb3a9ee --- include/functions_notification.inc.php | 438 +++++++++++++++++---------------- 1 file changed, 223 insertions(+), 215 deletions(-) (limited to 'include/functions_notification.inc.php') 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 = ''.$line.''; @@ -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; $i0) {// 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 -- cgit v1.2.3