aboutsummaryrefslogtreecommitdiffstats
path: root/admin/include
diff options
context:
space:
mode:
authormistic100 <mistic@piwigo.org>2014-01-16 15:24:36 +0000
committermistic100 <mistic@piwigo.org>2014-01-16 15:24:36 +0000
commit28f4a33bcb2d97f777ae439f0ddeaa9da581deb7 (patch)
tree805740a35a37c5dd7a5a62d485709008bb5bf355 /admin/include
parentec771fb24637e86e2dbed0cdaff800aa1c2c8b7d (diff)
feature 2999: documentation of admin/include/functions.php
git-svn-id: http://piwigo.org/svn/trunk@26807 68402e56-0260-453c-a942-63ccdbb3a9ee
Diffstat (limited to 'admin/include')
-rw-r--r--admin/include/functions.php447
1 files changed, 260 insertions, 187 deletions
diff --git a/admin/include/functions.php b/admin/include/functions.php
index ba6cdf40d..71c164822 100644
--- a/admin/include/functions.php
+++ b/admin/include/functions.php
@@ -21,11 +21,19 @@
// | USA. |
// +-----------------------------------------------------------------------+
-include(PHPWG_ROOT_PATH.'admin/include/functions_metadata.php');
+/**
+ * @package functions\admin\___
+ */
+
+include_once(PHPWG_ROOT_PATH.'admin/include/functions_metadata.php');
+
-// The function delete_site deletes a site and call the function
-// delete_categories for each primary category of the site
-function delete_site( $id )
+/**
+ * Deletes a site and call delete_categories for each primary category of the site
+ *
+ * @param int $id
+ */
+function delete_site($id)
{
// destruction of the categories of the site
$query = '
@@ -44,18 +52,19 @@ DELETE FROM '.SITES_TABLE.'
pwg_query($query);
}
-
-// The function delete_categories deletes the categories identified by the
-// (numeric) key of the array $ids. It also deletes (in the database) :
-// - all the elements physically linked to the category (delete_elements, see further)
-// - all the links between elements and this category
-// - all the restrictions linked to the category
-// The function works recursively.
-//
-// the $photo_deletion_mode is for photos virtually linked to the categorty
-// * no_delete : delete no photo, may create orphans
-// * delete_orphans : delete photos that are no longer linked to any category
-// * force_delete : delete photos even if they are linked to another category
+/**
+ * Recursively deletes one or more categories.
+ * It also deletes :
+ * - all the elements physically linked to the category (with delete_elements)
+ * - all the links between elements and this category
+ * - all the restrictions linked to the category
+ *
+ * @param int[] $ids
+ * @param string $photo_deletion_mode
+ * - no_delete : delete no photo, may create orphans
+ * - delete_orphans : delete photos that are no longer linked to any category
+ * - force_delete : delete photos even if they are linked to another category
+ */
function delete_categories($ids, $photo_deletion_mode='no_delete')
{
if (count($ids) == 0)
@@ -156,8 +165,12 @@ DELETE FROM '.USER_CACHE_CATEGORIES_TABLE.'
trigger_action('delete_categories', $ids);
}
-// Deletes all files (on disk) related to given image ids
-// @return image ids where files are deleted successfully
+/**
+ * Deletes all files (on disk) related to given image ids.
+ *
+ * @param int[] $ids
+ * @return 0|int[] image ids where files were successfully deleted
+ */
function delete_element_files($ids)
{
global $conf;
@@ -219,12 +232,18 @@ SELECT
return $new_ids;
}
-// The function delete_elements deletes the elements identified by the
-// (numeric) values of the array $ids. It also deletes (in the database) :
-// - all the comments related to elements
-// - all the links between categories and elements
-// - all the favorites associated to elements
-// @return number of deleted elements
+/**
+ * Deletes elements from database.
+ * It also deletes :
+ * - all the comments related to elements
+ * - all the links between categories/tags and elements
+ * - all the favorites/rates associated to elements
+ * - removes elements from caddie
+ *
+ * @param int[] $ids
+ * @param bool $physical_deletion
+ * @return int number of deleted elements
+ */
function delete_elements($ids, $physical_deletion=false)
{
if (count($ids) == 0)
@@ -241,60 +260,55 @@ function delete_elements($ids, $physical_deletion=false)
return 0;
}
}
+
+ $ids_str = wordwrap(implode(', ', $ids), 80, "\n");
// destruction of the comments on the image
$query = '
DELETE FROM '.COMMENTS_TABLE.'
- WHERE image_id IN (
-'.wordwrap(implode(', ', $ids), 80, "\n").')
+ WHERE image_id IN ('. $ids_str .')
;';
pwg_query($query);
- // destruction of the links between images and this category
+ // destruction of the links between images and categories
$query = '
DELETE FROM '.IMAGE_CATEGORY_TABLE.'
- WHERE image_id IN (
-'.wordwrap(implode(', ', $ids), 80, "\n").')
+ WHERE image_id IN ('. $ids_str .')
;';
pwg_query($query);
// destruction of the links between images and tags
$query = '
DELETE FROM '.IMAGE_TAG_TABLE.'
- WHERE image_id IN (
-'.wordwrap(implode(', ', $ids), 80, "\n").')
+ WHERE image_id IN ('. $ids_str .')
;';
pwg_query($query);
// destruction of the favorites associated with the picture
$query = '
DELETE FROM '.FAVORITES_TABLE.'
- WHERE image_id IN (
-'.wordwrap(implode(', ', $ids), 80, "\n").')
+ WHERE image_id IN ('. $ids_str .')
;';
pwg_query($query);
// destruction of the rates associated to this element
$query = '
DELETE FROM '.RATE_TABLE.'
- WHERE element_id IN (
-'.wordwrap(implode(', ', $ids), 80, "\n").')
+ WHERE element_id IN ('. $ids_str .')
;';
pwg_query($query);
- // destruction of the rates associated to this element
+ // destruction of the caddie associated to this element
$query = '
DELETE FROM '.CADDIE_TABLE.'
- WHERE element_id IN (
-'.wordwrap(implode(', ', $ids), 80, "\n").')
+ WHERE element_id IN ('. $ids_str .')
;';
pwg_query($query);
// destruction of the image
$query = '
DELETE FROM '.IMAGES_TABLE.'
- WHERE id IN (
-'.wordwrap(implode(', ', $ids), 80, "\n").')
+ WHERE id IN ('. $ids_str .')
;';
pwg_query($query);
@@ -303,8 +317,7 @@ DELETE FROM '.IMAGES_TABLE.'
SELECT
id
FROM '.CATEGORIES_TABLE.'
- WHERE representative_picture_id IN (
-'.wordwrap(implode(', ', $ids), 80, "\n").')
+ WHERE representative_picture_id IN ('. $ids_str .')
;';
$category_ids = array_from_query($query, 'id');
if (count($category_ids) > 0)
@@ -316,13 +329,13 @@ SELECT
return count($ids);
}
-// The delete_user function delete a user identified by the $user_id
-// It also deletes :
-// - all the access linked to this user
-// - all the links to any group
-// - all the favorites linked to this user
-// - calculated permissions linked to the user
-// - all datas about notifications for the user
+/**
+ * Deletes an user.
+ * It also deletes all related data (accesses, favorites, permissions, etc.)
+ * @todo : accept array input
+ *
+ * @param int $user_id
+ */
function delete_user($user_id)
{
global $conf;
@@ -356,7 +369,7 @@ DELETE FROM '.$table.'
pwg_query($query);
}
- // destruction of the user
+ // purge of sessions
$query = '
DELETE FROM '.SESSIONS_TABLE.'
WHERE data LIKE \'pwg_uid|i:'.(int)$user_id.';%\'
@@ -415,10 +428,9 @@ SELECT
/**
* Verifies that the representative picture really exists in the db and
- * picks up a random represantive if possible and based on config.
+ * picks up a random representative if possible and based on config.
*
- * @param mixed category id
- * @returns void
+ * @param 'all'|int|int[] $ids
*/
function update_category($ids = 'all')
{
@@ -485,9 +497,8 @@ SELECT DISTINCT id
}
/**
- * check and repair images integrity
- *
- * TODO see delete_elements function to check all linked tables
+ * Checks and repairs IMAGE_CATEGORY_TABLE integrity.
+ * Removes all entries from the table which correspond to a deleted image.
*/
function images_integrity()
{
@@ -513,18 +524,18 @@ DELETE
}
/**
- * returns an array containing sub-directories which can be a category,
- * recursive by default
- *
- * directories nammed "thumbnail", "pwg_high" or "pwg_representative" are
- * omitted
+ * Returns an array containing sub-directories which are potentially
+ * a category.
+ * Directories named ".svn", "thumbnail", "pwg_high" or "pwg_representative"
+ * are omitted.
*
- * @param string $basedir
- * @return array
+ * @param string $basedir (eg: ./galleries)
+ * @return string[]
*/
function get_fs_directories($path, $recursive = true)
{
$dirs = array();
+ $path = rtrim($path, '/');
if (is_dir($path))
{
@@ -555,9 +566,8 @@ function get_fs_directories($path, $recursive = true)
}
/**
- * order categories (update categories.rank and global_rank database fields)
- * so that rank field are consecutive integers starting at 1 for each child
- * @return void
+ * Orders categories (update categories.rank and global_rank database fields)
+ * so that rank field are consecutive integers starting at 1 for each child.
*/
function update_global_rank()
{
@@ -623,22 +633,21 @@ SELECT id, id_uppercat, uppercats, rank, global_rank
}
/**
- * change the visible property on a set of categories
+ * Change the **visible** property on a set of categories.
*
- * @param array categories
- * @param string value
- * @return void
+ * @param int[] $categories
+ * @param boolean|string $value
*/
function set_cat_visible($categories, $value)
{
- if (!in_array($value, array('true', 'false')))
+ if ( ($value = filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE)) === null )
{
trigger_error("set_cat_visible invalid param $value", E_USER_WARNING);
return false;
}
// unlocking a category => all its parent categories become unlocked
- if ($value == 'true')
+ if ($value)
{
$uppercats = get_uppercat_ids($categories);
$query = '
@@ -648,7 +657,7 @@ UPDATE '.CATEGORIES_TABLE.'
pwg_query($query);
}
// locking a category => all its child categories become locked
- if ($value == 'false')
+ else
{
$subcats = get_subcat_ids($categories);
$query = '
@@ -660,11 +669,10 @@ UPDATE '.CATEGORIES_TABLE.'
}
/**
- * change the status property on a set of categories : private or public
+ * Change the **status** property on a set of categories : private or public.
*
- * @param array categories
- * @param string value
- * @return void
+ * @param int[] $categories
+ * @param string $value
*/
function set_cat_status($categories, $value)
{
@@ -698,10 +706,10 @@ UPDATE '.CATEGORIES_TABLE.'
}
/**
- * returns all uppercats category ids of the given category ids
+ * Returns all uppercats category ids of the given category ids.
*
- * @param array cat_ids
- * @return array
+ * @param int[] $cat_ids
+ * @return int[]
*/
function get_uppercat_ids($cat_ids)
{
@@ -729,9 +737,9 @@ SELECT uppercats
}
/**
- * set a new random representant to the categories
+ * Set a new random representant to the categories.
*
- * @param array categories
+ * @param int[] $categories
*/
function set_random_representant($categories)
{
@@ -764,10 +772,10 @@ SELECT image_id
}
/**
- * returns the fulldir for each given category id
+ * Returns the fulldir for each given category id.
*
- * @param array cat_ids
- * @return array
+ * @param int[] intcat_ids
+ * @return string[]
*/
function get_fulldirs($cat_ids)
{
@@ -816,11 +824,10 @@ SELECT id, uppercats, site_id
}
/**
- * returns an array with all file system files according to
- * $conf['file_ext']
+ * Returns an array with all file system files according to $conf['file_ext']
*
* @param string $path
- * @param bool recursive
+ * @param bool $recursive
* @return array
*/
function get_fs($path, $recursive = true)
@@ -902,14 +909,12 @@ function get_fs($path, $recursive = true)
}
/**
- * synchronize base users list and related users list
+ * Synchronize base users list and related users list.
*
- * compares and synchronizes base users table (USERS_TABLE) with its child
+ * Compares and synchronizes base users table (USERS_TABLE) with its child
* tables (USER_INFOS_TABLE, USER_ACCESS, USER_CACHE, USER_GROUP) : each
* base user must be present in child tables, users in child tables not
* present in base table must be deleted.
- *
- * @return void
*/
function sync_users()
{
@@ -971,10 +976,7 @@ DELETE
}
/**
- * updates categories.uppercats field based on categories.id +
- * categories.id_uppercat
- *
- * @return void
+ * Updates categories.uppercats field based on categories.id + categories.id_uppercat
*/
function update_uppercats()
{
@@ -1010,9 +1012,7 @@ SELECT id, id_uppercat, uppercats
}
/**
- * update images.path field
- *
- * @return void
+ * Update images.path field base on images.file and storage categories fulldirs.
*/
function update_path()
{
@@ -1036,12 +1036,11 @@ UPDATE '.IMAGES_TABLE.'
}
/**
- * change the parent category of the given categories. The categories are
+ * Change the parent category of the given categories. The categories are
* supposed virtual.
*
- * @param array category identifiers
- * @param int parent category identifier
- * @return void
+ * @param int[] $category_ids
+ * @param int $new_parent (-1 for root)
*/
function move_categories($category_ids, $new_parent = -1)
{
@@ -1095,11 +1094,10 @@ SELECT uppercats
}
}
- $tables =
- array(
- USER_ACCESS_TABLE => 'user_id',
- GROUP_ACCESS_TABLE => 'group_id'
- );
+ $tables = array(
+ USER_ACCESS_TABLE => 'user_id',
+ GROUP_ACCESS_TABLE => 'group_id'
+ );
$query = '
UPDATE '.CATEGORIES_TABLE.'
@@ -1175,11 +1173,17 @@ DELETE FROM '.$table.'
}
/**
- * create a virtual category
+ * Create a virtual category.
*
- * @param string category name
- * @param int parent category id
- * @return array with ('info' and 'id') or ('error') key
+ * @param string $category_name
+ * @param int $parent_id
+ * @param array $options
+ * - boolean commentable
+ * - boolean visible
+ * - string status
+ * - string comment
+ * - boolean inherit
+ * @return array ('info', 'id') or ('error')
*/
function create_virtual_category($category_name, $parent_id=null, $options=array())
{
@@ -1322,12 +1326,11 @@ SELECT id, uppercats, global_rank, visible, status
}
/**
- * Set tags to an image. Warning: given tags are all tags associated to the
- * image, not additionnal tags.
+ * Set tags to an image.
+ * Warning: given tags are all tags associated to the image, not additionnal tags.
*
- * @param array tag ids
- * @param int image id
- * @return void
+ * @param int[] $tags
+ * @param int $image_id
*/
function set_tags($tags, $image_id)
{
@@ -1337,9 +1340,8 @@ function set_tags($tags, $image_id)
/**
* Add new tags to a set of images.
*
- * @param array tag ids
- * @param array image ids
- * @return void
+ * @param int[] $tags
+ * @param int[] $images
*/
function add_tags($tags, $images)
{
@@ -1378,7 +1380,9 @@ DELETE
}
/**
+ * Delete tags and tags associations.
*
+ * @param int[] $tag_ids
*/
function delete_tags($tag_ids)
{
@@ -1409,7 +1413,13 @@ DELETE
invalidate_user_cache_nb_tags();
}
-function tag_id_from_tag_name($tag_name)
+/**
+ * Returns a tag id from its name. If nothing found, create a new tag.
+ *
+ * @param string $tag_name
+ * @return int
+ */
+function tag_id_from_tag_name($tag_name, $create=true)
{
global $page;
@@ -1454,6 +1464,9 @@ SELECT id
)
)
);
+
+ invalidate_user_cache_nb_tags();
+
$page['tag_id_from_tag_name_cache'][$tag_name] = pwg_db_insert_id(TAGS_TABLE);
return $page['tag_id_from_tag_name_cache'][$tag_name];
}
@@ -1464,6 +1477,11 @@ SELECT id
return $page['tag_id_from_tag_name_cache'][$tag_name];
}
+/**
+ * Set tags of images. Overwrites all existing associations.
+ *
+ * @param array $tags_of - keys are image ids, values are array of tag ids
+ */
function set_tags_of($tags_of)
{
if (count($tags_of) > 0)
@@ -1503,12 +1521,10 @@ DELETE
/**
* Associate a list of images to a list of categories.
+ * The function will not duplicate links and will preserve ranks.
*
- * The function will not duplicate links and will preserve ranks
- *
- * @param array images
- * @param array categories
- * @return void
+ * @param int[] $images
+ * @param int[] $categories
*/
function associate_images_to_categories($images, $categories)
{
@@ -1595,12 +1611,10 @@ SELECT
/**
* Dissociate images from all old categories except their storage category and
* associate to new categories.
+ * This function will preserve ranks.
*
- * This function will preserve ranks
- *
- * @param array images
- * @param array categories
- * @return void
+ * @param int[] $images
+ * @param int[] $categories
*/
function move_images_to_categories($images, $categories)
{
@@ -1639,9 +1653,8 @@ DELETE '.IMAGE_CATEGORY_TABLE.'.*
* Associate images associated to a list of source categories to a list of
* destination categories.
*
- * @param array sources
- * @param array destinations
- * @return void
+ * @param int[] $sources
+ * @param int[] $destinations
*/
function associate_categories_to_categories($sources, $destinations)
{
@@ -1663,8 +1676,7 @@ SELECT image_id
/**
* Refer main Piwigo URLs (currently PHPWG_DOMAIN domain)
*
- * @param void
- * @return array like $conf['links']
+ * @return string[]
*/
function pwg_URL()
{
@@ -1680,7 +1692,7 @@ function pwg_URL()
}
/**
- * Invalidates cahed data (permissions and category counts) for all users.
+ * Invalidates cached data (permissions and category counts) for all users.
*/
function invalidate_user_cache($full = true)
{
@@ -1703,11 +1715,14 @@ UPDATE '.USER_CACHE_TABLE.'
trigger_action('invalidate_user_cache', $full);
}
-
+/**
+ * Invalidates cached tags counter for all users.
+ */
function invalidate_user_cache_nb_tags()
{
global $user;
unset($user['nb_available_tags']);
+
$query = '
UPDATE '.USER_CACHE_TABLE.'
SET nb_available_tags = NULL';
@@ -1715,9 +1730,11 @@ UPDATE '.USER_CACHE_TABLE.'
}
/**
- * adds the caracter set to a create table sql query.
- * all CREATE TABLE queries must call this function
- * @param string query - the sql query
+ * Adds the caracter set to a create table sql query.
+ * All CREATE TABLE queries must call this function
+ *
+ * @param string $query
+ * @return string
*/
function create_table_add_character_set($query)
{
@@ -1762,9 +1779,11 @@ function create_table_add_character_set($query)
}
/**
- * Returns array use on template with html_options method
- * @param Min and Max access to use
- * @return array of user access level
+ * Returns access levels as array used on template with html_options functions.
+ *
+ * @param int $MinLevelAccess
+ * @param int $MaxLevelAccess
+ * @return array
*/
function get_user_access_level_html_options($MinLevelAccess = ACCESS_FREE, $MaxLevelAccess = ACCESS_CLOSED)
{
@@ -1777,9 +1796,11 @@ function get_user_access_level_html_options($MinLevelAccess = ACCESS_FREE, $MaxL
}
/**
- * returns a list of templates currently available in template-extension
+ * returns a list of templates currently available in template-extension.
* Each .tpl file is extracted from template-extension.
- * @return array
+ *
+ * @param string $start (internal use)
+ * @return string[]
*/
function get_extents($start='')
{
@@ -1804,6 +1825,12 @@ function get_extents($start='')
return $extents;
}
+/**
+ * Create a new tag.
+ *
+ * @param string $tag_name
+ * @return array ('id', info') or ('error')
+ */
function create_tag($tag_name)
{
// does the tag already exists?
@@ -1841,11 +1868,10 @@ SELECT id
/**
* Is the category accessible to the (Admin) user ?
- *
* Note : if the user is not authorized to see this category, category jump
* will be replaced by admin cat_modify page
*
- * @param int category id to verify
+ * @param int $category_id
* @return bool
*/
function cat_admin_access($category_id)
@@ -1862,10 +1888,14 @@ function cat_admin_access($category_id)
}
/**
- * Retrieve data from external URL
+ * Retrieve data from external URL.
*
- * @param string $src: URL
- * @param global $dest: can be a file ressource or string
+ * @param string $src
+ * @param string|Ressource $dest - can be a file ressource or string
+ * @param array $get_data - data added to request url
+ * @param array $post_data - data transmitted with POST
+ * @param string $user_agent
+ * @param int $step (internal use)
* @return bool
*/
function fetchRemote($src, &$dest, $get_data=array(), $post_data=array(), $user_agent='Piwigo', $step=0)
@@ -2019,13 +2049,11 @@ function fetchRemote($src, &$dest, $get_data=array(), $post_data=array(), $user_
return true;
}
-
/**
- * returns the groupname corresponding to the given group identifier if
- * exists
+ * Returns the groupname corresponding to the given group identifier if exists.
*
- * @param int group_id
- * @return mixed
+ * @param int $group_id
+ * @return string|false
*/
function get_groupname($group_id)
{
@@ -2048,10 +2076,10 @@ SELECT name
}
/**
- * returns the username corresponding to the given user identifier if exists
+ * Returns the username corresponding to the given user identifier if exists.
*
- * @param int user_id
- * @return mixed
+ * @param int $user_id
+ * @return string|false
*/
function get_username($user_id)
{
@@ -2075,13 +2103,22 @@ SELECT '.$conf['user_fields']['username'].'
return stripslashes($username);
}
-function get_newsletter_subscribe_base_url($language) {
+/**
+ * Get url on piwigo.org for newsletter subscription
+ *
+ * @param string $language (unused)
+ * @return string
+ */
+function get_newsletter_subscribe_base_url($language='en_UK')
+{
return PHPWG_URL.'/announcement/subscribe/';
}
/**
- * Accordion menus need to know which section to open by default when
- * loading the page
+ * Return admin menu id for accordion.
+ *
+ * @param string $menu_page
+ * @return int
*/
function get_active_menu($menu_page)
{
@@ -2136,14 +2173,19 @@ function get_active_menu($menu_page)
case 'theme':
case 'languages':
return 5;
+
+ default:
+ return 0;
}
- return 0;
}
-/*
- * get tags list from SQL query (ids are surrounded by ~~, for get_tag_ids())
- * @param string: query
- * @param boolean: only_user_language, if true, only local name is returned for multilingual tags
+/**
+ * Get tags list from SQL query (ids are surrounded by ~~, for get_tag_ids()).
+ *
+ * @param string $query
+ * @param boolean $only_user_language - if true, only local name is returned for
+ * multilingual tags (if ExtendedDescription plugin is active)
+ * @return array[] ('id', 'name')
*/
function get_taglist($query, $only_user_language=true)
{
@@ -2185,18 +2227,20 @@ function get_taglist($query, $only_user_language=true)
return $taglist;
}
-/*
- * get tags ids from a list of raw tags (existing tags or new tags)
- * @param mixed: raw_tags, array or comma separated string
- * @param boolean: allow_create
+/**
+ * Get tags ids from a list of raw tags (existing tags or new tags).
+ *
+ * In $raw_tags we receive something like array('~~6~~', '~~59~~', 'New
+ * tag', 'Another new tag') The ~~34~~ means that it is an existing
+ * tag. We added the surrounding ~~ to permit creation of tags like "10"
+ * or "1234" (numeric characters only)
+ *
+ * @param string|string[] $raw_tags - array or comma separated string
+ * @param boolean $allow_create
+ * @return int[]
*/
function get_tag_ids($raw_tags, $allow_create=true)
{
- // In $raw_tags we receive something like array('~~6~~', '~~59~~', 'New
- // tag', 'Another new tag') The ~~34~~ means that it is an existing
- // tag. I've added the surrounding ~~ to permit creation of tags like "10"
- // or "1234" (numeric characters only)
-
$tag_ids = array();
if (!is_array($raw_tags))
{
@@ -2219,11 +2263,16 @@ function get_tag_ids($raw_tags, $allow_create=true)
return $tag_ids;
}
-/** returns the argument_ids array with new sequenced keys based on related
+/**
+ * Returns the argument_ids array with new sequenced keys based on related
* names. Sequence is not case sensitive.
- * Warning: By definition, this function breaks original keys
+ * Warning: By definition, this function breaks original keys.
+ *
+ * @param int[] $elements_ids
+ * @param string[] $name - names of elements, indexed by ids
+ * @return int[]
*/
-function order_by_name($element_ids,$name)
+function order_by_name($element_ids, $name)
{
$ordered_element_ids = array();
foreach ($element_ids as $k_id => $element_id)
@@ -2235,14 +2284,18 @@ function order_by_name($element_ids,$name)
return $ordered_element_ids;
}
+/**
+ * Grant access to a list of categories for a list of users.
+ *
+ * @param int[] $category_ids
+ * @param int[] $user_ids
+ */
function add_permission_on_category($category_ids, $user_ids)
{
- // array-ify categories and users
if (!is_array($category_ids))
{
$category_ids = array($category_ids);
}
-
if (!is_array($user_ids))
{
$user_ids = array($user_ids);
@@ -2294,7 +2347,12 @@ SELECT id
);
}
-
+/**
+ * Returns the list of admin users.
+ *
+ * @param boolean $include_webmaster
+ * @return int[]
+ */
function get_admins($include_webmaster=true)
{
$status_list = array('admin');
@@ -2314,7 +2372,11 @@ SELECT
return array_from_query($query, 'user_id');
}
-/** delete all derivative files for one or several types */
+/**
+ * Delete all derivative files for one or several types
+ *
+ * @param 'all'|int[] $types
+ */
function clear_derivative_cache($types='all')
{
if ($types === 'all')
@@ -2371,6 +2433,10 @@ function clear_derivative_cache($types='all')
}
}
+/**
+ * Used by clear_derivative_cache()
+ * @ignore
+ */
function clear_derivative_cache_rec($path, $pattern)
{
$rmdir = true;
@@ -2417,6 +2483,12 @@ function clear_derivative_cache_rec($path, $pattern)
}
}
+/**
+ * Deletes derivatives of a particular element
+ *
+ * @param array $infos ('path'[, 'representative_ext'])
+ * @param 'all'|int $type
+ */
function delete_element_derivatives($infos, $type='all')
{
$path = $infos['path'];
@@ -2448,10 +2520,10 @@ function delete_element_derivatives($infos, $type='all')
}
/**
- * returns an array contening sub-directories, excluding ".svn"
+ * Returns an array containing sub-directories, excluding ".svn"
*
- * @param string $dir
- * @return array
+ * @param string $directory
+ * @return string[]
*/
function get_dirs($directory)
{
@@ -2474,7 +2546,8 @@ function get_dirs($directory)
}
/**
- * recursively delete a directory
+ * Recursively delete a directory.
+ *
* @param string $path
* @param string $trash_path, try to move the directory to this path if it cannot be delete
*/