Changeset 25658


Ignore:
Timestamp:
Nov 23, 2013, 11:57:15 PM (10 years ago)
Author:
mistic100
Message:

feature 2999: documentation of functions_search and functions_tag

Location:
trunk/include
Files:
7 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/functions_category.inc.php

    r25508 r25658  
    343343 *
    344344 * @param string[] $permalinks
    345  * @param int $idx filled with the index in $permalinks that matches
     345 * @param int &$idx filled with the index in $permalinks that matches
    346346 * @return int|null
    347347 */

  • trunk/include/functions_comment.inc.php

    r25548 r25658  
    7373 * Tries to insert a user comment and returns action to perform.
    7474 *
    75  * @param array $comm
     75 * @param array &$comm
    7676 * @param string $key secret key sent back to the browser
    77  * @param array $infos output array of error messages
     77 * @param array &$infos output array of error messages
    7878 * @return string validate, moderate, reject
    7979 */

  • trunk/include/functions_filter.inc.php

    r25548 r25658  
    3030 * Updates data of categories with filtered values
    3131 *
    32  * @param array $cats
     32 * @param array &$cats
    3333 */
    3434function update_cats_with_filtered_data(&$cats)

  • trunk/include/functions_notification.inc.php

    r25602 r25658  
    362362 * Formats a news line and adds it to the array (e.g. '5 new elements')
    363363 *
    364  * @param array $news
     364 * @param array &$news
    365365 * @param int $count
    366366 * @param string $singular_key

  • trunk/include/functions_plugins.inc.php

    r25602 r25658  
    5151  /**
    5252   * @param string $plugin_version
    53    * @param array $errors - used to return error messages
     53   * @param array &$errors - used to return error messages
    5454   */
    5555  abstract function install($plugin_version, &$errors=array());
    … …  
    5757  /**
    5858   * @param string $plugin_version
    59    * @param array $errors - used to return error messages
     59   * @param array &$errors - used to return error messages
    6060   */
    6161  abstract function activate($plugin_version, &$errors=array());
    … …  
    120120  /**
    121121   * @param string $theme_version
    122    * @param array $errors - used to return error messages
     122   * @param array &$errors - used to return error messages
    123123   */
    124124  abstract function activate($theme_version, &$errors=array());
    … …  
    343343 *
    344344 * @param string $plugin_id
    345  * @param mixed $data
     345 * @param mixed &$data
    346346 * @return bool
    347347 */

  • trunk/include/functions_search.inc.php

    r25026 r25658  
    2222// +-----------------------------------------------------------------------+
    2323
    24 
    25 /**
    26  * returns search rules stored into a serialized array in "search"
     24/**
     25 * @package functions\search
     26 */
     27
     28
     29/**
     30 * Returns search rules stored into a serialized array in "search"
    2731 * table. Each search rules set is numericaly identified.
    2832 *
    29  * @param int search_id
     33 * @param int $search_id
    3034 * @return array
    3135 */
    … …  
    4852
    4953/**
    50  * returns the SQL clause from a search identifier
    51  *
    52  * Search rules are stored in search table as a serialized array. This array
    53  * need to be transformed into an SQL clause to be used in queries.
    54  *
    55  * @param array search
     54 * Returns the SQL clause for a search.
     55 * Transforms the array returned by get_search_array() into SQL sub-query.
     56 *
     57 * @param array $search
    5658 * @return string
    5759 */
    … …  
    171173
    172174/**
    173  * returns the list of items corresponding to the advanced search array
    174  *
    175  * @param array search
     175 * Returns the list of items corresponding to the advanced search array.
     176 *
     177 * @param array $search
     178 * @param string $images_where optional additional restriction on images table
    176179 * @return array
    177180 */
    178 function get_regular_search_results($search, $images_where)
     181function get_regular_search_results($search, $images_where='')
    179182{
    180183  global $conf;
    … …  
    247250}
    248251
    249 
     252/**
     253 * Finds if a char is a letter, a figure or any char of the extended ASCII table (>127).
     254 *
     255 * @param char $ch
     256 * @return bool
     257 */
    250258function is_word_char($ch)
    251259{
    … …  
    253261}
    254262
     263/**
     264 * Finds if a char is a special token for word start: [{<=*+
     265 *
     266 * @param char $ch
     267 * @return bool
     268 */
    255269function is_odd_wbreak_begin($ch)
    256270{
    … …  
    258272}
    259273
     274/**
     275 * Finds if a char is a special token for word end: ]}>=*+
     276 *
     277 * @param char $ch
     278 * @return bool
     279 */
    260280function is_odd_wbreak_end($ch)
    261281{
    … …  
    263283}
    264284
    265 define('QST_QUOTED',   0x01);
    266 define('QST_NOT',      0x02);
    267 define('QST_WILDCARD_BEGIN',0x04);
    268 define('QST_WILDCARD_END',  0x08);
     285
     286define('QST_QUOTED',         0x01);
     287define('QST_NOT',            0x02);
     288define('QST_WILDCARD_BEGIN', 0x04);
     289define('QST_WILDCARD_END',   0x08);
    269290define('QST_WILDCARD', QST_WILDCARD_BEGIN|QST_WILDCARD_END);
    270291
    271 
    272 /**
    273  * analyzes and splits the quick/query search query $q into tokens
     292/**
     293 * Analyzes and splits the quick/query search query $q into tokens.
    274294 * q='john bill' => 2 tokens 'john' 'bill'
    275295 * Special characters for MySql full text search (+,<,>,~) appear in the token modifiers.
    276296 * The query can contain a phrase: 'Pierre "New York"' will return 'pierre' qnd 'new york'.
     297 *
     298 * @param string $q
     299 * @param array &$qtokens
     300 * @param array &$qtoken_modifiers
    277301 */
    278302function analyse_qsearch($q, &$qtokens, &$qtoken_modifiers)
    … …  
    369393}
    370394
    371 
    372 /**
    373  * returns the LIKE sql clause corresponding to the quick search query
    374  * that has been split into tokens
     395/**
     396 * Returns the LIKE SQL clause corresponding to the quick search query
     397 * that has been split into tokens.
    375398 * for example file LIKE '%john%' OR file LIKE '%bill%'.
     399 *
     400 * @param array $tokens
     401 * @param array $token_modifiers
     402 * @param string $field
     403 * @return string|null
    376404 */
    377405function get_qsearch_like_clause($tokens, $token_modifiers, $field)
    … …  
    394422
    395423/**
    396 */
     424 * Returns tags corresponding to the quick search query that has been split into tokens.
     425 *
     426 * @param array $tokens
     427 * @param array $token_modifiers
     428 * @param array &$token_tag_ids
     429 * @param array &$not_tag_ids
     430 * @param array &$all_tags
     431 */
    397432function get_qsearch_tags($tokens, $token_modifiers, &$token_tag_ids, &$not_tag_ids, &$all_tags)
    398433{
    … …  
    547582  usort($all_tags, 'tag_alpha_compare');
    548583  foreach ( $all_tags as &$tag )
     584  {
    549585    $tag['name'] = trigger_event('render_tag_name', $tag['name']);
    550 }
    551 
    552 /**
    553  * returns the search results corresponding to a quick/query search.
     586  }
     587}
     588
     589/**
     590 * Returns the search results corresponding to a quick/query search.
    554591 * A quick/query search returns many items (search is not strict), but results
    555592 * are sorted by relevance unless $super_order_by is true. Returns:
    556  * array (
    557  * 'items' => array(85,68,79...)
    558  * 'qs'    => array(
    559  *    'matching_tags' => array of matching tags
    560  *    'matching_cats' => array of matching categories
    561  *    'matching_cats_no_images' =>array(99) - matching categories without images
    562  *      ))
    563  *
    564  * @param string q
    565  * @param bool super_order_by
    566  * @param string images_where optional aditional restriction on images table
     593 *  array (
     594 *    'items' => array of matching images
     595 *    'qs'    => array(
     596 *      'matching_tags' => array of matching tags
     597 *      'matching_cats' => array of matching categories
     598 *      'matching_cats_no_images' =>array(99) - matching categories without images
     599 *      )
     600 *    )
     601 *
     602 * @param string $q
     603 * @param bool $super_order_by
     604 * @param string $images_where optional additional restriction on images table
    567605 * @return array
    568606 */
    … …  
    764802
    765803/**
    766  * returns an array of 'items' corresponding to the search id
    767  *
    768  * @param int search id
    769  * @param string images_where optional aditional restriction on images table
     804 * Returns an array of 'items' corresponding to the search id.
     805 * It can be either a quick search or a regular search.
     806 *
     807 * @param int $search_id
     808 * @param bool $super_order_by
     809 * @param string $images_where optional aditional restriction on images table
    770810 * @return array
    771811 */
    … …  
    783823  }
    784824}
     825
    785826?>

  • trunk/include/functions_tag.inc.php

    r25018 r25658  
    2222// +-----------------------------------------------------------------------+
    2323
    24 
    25 /** returns the number of available tags for the connected user */
     24/**
     25 * @package functions\tag
     26 */
     27
     28
     29/**
     30 * Returns the number of available tags for the connected user.
     31 *
     32 * @return int
     33 */
    2634function get_nb_available_tags()
    2735{
    … …  
    3947
    4048/**
    41  * Tags available. Each return tag is represented as an array with its id,
    42  * its name, its weight (count), its url name. Tags are not sorted.
    43  *
    44  * The returned list can be a subset of all existing tags due to
    45  * permissions, only if a list of forbidden categories is provided
    46  *
    47  * @param array forbidden categories
    48  * @return array
     49 * Returns all available tags for the connected user (not sorted).
     50 * The returned list can be a subset of all existing tags due to permissions,
     51 * also tags with no images are not returned.
     52 *
     53 * @return array [id, name, counter, url_name]
    4954 */
    5055function get_available_tags()
    … …  
    5459SELECT tag_id, COUNT(DISTINCT(it.image_id)) AS counter
    5560  FROM '.IMAGE_CATEGORY_TABLE.' ic
    56     INNER JOIN '.IMAGE_TAG_TABLE.' it ON ic.image_id=it.image_id'.get_sql_condition_FandF
    57     (
    58       array
    59         (
    60           'forbidden_categories' => 'category_id',
    61           'visible_categories' => 'category_id',
    62           'visible_images' => 'ic.image_id'
    63         ),
    64       '
    65   WHERE'
     61    INNER JOIN '.IMAGE_TAG_TABLE.' it
     62    ON ic.image_id=it.image_id
     63  '.get_sql_condition_FandF(
     64    array(
     65      'forbidden_categories' => 'category_id',
     66      'visible_categories' => 'category_id',
     67      'visible_images' => 'ic.image_id'
     68      ),
     69    ' WHERE '
    6670    ).'
    67   GROUP BY tag_id';
     71  GROUP BY tag_id
     72;';
    6873  $tag_counters = simple_hash_from_query($query, 'tag_id', 'counter');
    6974
    … …  
    7782  FROM '.TAGS_TABLE;
    7883  $result = pwg_query($query);
     84
    7985  $tags = array();
    8086  while ($row = pwg_db_fetch_assoc($result))
    … …  
    9298
    9399/**
    94  * All tags, even tags associated to no image.
    95  *
    96  * @return array
     100 * Returns all tags even associated to no image.
     101 *
     102 * @return array [id, name, url_name]
    97103 */
    98104function get_all_tags()
    … …  
    120126 *
    121127 * The level of each tag depends on the average count of tags. This
    122  * calcylation method avoid having very different levels for tags having
     128 * calculation method avoid having very different levels for tags having
    123129 * nearly the same count when set are small.
    124130 *
    125  * @param array tags
    126  * @return array
     131 * @param array $tags at least [id, counter]
     132 * @return array [..., level]
    127133 */
    128134function add_level_to_tags($tags)
    … …  
    174180
    175181/**
    176  * return the list of image ids corresponding to given tags. AND & OR mode
    177  * supported.
    178  *
    179  * @param array tag ids
     182 * Return the list of image ids corresponding to given tags.
     183 * AND & OR mode supported.
     184 *
     185 * @param int[] $tag_ids
    180186 * @param string mode
    181  * @param string extra_images_where_sql - optionally apply a sql where filter to retrieved images
    182  * @param string order_by - optionally overwrite default photo order
     187 * @param string $extra_images_where_sql - optionally apply a sql where filter to retrieved images
     188 * @param string $order_by - optionally overwrite default photo order
     189 * @param bool $user_permissions
    183190 * @return array
    184191 */
    … …  
    191198  }
    192199
    193   $query = 'SELECT id
     200  $query = '
     201SELECT id
    194202  FROM '.IMAGES_TABLE.' i ';
    195203
    … …  
    230238
    231239/**
    232  * return a list of tags corresponding to given items.
    233  *
    234  * @param array items
    235  * @param array max_tags
    236  * @param array excluded_tag_ids
    237  * @return array
    238  */
    239 function get_common_tags($items, $max_tags, $excluded_tag_ids=null)
     240 * Return a list of tags corresponding to given items.
     241 *
     242 * @param int[] $items
     243 * @param int $max_tags
     244 * @param int[] $excluded_tag_ids
     245 * @return array [id, name, counter, url_name]
     246 */
     247function get_common_tags($items, $max_tags, $excluded_tag_ids=array())
    240248{
    241249  if (empty($items))
    … …  
    257265  ORDER BY ';
    258266  if ($max_tags>0)
    259   {
     267  { // TODO : why ORDER field is in the if ?
    260268    $query .= 'counter DESC
    261269  LIMIT '.$max_tags;
    … …  
    278286
    279287/**
    280  * return a list of tags corresponding to any of ids, url_names, names
    281  *
    282  * @param array ids
    283  * @param array url_names
    284  * @param array names
    285  * @return array
    286  */
    287 function find_tags($ids, $url_names=array(), $names=array() )
     288 * Return a list of tags corresponding to any of ids, url_names or names.
     289 *
     290 * @param int[] $ids
     291 * @param string[] $url_names
     292 * @param string[] $names
     293 * @return array [id, name, url_name]
     294 */
     295function find_tags($ids=array(), $url_names=array(), $names=array() )
    288296{
    289297  $where_clauses = array();
    290   if ( !empty($ids) )
     298  if (!empty($ids))
    291299  {
    292300    $where_clauses[] = 'id IN ('.implode(',', $ids).')';
    293301  }
    294   if ( !empty($url_names) )
     302  if (!empty($url_names))
    295303  {
    296304    $where_clauses[] =
    297       'url_name IN ('.
    298       implode(
    299         ',',
    300         array_map(
    301           create_function('$s', 'return "\'".$s."\'";'),
    302           $url_names
    303           )
    304         )
    305       .')';
    306   }
    307   if ( !empty($names) )
     305      'url_name IN (\''. implode('\', \'', $url_names) .'\')';
     306  }
     307  if (!empty($names))
    308308  {
    309309    $where_clauses[] =
    310       'name IN ('.
    311       implode(
    312         ',',
    313         array_map(
    314           create_function('$s', 'return "\'".$s."\'";'),
    315           $names
    316           )
    317         )
    318       .')';
     310      'name IN (\''. implode('\', \'', $names) .'\')';
    319311  }
    320312  if (empty($where_clauses))
    … …  
    337329  return $tags;
    338330}
     331
    339332?>
Note: See TracChangeset for help on using the changeset viewer.