Index: /trunk/include/functions_notification.inc.php
===================================================================
--- /trunk/include/functions_notification.inc.php	(revision 25577)
+++ /trunk/include/functions_notification.inc.php	(revision 25578)
@@ -22,45 +22,45 @@
 // +-----------------------------------------------------------------------+
 
-// +-----------------------------------------------------------------------+
-// |                               functions                               |
-// +-----------------------------------------------------------------------+
-
-/*
- * get standard sql where in order to
- * restict an filter caregories and images
- *
- * IMAGE_CATEGORY_TABLE muste named ic in the query
- *
- * @param none
- *
- * @return string sql where
- */
-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
-          );
-}
-
-/*
- * 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)
- *
- * @return integer for action count
- *         array for info
- */
-function custom_notification_query($action, $type, $start, $end)
+/**
+ * @package functions\notification
+ */
+ 
+// TODO : use a cache for all data returned by custom_notification_query()
+
+
+/**
+ * Get standard sql where in order to restrict and filter categories and images.
+ * IMAGE_CATEGORY_TABLE must be named "ic" in the query
+ *
+ * @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)
+{
+  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', '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=null, $end=null)
 {
   global $user;
@@ -69,22 +69,25 @@
   {
     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.'
@@ -92,44 +95,59 @@
       if (!empty($start))
       {
-	$query .= ' AND date> \''.$start.'\'';
+        $query.= '
+    AND date > \''.$start.'\'';
       }
       if (!empty($end))
       {
-	$query .= ' AND date <= \''.$end.'\'';
-      }
-      $query .= ' AND validated = \'false\'
-;';
+        $query.= '
+    AND date <= \''.$end.'\'';
+      }
+      $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 .= get_std_sql_where_restrict_filter('AND', 'id').'
-;';
+        $query.= '
+    AND date_available <= \''.$end.'\'';
+      }
+      $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 .= get_std_sql_where_restrict_filter('AND', 'id').'
-;';
+        $query.= '
+    AND date_available <= \''.$end.'\'';
+      }
+      $query.= get_std_sql_where_restrict_filter('AND', 'id');
       break;
+    }
+
     case 'new_users':
+    {
       $query = '
   FROM '.USER_INFOS_TABLE.'
@@ -137,17 +155,17 @@
       if (!empty($start))
       {
-	$query .= ' AND registration_date > \''.$start.'\'';
+        $query.= '
+    AND registration_date > \''.$start.'\'';
       }
       if (!empty($end))
       {
-	$query .= ' AND registration_date <= \''.$end.'\'';
-      }
-      $query .= '
-;';
+        $query.= '
+    AND registration_date <= \''.$end.'\'';
+      }
       break;
+    }
+
     default:
-      // stop this function and return nothing
-      return;
-      break;
+      return null; // stop and return nothing
   }
 
@@ -155,4 +173,5 @@
   {
     case 'count':
+    {
       switch($type)
       {
@@ -172,59 +191,50 @@
           $field_id = 'user_id';
           break;
-    }
-    $query = 'SELECT count(distinct '.$field_id.') as CountId
-'.$query;
-    list($count) = pwg_db_fetch_row(pwg_query($query));
-    return $count;
-
-    break;
+      }
+      $query = 'SELECT COUNT(DISTINCT '.$field_id.') '.$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');
-          break;
-      }
-
-    $query = 'SELECT distinct '.implode(', ', $fields).'
-'.$query;
-    $result = pwg_query($query);
-
-    $infos = array();
-
-    while ($row = pwg_db_fetch_assoc($result))
-    {
-      $infos[] = $row;
-    }
-
-    return $infos;
-
-    break;
-  }
-
-  //return is done on previous switch($action)
-}
-
-/**
- * new comments between two dates, according to authorized categories
- *
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @param string forbidden categories (comma separated)
- * @return count comment ids
- */
-function nb_new_comments($start, $end)
+          $field_id = 'user_id';
+          break;
+      }
+      $query = 'SELECT DISTINCT '.$field_id.' '.$query.';';
+      $infos = array_from_query($query);
+      return $infos;
+      break;
+    }
+
+    default:
+      return null; // stop and return nothing
+  }
+}
+
+/**
+ * Returns number of new comments between two dates.
+ *
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int
+ */
+function nb_new_comments($start=null, $end=null)
 {
   return custom_notification_query('count', 'new_comments', $start, $end);
@@ -232,12 +242,11 @@
 
 /**
- * new comments between two dates, according to authorized categories
- *
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @param string forbidden categories (comma separated)
- * @return array comment ids
- */
-function new_comments($start, $end)
+ * Returns new comments between two dates.
+ *
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int[] comment ids
+ */
+function new_comments($start=null, $end=null)
 {
   return custom_notification_query('info', 'new_comments', $start, $end);
@@ -245,13 +254,11 @@
 
 /**
- * unvalidated at a precise date
- *
- * Comments that are registered and not validated yet on a precise date
- *
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @return count comment ids
- */
-function nb_unvalidated_comments($start, $end)
+ * Returns number of unvalidated comments between two dates.
+ *
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int
+ */
+function nb_unvalidated_comments($start=null, $end=null)
 {
   return custom_notification_query('count', 'unvalidated_comments', $start, $end);
@@ -260,12 +267,11 @@
 
 /**
- * new elements between two dates, according to authorized categories
- *
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @param string forbidden categories (comma separated)
- * @return count element ids
- */
-function nb_new_elements($start, $end)
+ * Returns number of new photos between two dates.
+ *
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int
+ */
+function nb_new_elements($start=null, $end=null)
 {
   return custom_notification_query('count', 'new_elements', $start, $end);
@@ -273,12 +279,11 @@
 
 /**
- * new elements between two dates, according to authorized categories
- *
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @param string forbidden categories (comma separated)
- * @return array element ids
- */
-function new_elements($start, $end)
+ * Returns new photos between two dates.es
+ *
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int[] photos ids
+ */
+function new_elements($start=null, $end=null)
 {
   return custom_notification_query('info', 'new_elements', $start, $end);
@@ -286,12 +291,11 @@
 
 /**
- * updated categories between two dates, according to authorized categories
- *
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @param string forbidden categories (comma separated)
- * @return count element ids
- */
-function nb_updated_categories($start, $end)
+ * Returns number of updated categories between two dates.
+ *
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int
+ */
+function nb_updated_categories($start=null, $end=null)
 {
   return custom_notification_query('count', 'updated_categories', $start, $end);
@@ -299,12 +303,11 @@
 
 /**
- * updated categories between two dates, according to authorized categories
- *
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @param string forbidden categories (comma separated)
- * @return array element ids
- */
-function updated_categories($start, $end)
+ * Returns updated categories between two dates.
+ *
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int[] categories ids
+ */
+function updated_categories($start=null, $end=null)
 {
   return custom_notification_query('info', 'updated_categories', $start, $end);
@@ -312,11 +315,11 @@
 
 /**
- * new registered users between two dates
- *
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @return count user ids
- */
-function nb_new_users($start, $end)
+ * Returns number of new users between two dates.
+ *
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int
+ */
+function nb_new_users($start=null, $end=null)
 {
   return custom_notification_query('count', 'new_users', $start, $end);
@@ -324,11 +327,11 @@
 
 /**
- * new registered users between two dates
- *
- * @param string start (mysql datetime format)
- * @param string end (mysql datetime format)
- * @return array user ids
- */
-function new_users($start, $end)
+ * Returns new users between two dates.
+ *
+ * @param string $start (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return int[] user ids
+ */
+function new_users($start=null, $end=null)
 {
   return custom_notification_query('info', 'new_users', $start, $end);
@@ -336,17 +339,16 @@
 
 /**
- * There are new 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)
- *
- * @param string start date (mysql datetime format)
- * @param string end date (mysql datetime format)
- *
- * @return boolean : true if exist news else false
- */
-function news_exists($start, $end)
+ * Returns if there was new activity between two dates.
+ *
+ * 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 (mysql datetime format)
+ * @param string $end (mysql datetime format)
+ * @return boolean
+ */
+function news_exists($start=null, $end=null)
 {
   return (
@@ -360,10 +362,17 @@
 /**
  * Formats a news line and adds it to the array (e.g. '5 new elements')
- */
-function add_news_line(&$news, $count, $singular_fmt_key, $plural_fmt_key, $url='', $add_url=false)
+ *
+ * @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_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) )
     {
@@ -375,19 +384,18 @@
 
 /**
- * What's new 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)
- *
- * @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
- */
-function news($start, $end, $exclude_img_cats=false, $add_url=false)
+ * Returns new activity between two dates.
+ *
+ * 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 (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=null, $end=null, $exclude_img_cats=false, $add_url=false)
 {
   $news = array();
@@ -426,8 +434,10 @@
 
 /**
- * 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)
@@ -438,7 +448,8 @@
 
   $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.'
@@ -447,10 +458,5 @@
   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++)
@@ -460,5 +466,6 @@
       $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'].'\'
@@ -466,10 +473,5 @@
   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);
     }
 
@@ -477,6 +479,9 @@
     {// 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.'
@@ -486,28 +491,25 @@
   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'])
     );
 }
@@ -515,6 +517,9 @@
 
 /**
- * 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)
@@ -568,6 +573,8 @@
 
 /**
- * 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)
@@ -584,14 +591,15 @@
 }
 
-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;
-		}
- }
+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;
+  }
+}
+
 ?>
