Changeset 25658


Ignore:
Timestamp:
11/23/13 23:57:15 (6 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.