Changeset 25578 for trunk


Ignore:
Timestamp:
Nov 19, 2013, 7:45:48 PM (10 years ago)
Author:
mistic100
Message:

feature 2999: Documentation of include/functions_notification + clean code

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/functions_notification.inc.php

    r25018 r25578  
    2222// +-----------------------------------------------------------------------+
    2323
    24 // +-----------------------------------------------------------------------+
    25 // |                               functions                               |
    26 // +-----------------------------------------------------------------------+
    27 
    28 /*
    29  * get standard sql where in order to
    30  * restict an filter caregories and images
    31  *
    32  * IMAGE_CATEGORY_TABLE muste named ic in the query
    33  *
    34  * @param none
    35  *
    36  * @return string sql where
    37  */
    38 function get_std_sql_where_restrict_filter($prefix_condition, $img_field='ic.image_id', $force_one_condition = false)
    39 {
    40   return get_sql_condition_FandF
    41           (
    42             array
    43               (
    44                 'forbidden_categories' => 'ic.category_id',
    45                 'visible_categories' => 'ic.category_id',
    46                 'visible_images' => $img_field
    47               ),
    48             $prefix_condition,
    49             $force_one_condition
    50           );
    51 }
    52 
    53 /*
    54  * Execute custom notification query
    55  *
    56  * @param string action ('count' or 'info')
    57  * @param string type of query ('new_comments', 'unvalidated_comments', 'new_elements', 'updated_categories', 'new_users')
    58  * @param string start (mysql datetime format)
    59  * @param string end (mysql datetime format)
    60  *
    61  * @return integer for action count
    62  *         array for info
    63  */
    64 function custom_notification_query($action, $type, $start, $end)
     24/**
     25 * @package functions\notification
     26 */
     27 
     28// TODO : use a cache for all data returned by custom_notification_query()
     29
     30
     31/**
     32 * Get standard sql where in order to restrict and filter categories and images.
     33 * IMAGE_CATEGORY_TABLE must be named "ic" in the query
     34 *
     35 * @param string $prefix_condition
     36 * @param string $img_field
     37 * @param bool $force_one_condition
     38 * @return string
     39 */
     40function get_std_sql_where_restrict_filter($prefix_condition,
     41                                           $img_field = 'ic.image_id',
     42                                           $force_one_condition = false)
     43{
     44  return get_sql_condition_FandF(
     45    array(
     46      'forbidden_categories' => 'ic.category_id',
     47      'visible_categories' => 'ic.category_id',
     48      'visible_images' => $img_field
     49      ),
     50    $prefix_condition,
     51    $force_one_condition
     52    );
     53}
     54
     55/**
     56 * Execute custom notification query.
     57 *
     58 * @param string $action 'count', 'info'
     59 * @param string $type 'new_comments', 'unvalidated_comments', 'new_elements', 'updated_categories', 'new_users'
     60 * @param string $start (mysql datetime format)
     61 * @param string $end (mysql datetime format)
     62 * @return int|array int for action count array for info
     63 */
     64function custom_notification_query($action, $type, $start=null, $end=null)
    6565{
    6666  global $user;
    … …  
    6969  {
    7070    case 'new_comments':
     71    {
    7172      $query = '
    7273  FROM '.COMMENTS_TABLE.' AS c
    73      , '.IMAGE_CATEGORY_TABLE.' AS ic
    74   WHERE c.image_id = ic.image_id';
     74    INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON c.image_id = ic.image_id
     75  WHERE 1=1';
    7576      if (!empty($start))
    7677      {
    77         $query .= '
     78        $query.= '
    7879    AND c.validation_date > \''.$start.'\'';
    7980      }
    8081      if (!empty($end))
    8182      {
    82         $query .= '
     83        $query.= '
    8384    AND c.validation_date <= \''.$end.'\'';
    8485      }
    85       $query .= get_std_sql_where_restrict_filter('AND').'
    86 ;';
     86      $query.= get_std_sql_where_restrict_filter('AND');
    8787      break;
     88    }
     89
    8890    case 'unvalidated_comments':
     91    {
    8992      $query = '
    9093  FROM '.COMMENTS_TABLE.'
    … …  
    9295      if (!empty($start))
    9396      {
    94         $query .= ' AND date> \''.$start.'\'';
     97        $query.= '
     98    AND date > \''.$start.'\'';
    9599      }
    96100      if (!empty($end))
    97101      {
    98         $query .= ' AND date <= \''.$end.'\'';
    99       }
    100       $query .= ' AND validated = \'false\'
    101 ;';
     102        $query.= '
     103    AND date <= \''.$end.'\'';
     104      }
     105      $query.= '
     106    AND validated = \'false\'';
    102107      break;
     108    }
     109
    103110    case 'new_elements':
     111    {
    104112      $query = '
    105   FROM '.IMAGES_TABLE.' INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON image_id = id
     113  FROM '.IMAGES_TABLE.'
     114    INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON image_id = id
    106115  WHERE 1=1';
    107116      if (!empty($start))
    108117      {
    109         $query .= ' AND date_available > \''.$start.'\'';
     118        $query.= '
     119    AND date_available > \''.$start.'\'';
    110120      }
    111121      if (!empty($end))
    112122      {
    113         $query .= ' AND date_available <= \''.$end.'\'';
    114       }
    115       $query .= get_std_sql_where_restrict_filter('AND', 'id').'
    116 ;';
     123        $query.= '
     124    AND date_available <= \''.$end.'\'';
     125      }
     126      $query.= get_std_sql_where_restrict_filter('AND', 'id');
    117127      break;
     128    }
     129
    118130    case 'updated_categories':
     131    {
    119132      $query = '
    120   FROM '.IMAGES_TABLE.' INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON image_id = id
     133  FROM '.IMAGES_TABLE.'
     134    INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON image_id = id
    121135  WHERE 1=1';
    122136      if (!empty($start))
    123137      {
    124         $query .= ' AND date_available > \''.$start.'\'';
     138        $query.= '
     139    AND date_available > \''.$start.'\'';
    125140      }
    126141      if (!empty($end))
    127142      {
    128         $query .= ' AND date_available <= \''.$end.'\'';
    129       }
    130       $query .= get_std_sql_where_restrict_filter('AND', 'id').'
    131 ;';
     143        $query.= '
     144    AND date_available <= \''.$end.'\'';
     145      }
     146      $query.= get_std_sql_where_restrict_filter('AND', 'id');
    132147      break;
     148    }
     149
    133150    case 'new_users':
     151    {
    134152      $query = '
    135153  FROM '.USER_INFOS_TABLE.'
    … …  
    137155      if (!empty($start))
    138156      {
    139         $query .= ' AND registration_date > \''.$start.'\'';
     157        $query.= '
     158    AND registration_date > \''.$start.'\'';
    140159      }
    141160      if (!empty($end))
    142161      {
    143         $query .= ' AND registration_date <= \''.$end.'\'';
    144       }
    145       $query .= '
    146 ;';
     162        $query.= '
     163    AND registration_date <= \''.$end.'\'';
     164      }
    147165      break;
     166    }
     167
    148168    default:
    149       // stop this function and return nothing
    150       return;
    151       break;
     169      return null; // stop and return nothing
    152170  }
    153171
    … …  
    155173  {
    156174    case 'count':
     175    {
    157176      switch($type)
    158177      {
    … …  
    172191          $field_id = 'user_id';
    173192          break;
    174     }
    175     $query = 'SELECT count(distinct '.$field_id.') as CountId
    176 '.$query;
    177     list($count) = pwg_db_fetch_row(pwg_query($query));
    178     return $count;
    179 
    180     break;
     193      }
     194      $query = 'SELECT COUNT(DISTINCT '.$field_id.') '.$query.';';
     195      list($count) = pwg_db_fetch_row(pwg_query($query));
     196      return $count;
     197      break;
     198    }
     199
    181200    case 'info':
     201    {
    182202      switch($type)
    183203      {
    184204        case 'new_comments':
    185           $fields = array('c.id');
     205          $field_id = 'c.id';
    186206          break;
    187207        case 'unvalidated_comments':
    188           $fields = array('id');
     208          $field_id = 'id';
    189209          break;
    190210        case 'new_elements':
    191           $fields = array('image_id');
     211          $field_id = 'image_id';
    192212          break;
    193213        case 'updated_categories':
    194           $fields = array('category_id');
     214          $field_id = 'category_id';
    195215          break;
    196216        case 'new_users':
    197           $fields = array('user_id');
    198           break;
    199       }
    200 
    201     $query = 'SELECT distinct '.implode(', ', $fields).'
    202 '.$query;
    203     $result = pwg_query($query);
    204 
    205     $infos = array();
    206 
    207     while ($row = pwg_db_fetch_assoc($result))
    208     {
    209       $infos[] = $row;
    210     }
    211 
    212     return $infos;
    213 
    214     break;
    215   }
    216 
    217   //return is done on previous switch($action)
    218 }
    219 
    220 /**
    221  * new comments between two dates, according to authorized categories
    222  *
    223  * @param string start (mysql datetime format)
    224  * @param string end (mysql datetime format)
    225  * @param string forbidden categories (comma separated)
    226  * @return count comment ids
    227  */
    228 function nb_new_comments($start, $end)
     217          $field_id = 'user_id';
     218          break;
     219      }
     220      $query = 'SELECT DISTINCT '.$field_id.' '.$query.';';
     221      $infos = array_from_query($query);
     222      return $infos;
     223      break;
     224    }
     225
     226    default:
     227      return null; // stop and return nothing
     228  }
     229}
     230
     231/**
     232 * Returns number of new comments between two dates.
     233 *
     234 * @param string $start (mysql datetime format)
     235 * @param string $end (mysql datetime format)
     236 * @return int
     237 */
     238function nb_new_comments($start=null, $end=null)
    229239{
    230240  return custom_notification_query('count', 'new_comments', $start, $end);
    … …  
    232242
    233243/**
    234  * new comments between two dates, according to authorized categories
    235  *
    236  * @param string start (mysql datetime format)
    237  * @param string end (mysql datetime format)
    238  * @param string forbidden categories (comma separated)
    239  * @return array comment ids
    240  */
    241 function new_comments($start, $end)
     244 * Returns new comments between two dates.
     245 *
     246 * @param string $start (mysql datetime format)
     247 * @param string $end (mysql datetime format)
     248 * @return int[] comment ids
     249 */
     250function new_comments($start=null, $end=null)
    242251{
    243252  return custom_notification_query('info', 'new_comments', $start, $end);
    … …  
    245254
    246255/**
    247  * unvalidated at a precise date
    248  *
    249  * Comments that are registered and not validated yet on a precise date
    250  *
    251  * @param string start (mysql datetime format)
    252  * @param string end (mysql datetime format)
    253  * @return count comment ids
    254  */
    255 function nb_unvalidated_comments($start, $end)
     256 * Returns number of unvalidated comments between two dates.
     257 *
     258 * @param string $start (mysql datetime format)
     259 * @param string $end (mysql datetime format)
     260 * @return int
     261 */
     262function nb_unvalidated_comments($start=null, $end=null)
    256263{
    257264  return custom_notification_query('count', 'unvalidated_comments', $start, $end);
    … …  
    260267
    261268/**
    262  * new elements between two dates, according to authorized categories
    263  *
    264  * @param string start (mysql datetime format)
    265  * @param string end (mysql datetime format)
    266  * @param string forbidden categories (comma separated)
    267  * @return count element ids
    268  */
    269 function nb_new_elements($start, $end)
     269 * Returns number of new photos between two dates.
     270 *
     271 * @param string $start (mysql datetime format)
     272 * @param string $end (mysql datetime format)
     273 * @return int
     274 */
     275function nb_new_elements($start=null, $end=null)
    270276{
    271277  return custom_notification_query('count', 'new_elements', $start, $end);
    … …  
    273279
    274280/**
    275  * new elements between two dates, according to authorized categories
    276  *
    277  * @param string start (mysql datetime format)
    278  * @param string end (mysql datetime format)
    279  * @param string forbidden categories (comma separated)
    280  * @return array element ids
    281  */
    282 function new_elements($start, $end)
     281 * Returns new photos between two dates.es
     282 *
     283 * @param string $start (mysql datetime format)
     284 * @param string $end (mysql datetime format)
     285 * @return int[] photos ids
     286 */
     287function new_elements($start=null, $end=null)
    283288{
    284289  return custom_notification_query('info', 'new_elements', $start, $end);
    … …  
    286291
    287292/**
    288  * updated categories between two dates, according to authorized categories
    289  *
    290  * @param string start (mysql datetime format)
    291  * @param string end (mysql datetime format)
    292  * @param string forbidden categories (comma separated)
    293  * @return count element ids
    294  */
    295 function nb_updated_categories($start, $end)
     293 * Returns number of updated categories between two dates.
     294 *
     295 * @param string $start (mysql datetime format)
     296 * @param string $end (mysql datetime format)
     297 * @return int
     298 */
     299function nb_updated_categories($start=null, $end=null)
    296300{
    297301  return custom_notification_query('count', 'updated_categories', $start, $end);
    … …  
    299303
    300304/**
    301  * updated categories between two dates, according to authorized categories
    302  *
    303  * @param string start (mysql datetime format)
    304  * @param string end (mysql datetime format)
    305  * @param string forbidden categories (comma separated)
    306  * @return array element ids
    307  */
    308 function updated_categories($start, $end)
     305 * Returns updated categories between two dates.
     306 *
     307 * @param string $start (mysql datetime format)
     308 * @param string $end (mysql datetime format)
     309 * @return int[] categories ids
     310 */
     311function updated_categories($start=null, $end=null)
    309312{
    310313  return custom_notification_query('info', 'updated_categories', $start, $end);
    … …  
    312315
    313316/**
    314  * new registered users between two dates
    315  *
    316  * @param string start (mysql datetime format)
    317  * @param string end (mysql datetime format)
    318  * @return count user ids
    319  */
    320 function nb_new_users($start, $end)
     317 * Returns number of new users between two dates.
     318 *
     319 * @param string $start (mysql datetime format)
     320 * @param string $end (mysql datetime format)
     321 * @return int
     322 */
     323function nb_new_users($start=null, $end=null)
    321324{
    322325  return custom_notification_query('count', 'new_users', $start, $end);
    … …  
    324327
    325328/**
    326  * new registered users between two dates
    327  *
    328  * @param string start (mysql datetime format)
    329  * @param string end (mysql datetime format)
    330  * @return array user ids
    331  */
    332 function new_users($start, $end)
     329 * Returns new users between two dates.
     330 *
     331 * @param string $start (mysql datetime format)
     332 * @param string $end (mysql datetime format)
     333 * @return int[] user ids
     334 */
     335function new_users($start=null, $end=null)
    333336{
    334337  return custom_notification_query('info', 'new_users', $start, $end);
    … …  
    336339
    337340/**
    338  * There are new between two dates ?
    339  *
    340  * Informations : number of new comments, number of new elements, number of
    341  * updated categories. Administrators are also informed about : number of
    342  * unvalidated comments, number of new users (TODO : number of unvalidated
    343  * elements)
    344  *
    345  * @param string start date (mysql datetime format)
    346  * @param string end date (mysql datetime format)
    347  *
    348  * @return boolean : true if exist news else false
    349  */
    350 function news_exists($start, $end)
     341 * Returns if there was new activity between two dates.
     342 *
     343 * Takes in account: number of new comments, number of new elements, number of
     344 * updated categories. Administrators are also informed about: number of
     345 * unvalidated comments, number of new users.
     346 * TODO : number of unvalidated elements
     347 *
     348 * @param string $start (mysql datetime format)
     349 * @param string $end (mysql datetime format)
     350 * @return boolean
     351 */
     352function news_exists($start=null, $end=null)
    351353{
    352354  return (
    … …  
    360362/**
    361363 * Formats a news line and adds it to the array (e.g. '5 new elements')
    362  */
    363 function add_news_line(&$news, $count, $singular_fmt_key, $plural_fmt_key, $url='', $add_url=false)
     364 *
     365 * @param array $news
     366 * @param int $count
     367 * @param string $singular_key
     368 * @param string $plural_key
     369 * @param string $url
     370 * @param bool $add_url
     371 */
     372function add_news_line(&$news, $count, $singular_key, $plural_key, $url='', $add_url=false)
    364373{
    365374  if ($count > 0)
    366375  {
    367     $line = l10n_dec($singular_fmt_key, $plural_fmt_key, $count);
     376    $line = l10n_dec($singular_key, $plural_key, $count);
    368377    if ($add_url and !empty($url) )
    369378    {
    … …  
    375384
    376385/**
    377  * What's new between two dates ?
    378  *
    379  * Informations : number of new comments, number of new elements, number of
    380  * updated categories. Administrators are also informed about : number of
    381  * unvalidated comments, number of new users (TODO : number of unvalidated
    382  * elements)
    383  *
    384  * @param string start date (mysql datetime format)
    385  * @param string end date (mysql datetime format)
    386  * @param bool exclude_img_cats if true, no info about new images/categories
    387  * @param bool add_url add html A link around news
    388  *
    389  * @return array of news
    390  */
    391 function news($start, $end, $exclude_img_cats=false, $add_url=false)
     386 * Returns new activity between two dates.
     387 *
     388 * Takes in account: number of new comments, number of new elements, number of
     389 * updated categories. Administrators are also informed about: number of
     390 * unvalidated comments, number of new users.
     391 * TODO : number of unvalidated elements
     392 *
     393 * @param string $start (mysql datetime format)
     394 * @param string $end (mysql datetime format)
     395 * @param bool $exclude_img_cats if true, no info about new images/categories
     396 * @param bool $add_url add html link around news
     397 * @return array
     398 */
     399function news($start=null, $end=null, $exclude_img_cats=false, $add_url=false)
    392400{
    393401  $news = array();
    … …  
    426434
    427435/**
    428  * returns information about recently published elements grouped by post date
    429  * @param int max_dates maximum returned number of recent dates
    430  * @param int max_elements maximum returned number of elements per date
    431  * @param int max_cats maximum returned number of categories per date
     436 * Returns information about recently published elements grouped by post date.
     437 *
     438 * @param int $max_dates maximum number of recent dates
     439 * @param int $max_elements maximum number of elements per date
     440 * @param int $max_cats maximum number of categories per date
     441 * @return array
    432442 */
    433443function get_recent_post_dates($max_dates, $max_elements, $max_cats)
    … …  
    438448
    439449  $query = '
    440 SELECT date_available,
    441       COUNT(DISTINCT id) AS nb_elements,
    442       COUNT(DISTINCT category_id) AS nb_cats
     450SELECT
     451    date_available,
     452    COUNT(DISTINCT id) AS nb_elements,
     453    COUNT(DISTINCT category_id) AS nb_cats
    443454  FROM '.IMAGES_TABLE.' i INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON id=image_id
    444455  '.$where_sql.'
    … …  
    447458  LIMIT '.$max_dates.'
    448459;';
    449   $result = pwg_query($query);
    450   $dates = array();
    451   while ($row = pwg_db_fetch_assoc($result))
    452   {
    453     $dates[] = $row;
    454   }
     460  $dates = array_from_query($query);
    455461
    456462  for ($i=0; $i<count($dates); $i++)
    … …  
    460466      $query = '
    461467SELECT DISTINCT i.*
    462   FROM '.IMAGES_TABLE.' i INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON id=image_id
     468  FROM '.IMAGES_TABLE.' i
     469    INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON id=image_id
    463470  '.$where_sql.'
    464471    AND date_available=\''.$dates[$i]['date_available'].'\'
    … …  
    466473  LIMIT '.$max_elements.'
    467474;';
    468       $dates[$i]['elements'] = array();
    469       $result = pwg_query($query);
    470       while ($row = pwg_db_fetch_assoc($result))
    471       {
    472         $dates[$i]['elements'][] = $row;
    473       }
     475      $dates[$i]['elements'] = array_from_query($query);
    474476    }
    475477
    … …  
    477479    {// get some categories ...
    478480      $query = '
    479 SELECT DISTINCT c.uppercats, COUNT(DISTINCT i.id) AS img_count
    480   FROM '.IMAGES_TABLE.' i INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON i.id=image_id
     481SELECT
     482    DISTINCT c.uppercats,
     483    COUNT(DISTINCT i.id) AS img_count
     484  FROM '.IMAGES_TABLE.' i
     485    INNER JOIN '.IMAGE_CATEGORY_TABLE.' AS ic ON i.id=image_id
    481486    INNER JOIN '.CATEGORIES_TABLE.' c ON c.id=category_id
    482487  '.$where_sql.'
    … …  
    486491  LIMIT '.$max_cats.'
    487492;';
    488       $dates[$i]['categories'] = array();
    489       $result = pwg_query($query);
    490       while ($row = pwg_db_fetch_assoc($result))
    491       {
    492         $dates[$i]['categories'][] = $row;
    493       }
    494     }
    495   }
     493      $dates[$i]['categories'] = array_from_query($query);
     494    }
     495  }
     496
    496497  return $dates;
    497498}
    498499
    499 /*
    500   Call function get_recent_post_dates but
    501   the parameters to be passed to the function, as an indexed array.
    502 
    503 */
     500/**
     501 * Returns information about recently published elements grouped by post date.
     502 * Same as get_recent_post_dates() but parameters as an indexed array.
     503 * @see get_recent_post_dates()
     504 *
     505 * @param array $args
     506 * @return array
     507 */
    504508function get_recent_post_dates_array($args)
    505509{
    506   return
    507     get_recent_post_dates
    508     (
    509       (empty($args['max_dates']) ? 3 : $args['max_dates']),
    510       (empty($args['max_elements']) ? 3 : $args['max_elements']),
    511       (empty($args['max_cats']) ? 3 : $args['max_cats'])
     510  return get_recent_post_dates(
     511    (empty($args['max_dates']) ? 3 : $args['max_dates']),
     512    (empty($args['max_elements']) ? 3 : $args['max_elements']),
     513    (empty($args['max_cats']) ? 3 : $args['max_cats'])
    512514    );
    513515}
    … …  
    515517
    516518/**
    517  * returns html description about recently published elements grouped by post date
    518  * @param $date_detail: selected date computed by get_recent_post_dates function
     519 * Returns html description about recently published elements grouped by post date.
     520 * TODO : clean up HTML output, currently messy and invalid !
     521 *
     522 * @param array $date_detail returned value of get_recent_post_dates()
     523 * @return string
    519524 */
    520525function get_html_description_recent_post_date($date_detail)
    … …  
    568573
    569574/**
    570  * returns title about recently published elements grouped by post date
    571  * @param $date_detail: selected date computed by get_recent_post_dates function
     575 * Returns title about recently published elements grouped by post date.
     576 *
     577 * @param array $date_detail returned value of get_recent_post_dates()
     578 * @return string
    572579 */
    573580function get_title_recent_post_date($date_detail)
    … …  
    584591}
    585592
    586 if(!function_exists("strptime"))
    587 {
    588                 function strptime($date, $fmt)
    589                 {
    590                         if ($fmt != '%Y-%m-%d %H:%M:%S')
    591                                 die('Invalid strptime format '.$fmt);
    592                         list($y,$m,$d,$H,$M,$S) = preg_split('/[-: ]/', $date);
    593                         $res = localtime( mktime($H,$M,$S,$m,$d,$y), true );
    594                         return $res;
    595                 }
    596  }
     593if (!function_exists('strptime'))
     594{
     595  function strptime($date, $fmt)
     596  {
     597    if ($fmt != '%Y-%m-%d %H:%M:%S')
     598      die('Invalid strptime format '.$fmt);
     599    list($y,$m,$d,$H,$M,$S) = preg_split('/[-: ]/', $date);
     600    $res = localtime( mktime($H,$M,$S,$m,$d,$y), true );
     601    return $res;
     602  }
     603}
     604
    597605?>
Note: See TracChangeset for help on using the changeset viewer.