aboutsummaryrefslogtreecommitdiffstats
path: root/include
diff options
context:
space:
mode:
authormistic100 <mistic@piwigo.org>2013-11-23 22:57:15 +0000
committermistic100 <mistic@piwigo.org>2013-11-23 22:57:15 +0000
commitda06285d4e7c8b689ef4d9a01710bc832e8f8e74 (patch)
tree3cd5cd0952e1ca2164d8a793ab050fcb94cd1cd0 /include
parent037413eee88b4049b073c44d300b51b8dbcd9abe (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.php2
-rw-r--r--include/functions_comment.inc.php4
-rw-r--r--include/functions_filter.inc.php2
-rw-r--r--include/functions_notification.inc.php2
-rw-r--r--include/functions_plugins.inc.php8
-rw-r--r--include/functions_search.inc.php111
-rw-r--r--include/functions_tag.inc.php121
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