diff options
author | mistic100 <mistic@piwigo.org> | 2013-11-23 22:57:15 +0000 |
---|---|---|
committer | mistic100 <mistic@piwigo.org> | 2013-11-23 22:57:15 +0000 |
commit | da06285d4e7c8b689ef4d9a01710bc832e8f8e74 (patch) | |
tree | 3cd5cd0952e1ca2164d8a793ab050fcb94cd1cd0 | |
parent | 037413eee88b4049b073c44d300b51b8dbcd9abe (diff) |
feature 2999: documentation of functions_search and functions_tag
git-svn-id: http://piwigo.org/svn/trunk@25658 68402e56-0260-453c-a942-63ccdbb3a9ee
Diffstat (limited to '')
-rw-r--r-- | include/functions_category.inc.php | 2 | ||||
-rw-r--r-- | include/functions_comment.inc.php | 4 | ||||
-rw-r--r-- | include/functions_filter.inc.php | 2 | ||||
-rw-r--r-- | include/functions_notification.inc.php | 2 | ||||
-rw-r--r-- | include/functions_plugins.inc.php | 8 | ||||
-rw-r--r-- | include/functions_search.inc.php | 111 | ||||
-rw-r--r-- | include/functions_tag.inc.php | 121 |
7 files changed, 142 insertions, 108 deletions
diff --git a/include/functions_category.inc.php b/include/functions_category.inc.php index 798efe35d..d22cbba93 100644 --- a/include/functions_category.inc.php +++ b/include/functions_category.inc.php @@ -342,7 +342,7 @@ SELECT DISTINCT(id) * Finds a matching category id from a potential list of permalinks * * @param string[] $permalinks - * @param int $idx filled with the index in $permalinks that matches + * @param int &$idx filled with the index in $permalinks that matches * @return int|null */ function get_cat_id_from_permalinks($permalinks, &$idx) diff --git a/include/functions_comment.inc.php b/include/functions_comment.inc.php index f48f711c7..8a6ee1d4a 100644 --- a/include/functions_comment.inc.php +++ b/include/functions_comment.inc.php @@ -72,9 +72,9 @@ function user_comment_check($action, $comment) /** * Tries to insert a user comment and returns action to perform. * - * @param array $comm + * @param array &$comm * @param string $key secret key sent back to the browser - * @param array $infos output array of error messages + * @param array &$infos output array of error messages * @return string validate, moderate, reject */ function insert_user_comment(&$comm, $key, &$infos) diff --git a/include/functions_filter.inc.php b/include/functions_filter.inc.php index 13691aed6..a7cad8902 100644 --- a/include/functions_filter.inc.php +++ b/include/functions_filter.inc.php @@ -29,7 +29,7 @@ /** * Updates data of categories with filtered values * - * @param array $cats + * @param array &$cats */ function update_cats_with_filtered_data(&$cats) { diff --git a/include/functions_notification.inc.php b/include/functions_notification.inc.php index e3a2880cb..1834250a9 100644 --- a/include/functions_notification.inc.php +++ b/include/functions_notification.inc.php @@ -361,7 +361,7 @@ function news_exists($start=null, $end=null) /** * Formats a news line and adds it to the array (e.g. '5 new elements') * - * @param array $news + * @param array &$news * @param int $count * @param string $singular_key * @param string $plural_key diff --git a/include/functions_plugins.inc.php b/include/functions_plugins.inc.php index 1f985a2ef..03ecc6541 100644 --- a/include/functions_plugins.inc.php +++ b/include/functions_plugins.inc.php @@ -50,13 +50,13 @@ abstract class PluginMaintain /** * @param string $plugin_version - * @param array $errors - used to return error messages + * @param array &$errors - used to return error messages */ abstract function install($plugin_version, &$errors=array()); /** * @param string $plugin_version - * @param array $errors - used to return error messages + * @param array &$errors - used to return error messages */ abstract function activate($plugin_version, &$errors=array()); @@ -119,7 +119,7 @@ abstract class ThemeMaintain /** * @param string $theme_version - * @param array $errors - used to return error messages + * @param array &$errors - used to return error messages */ abstract function activate($theme_version, &$errors=array()); @@ -342,7 +342,7 @@ function trigger_action($event) * @depracted 2.6 * * @param string $plugin_id - * @param mixed $data + * @param mixed &$data * @return bool */ function set_plugin_data($plugin_id, &$data) diff --git a/include/functions_search.inc.php b/include/functions_search.inc.php index 0a2be7a31..7140ec6aa 100644 --- a/include/functions_search.inc.php +++ b/include/functions_search.inc.php @@ -21,12 +21,16 @@ // | USA. | // +-----------------------------------------------------------------------+ +/** + * @package functions\search + */ + /** - * returns search rules stored into a serialized array in "search" + * Returns search rules stored into a serialized array in "search" * table. Each search rules set is numericaly identified. * - * @param int search_id + * @param int $search_id * @return array */ function get_search_array($search_id) @@ -47,12 +51,10 @@ SELECT rules } /** - * returns the SQL clause from a search identifier + * Returns the SQL clause for a search. + * Transforms the array returned by get_search_array() into SQL sub-query. * - * Search rules are stored in search table as a serialized array. This array - * need to be transformed into an SQL clause to be used in queries. - * - * @param array search + * @param array $search * @return string */ function get_sql_search_clause($search) @@ -170,12 +172,13 @@ function get_sql_search_clause($search) } /** - * returns the list of items corresponding to the advanced search array + * Returns the list of items corresponding to the advanced search array. * - * @param array search + * @param array $search + * @param string $images_where optional additional restriction on images table * @return array */ -function get_regular_search_results($search, $images_where) +function get_regular_search_results($search, $images_where='') { global $conf; $forbidden = get_sql_condition_FandF( @@ -246,34 +249,55 @@ SELECT DISTINCT(id) return $items; } - +/** + * Finds if a char is a letter, a figure or any char of the extended ASCII table (>127). + * + * @param char $ch + * @return bool + */ function is_word_char($ch) { return ($ch>='0' && $ch<='9') || ($ch>='a' && $ch<='z') || ($ch>='A' && $ch<='Z') || ord($ch)>127; } +/** + * Finds if a char is a special token for word start: [{<=*+ + * + * @param char $ch + * @return bool + */ function is_odd_wbreak_begin($ch) { return strpos('[{<=*+', $ch)===false ? false:true; } +/** + * Finds if a char is a special token for word end: ]}>=*+ + * + * @param char $ch + * @return bool + */ function is_odd_wbreak_end($ch) { return strpos(']}>=*+', $ch)===false ? false:true; } -define('QST_QUOTED', 0x01); -define('QST_NOT', 0x02); -define('QST_WILDCARD_BEGIN',0x04); -define('QST_WILDCARD_END', 0x08); -define('QST_WILDCARD', QST_WILDCARD_BEGIN|QST_WILDCARD_END); +define('QST_QUOTED', 0x01); +define('QST_NOT', 0x02); +define('QST_WILDCARD_BEGIN', 0x04); +define('QST_WILDCARD_END', 0x08); +define('QST_WILDCARD', QST_WILDCARD_BEGIN|QST_WILDCARD_END); /** - * analyzes and splits the quick/query search query $q into tokens + * Analyzes and splits the quick/query search query $q into tokens. * q='john bill' => 2 tokens 'john' 'bill' * Special characters for MySql full text search (+,<,>,~) appear in the token modifiers. * The query can contain a phrase: 'Pierre "New York"' will return 'pierre' qnd 'new york'. + * + * @param string $q + * @param array &$qtokens + * @param array &$qtoken_modifiers */ function analyse_qsearch($q, &$qtokens, &$qtoken_modifiers) { @@ -368,11 +392,15 @@ function analyse_qsearch($q, &$qtokens, &$qtoken_modifiers) } } - /** - * returns the LIKE sql clause corresponding to the quick search query - * that has been split into tokens + * Returns the LIKE SQL clause corresponding to the quick search query + * that has been split into tokens. * for example file LIKE '%john%' OR file LIKE '%bill%'. + * + * @param array $tokens + * @param array $token_modifiers + * @param string $field + * @return string|null */ function get_qsearch_like_clause($tokens, $token_modifiers, $field) { @@ -393,7 +421,14 @@ function get_qsearch_like_clause($tokens, $token_modifiers, $field) } /** -*/ + * Returns tags corresponding to the quick search query that has been split into tokens. + * + * @param array $tokens + * @param array $token_modifiers + * @param array &$token_tag_ids + * @param array &$not_tag_ids + * @param array &$all_tags + */ function get_qsearch_tags($tokens, $token_modifiers, &$token_tag_ids, &$not_tag_ids, &$all_tags) { $token_tag_ids = array_fill(0, count($tokens), array() ); @@ -546,24 +581,27 @@ SELECT t.*, COUNT(image_id) AS counter usort($all_tags, 'tag_alpha_compare'); foreach ( $all_tags as &$tag ) + { $tag['name'] = trigger_event('render_tag_name', $tag['name']); + } } /** - * returns the search results corresponding to a quick/query search. + * Returns the search results corresponding to a quick/query search. * A quick/query search returns many items (search is not strict), but results * are sorted by relevance unless $super_order_by is true. Returns: - * array ( - * 'items' => array(85,68,79...) - * 'qs' => array( - * 'matching_tags' => array of matching tags - * 'matching_cats' => array of matching categories - * 'matching_cats_no_images' =>array(99) - matching categories without images - * )) + * array ( + * 'items' => array of matching images + * 'qs' => array( + * 'matching_tags' => array of matching tags + * 'matching_cats' => array of matching categories + * 'matching_cats_no_images' =>array(99) - matching categories without images + * ) + * ) * - * @param string q - * @param bool super_order_by - * @param string images_where optional aditional restriction on images table + * @param string $q + * @param bool $super_order_by + * @param string $images_where optional additional restriction on images table * @return array */ function get_quick_search_results($q, $super_order_by, $images_where='') @@ -763,10 +801,12 @@ SELECT DISTINCT(id) } /** - * returns an array of 'items' corresponding to the search id + * Returns an array of 'items' corresponding to the search id. + * It can be either a quick search or a regular search. * - * @param int search id - * @param string images_where optional aditional restriction on images table + * @param int $search_id + * @param bool $super_order_by + * @param string $images_where optional aditional restriction on images table * @return array */ function get_search_results($search_id, $super_order_by, $images_where='') @@ -782,4 +822,5 @@ function get_search_results($search_id, $super_order_by, $images_where='') return get_quick_search_results($search['q'], $super_order_by, $images_where); } } + ?>
\ No newline at end of file diff --git a/include/functions_tag.inc.php b/include/functions_tag.inc.php index 52f01ab88..dd732fca2 100644 --- a/include/functions_tag.inc.php +++ b/include/functions_tag.inc.php @@ -21,8 +21,16 @@ // | USA. | // +-----------------------------------------------------------------------+ +/** + * @package functions\tag + */ + -/** returns the number of available tags for the connected user */ +/** + * Returns the number of available tags for the connected user. + * + * @return int + */ function get_nb_available_tags() { global $user; @@ -38,14 +46,11 @@ function get_nb_available_tags() } /** - * Tags available. Each return tag is represented as an array with its id, - * its name, its weight (count), its url name. Tags are not sorted. - * - * The returned list can be a subset of all existing tags due to - * permissions, only if a list of forbidden categories is provided + * Returns all available tags for the connected user (not sorted). + * The returned list can be a subset of all existing tags due to permissions, + * also tags with no images are not returned. * - * @param array forbidden categories - * @return array + * @return array [id, name, counter, url_name] */ function get_available_tags() { @@ -53,18 +58,18 @@ function get_available_tags() $query = ' SELECT tag_id, COUNT(DISTINCT(it.image_id)) AS counter FROM '.IMAGE_CATEGORY_TABLE.' ic - INNER JOIN '.IMAGE_TAG_TABLE.' it ON ic.image_id=it.image_id'.get_sql_condition_FandF - ( - array - ( - 'forbidden_categories' => 'category_id', - 'visible_categories' => 'category_id', - 'visible_images' => 'ic.image_id' - ), - ' - WHERE' + INNER JOIN '.IMAGE_TAG_TABLE.' it + ON ic.image_id=it.image_id + '.get_sql_condition_FandF( + array( + 'forbidden_categories' => 'category_id', + 'visible_categories' => 'category_id', + 'visible_images' => 'ic.image_id' + ), + ' WHERE ' ).' - GROUP BY tag_id'; + GROUP BY tag_id +;'; $tag_counters = simple_hash_from_query($query, 'tag_id', 'counter'); if ( empty($tag_counters) ) @@ -76,6 +81,7 @@ SELECT tag_id, COUNT(DISTINCT(it.image_id)) AS counter SELECT * FROM '.TAGS_TABLE; $result = pwg_query($query); + $tags = array(); while ($row = pwg_db_fetch_assoc($result)) { @@ -91,9 +97,9 @@ SELECT * } /** - * All tags, even tags associated to no image. + * Returns all tags even associated to no image. * - * @return array + * @return array [id, name, url_name] */ function get_all_tags() { @@ -119,11 +125,11 @@ SELECT * * level of each tag. * * The level of each tag depends on the average count of tags. This - * calcylation method avoid having very different levels for tags having + * calculation method avoid having very different levels for tags having * nearly the same count when set are small. * - * @param array tags - * @return array + * @param array $tags at least [id, counter] + * @return array [..., level] */ function add_level_to_tags($tags) { @@ -173,13 +179,14 @@ function add_level_to_tags($tags) } /** - * return the list of image ids corresponding to given tags. AND & OR mode - * supported. + * Return the list of image ids corresponding to given tags. + * AND & OR mode supported. * - * @param array tag ids + * @param int[] $tag_ids * @param string mode - * @param string extra_images_where_sql - optionally apply a sql where filter to retrieved images - * @param string order_by - optionally overwrite default photo order + * @param string $extra_images_where_sql - optionally apply a sql where filter to retrieved images + * @param string $order_by - optionally overwrite default photo order + * @param bool $user_permissions * @return array */ function get_image_ids_for_tags($tag_ids, $mode='AND', $extra_images_where_sql='', $order_by='', $use_permissions=true) @@ -190,7 +197,8 @@ function get_image_ids_for_tags($tag_ids, $mode='AND', $extra_images_where_sql=' return array(); } - $query = 'SELECT id + $query = ' +SELECT id FROM '.IMAGES_TABLE.' i '; if ($use_permissions) @@ -229,14 +237,14 @@ function get_image_ids_for_tags($tag_ids, $mode='AND', $extra_images_where_sql=' } /** - * return a list of tags corresponding to given items. + * Return a list of tags corresponding to given items. * - * @param array items - * @param array max_tags - * @param array excluded_tag_ids - * @return array + * @param int[] $items + * @param int $max_tags + * @param int[] $excluded_tag_ids + * @return array [id, name, counter, url_name] */ -function get_common_tags($items, $max_tags, $excluded_tag_ids=null) +function get_common_tags($items, $max_tags, $excluded_tag_ids=array()) { if (empty($items)) { @@ -256,7 +264,7 @@ SELECT t.*, count(*) AS counter GROUP BY t.id ORDER BY '; if ($max_tags>0) - { + { // TODO : why ORDER field is in the if ? $query .= 'counter DESC LIMIT '.$max_tags; } @@ -277,45 +285,29 @@ SELECT t.*, count(*) AS counter } /** - * return a list of tags corresponding to any of ids, url_names, names + * Return a list of tags corresponding to any of ids, url_names or names. * - * @param array ids - * @param array url_names - * @param array names - * @return array + * @param int[] $ids + * @param string[] $url_names + * @param string[] $names + * @return array [id, name, url_name] */ -function find_tags($ids, $url_names=array(), $names=array() ) +function find_tags($ids=array(), $url_names=array(), $names=array() ) { $where_clauses = array(); - if ( !empty($ids) ) + if (!empty($ids)) { $where_clauses[] = 'id IN ('.implode(',', $ids).')'; } - if ( !empty($url_names) ) + if (!empty($url_names)) { $where_clauses[] = - 'url_name IN ('. - implode( - ',', - array_map( - create_function('$s', 'return "\'".$s."\'";'), - $url_names - ) - ) - .')'; + 'url_name IN (\''. implode('\', \'', $url_names) .'\')'; } - if ( !empty($names) ) + if (!empty($names)) { $where_clauses[] = - 'name IN ('. - implode( - ',', - array_map( - create_function('$s', 'return "\'".$s."\'";'), - $names - ) - ) - .')'; + 'name IN (\''. implode('\', \'', $names) .'\')'; } if (empty($where_clauses)) { @@ -336,4 +328,5 @@ SELECT * } return $tags; } + ?>
\ No newline at end of file |