Changeset 26807


Ignore:
Timestamp:
01/16/14 16:24:36 (6 years ago)
Author:
mistic100
Message:

feature 2999: documentation of admin/include/functions.php

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/admin/include/functions.php

    r26649 r26807  
    2222// +-----------------------------------------------------------------------+ 
    2323 
    24 include(PHPWG_ROOT_PATH.'admin/include/functions_metadata.php'); 
    25  
    26 // The function delete_site deletes a site and call the function 
    27 // delete_categories for each primary category of the site 
    28 function delete_site( $id ) 
     24/** 
     25 * @package functions\admin\___ 
     26 */ 
     27 
     28include_once(PHPWG_ROOT_PATH.'admin/include/functions_metadata.php'); 
     29 
     30 
     31/** 
     32 * Deletes a site and call delete_categories for each primary category of the site 
     33 * 
     34 * @param int $id 
     35 */ 
     36function delete_site($id) 
    2937{ 
    3038  // destruction of the categories of the site 
     
    4553} 
    4654 
    47  
    48 // The function delete_categories deletes the categories identified by the 
    49 // (numeric) key of the array $ids. It also deletes (in the database) : 
    50 //    - all the elements physically linked to the category (delete_elements, see further) 
    51 //    - all the links between elements and this category 
    52 //    - all the restrictions linked to the category 
    53 // The function works recursively. 
    54 // 
    55 // the $photo_deletion_mode is for photos virtually linked to the categorty 
    56 //   * no_delete : delete no photo, may create orphans 
    57 //   * delete_orphans : delete photos that are no longer linked to any category 
    58 //   * force_delete : delete photos even if they are linked to another category 
     55/** 
     56 * Recursively deletes one or more categories. 
     57 * It also deletes : 
     58 *    - all the elements physically linked to the category (with delete_elements) 
     59 *    - all the links between elements and this category 
     60 *    - all the restrictions linked to the category 
     61 * 
     62 * @param int[] $ids 
     63 * @param string $photo_deletion_mode 
     64 *    - no_delete : delete no photo, may create orphans 
     65 *    - delete_orphans : delete photos that are no longer linked to any category 
     66 *    - force_delete : delete photos even if they are linked to another category 
     67 */ 
    5968function delete_categories($ids, $photo_deletion_mode='no_delete') 
    6069{ 
     
    157166} 
    158167 
    159 // Deletes all files (on disk) related to given image ids 
    160 // @return image ids where files are deleted successfully 
     168/** 
     169 * Deletes all files (on disk) related to given image ids. 
     170 * 
     171 * @param int[] $ids 
     172 * @return 0|int[] image ids where files were successfully deleted 
     173 */ 
    161174function delete_element_files($ids) 
    162175{ 
     
    220233} 
    221234 
    222 // The function delete_elements deletes the elements identified by the 
    223 // (numeric) values of the array $ids. It also deletes (in the database) : 
    224 //    - all the comments related to elements 
    225 //    - all the links between categories and elements 
    226 //    - all the favorites associated to elements 
    227 // @return number of deleted elements 
     235/** 
     236 * Deletes elements from database. 
     237 * It also deletes : 
     238 *    - all the comments related to elements 
     239 *    - all the links between categories/tags and elements 
     240 *    - all the favorites/rates associated to elements 
     241 *    - removes elements from caddie 
     242 * 
     243 * @param int[] $ids 
     244 * @param bool $physical_deletion 
     245 * @return int number of deleted elements 
     246 */ 
    228247function delete_elements($ids, $physical_deletion=false) 
    229248{ 
     
    242261    } 
    243262  } 
     263   
     264  $ids_str = wordwrap(implode(', ', $ids), 80, "\n"); 
    244265 
    245266  // destruction of the comments on the image 
    246267  $query = ' 
    247268DELETE FROM '.COMMENTS_TABLE.' 
    248   WHERE image_id IN ( 
    249 '.wordwrap(implode(', ', $ids), 80, "\n").') 
     269  WHERE image_id IN ('. $ids_str .') 
    250270;'; 
    251271  pwg_query($query); 
    252272 
    253   // destruction of the links between images and this category 
     273  // destruction of the links between images and categories 
    254274  $query = ' 
    255275DELETE FROM '.IMAGE_CATEGORY_TABLE.' 
    256   WHERE image_id IN ( 
    257 '.wordwrap(implode(', ', $ids), 80, "\n").') 
     276  WHERE image_id IN ('. $ids_str .') 
    258277;'; 
    259278  pwg_query($query); 
     
    262281  $query = ' 
    263282DELETE FROM '.IMAGE_TAG_TABLE.' 
    264   WHERE image_id IN ( 
    265 '.wordwrap(implode(', ', $ids), 80, "\n").') 
     283  WHERE image_id IN ('. $ids_str .') 
    266284;'; 
    267285  pwg_query($query); 
     
    270288  $query = ' 
    271289DELETE FROM '.FAVORITES_TABLE.' 
    272   WHERE image_id IN ( 
    273 '.wordwrap(implode(', ', $ids), 80, "\n").') 
     290  WHERE image_id IN ('. $ids_str .') 
    274291;'; 
    275292  pwg_query($query); 
     
    278295  $query = ' 
    279296DELETE FROM '.RATE_TABLE.' 
    280   WHERE element_id IN ( 
    281 '.wordwrap(implode(', ', $ids), 80, "\n").') 
     297  WHERE element_id IN ('. $ids_str .') 
    282298;'; 
    283299  pwg_query($query); 
    284300 
    285   // destruction of the rates associated to this element 
     301  // destruction of the caddie associated to this element 
    286302  $query = ' 
    287303DELETE FROM '.CADDIE_TABLE.' 
    288   WHERE element_id IN ( 
    289 '.wordwrap(implode(', ', $ids), 80, "\n").') 
     304  WHERE element_id IN ('. $ids_str .') 
    290305;'; 
    291306  pwg_query($query); 
     
    294309  $query = ' 
    295310DELETE FROM '.IMAGES_TABLE.' 
    296   WHERE id IN ( 
    297 '.wordwrap(implode(', ', $ids), 80, "\n").') 
     311  WHERE id IN ('. $ids_str .') 
    298312;'; 
    299313  pwg_query($query); 
     
    304318    id 
    305319  FROM '.CATEGORIES_TABLE.' 
    306   WHERE representative_picture_id IN ( 
    307 '.wordwrap(implode(', ', $ids), 80, "\n").') 
     320  WHERE representative_picture_id IN ('. $ids_str .') 
    308321;'; 
    309322  $category_ids = array_from_query($query, 'id'); 
     
    317330} 
    318331 
    319 // The delete_user function delete a user identified by the $user_id 
    320 // It also deletes : 
    321 //     - all the access linked to this user 
    322 //     - all the links to any group 
    323 //     - all the favorites linked to this user 
    324 //     - calculated permissions linked to the user 
    325 //     - all datas about notifications for the user 
     332/** 
     333 * Deletes an user. 
     334 * It also deletes all related data (accesses, favorites, permissions, etc.) 
     335 * @todo : accept array input 
     336 * 
     337 * @param int $user_id 
     338 */ 
    326339function delete_user($user_id) 
    327340{ 
     
    357370  } 
    358371 
    359   // destruction of the user 
     372  // purge of sessions 
    360373  $query = ' 
    361374DELETE FROM '.SESSIONS_TABLE.' 
     
    416429/** 
    417430 * Verifies that the representative picture really exists in the db and 
    418  * picks up a random represantive if possible and based on config. 
    419  * 
    420  * @param mixed category id 
    421  * @returns void 
     431 * picks up a random representative if possible and based on config. 
     432 * 
     433 * @param 'all'|int|int[] $ids 
    422434 */ 
    423435function update_category($ids = 'all') 
     
    486498 
    487499/** 
    488  * check and repair images integrity 
    489  * 
    490  * TODO see delete_elements function to check all linked tables 
     500 * Checks and repairs IMAGE_CATEGORY_TABLE integrity. 
     501 * Removes all entries from the table which correspond to a deleted image. 
    491502 */ 
    492503function images_integrity() 
     
    514525 
    515526/** 
    516  * returns an array containing sub-directories which can be a category, 
    517  * recursive by default 
    518  * 
    519  * directories nammed "thumbnail", "pwg_high" or "pwg_representative" are 
    520  * omitted 
    521  * 
    522  * @param string $basedir 
    523  * @return array 
     527 * Returns an array containing sub-directories which are potentially 
     528 * a category. 
     529 * Directories named ".svn", "thumbnail", "pwg_high" or "pwg_representative" 
     530 * are omitted. 
     531 * 
     532 * @param string $basedir (eg: ./galleries) 
     533 * @return string[] 
    524534 */ 
    525535function get_fs_directories($path, $recursive = true) 
    526536{ 
    527537  $dirs = array(); 
     538  $path = rtrim($path, '/'); 
    528539 
    529540  if (is_dir($path)) 
     
    556567 
    557568/** 
    558  * order categories (update categories.rank and global_rank database fields) 
    559  * so that rank field are consecutive integers starting at 1 for each child 
    560  * @return void 
     569 * Orders categories (update categories.rank and global_rank database fields) 
     570 * so that rank field are consecutive integers starting at 1 for each child. 
    561571 */ 
    562572function update_global_rank() 
     
    624634 
    625635/** 
    626  * change the visible property on a set of categories 
    627  * 
    628  * @param array categories 
    629  * @param string value 
    630  * @return void 
     636 * Change the **visible** property on a set of categories. 
     637 * 
     638 * @param int[] $categories 
     639 * @param boolean|string $value 
    631640 */ 
    632641function set_cat_visible($categories, $value) 
    633642{ 
    634   if (!in_array($value, array('true', 'false'))) 
     643  if ( ($value = filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE)) === null ) 
    635644  { 
    636645    trigger_error("set_cat_visible invalid param $value", E_USER_WARNING); 
     
    639648 
    640649  // unlocking a category => all its parent categories become unlocked 
    641   if ($value == 'true') 
     650  if ($value) 
    642651  { 
    643652    $uppercats = get_uppercat_ids($categories); 
     
    649658  } 
    650659  // locking a category   => all its child categories become locked 
    651   if ($value == 'false') 
     660  else 
    652661  { 
    653662    $subcats = get_subcat_ids($categories); 
     
    661670 
    662671/** 
    663  * change the status property on a set of categories : private or public 
    664  * 
    665  * @param array categories 
    666  * @param string value 
    667  * @return void 
     672 * Change the **status** property on a set of categories : private or public. 
     673 * 
     674 * @param int[] $categories 
     675 * @param string $value 
    668676 */ 
    669677function set_cat_status($categories, $value) 
     
    699707 
    700708/** 
    701  * returns all uppercats category ids of the given category ids 
    702  * 
    703  * @param array cat_ids 
    704  * @return array 
     709 * Returns all uppercats category ids of the given category ids. 
     710 * 
     711 * @param int[] $cat_ids 
     712 * @return int[] 
    705713 */ 
    706714function get_uppercat_ids($cat_ids) 
     
    730738 
    731739/** 
    732  * set a new random representant to the categories 
    733  * 
    734  * @param array categories 
     740 * Set a new random representant to the categories. 
     741 * 
     742 * @param int[] $categories 
    735743 */ 
    736744function set_random_representant($categories) 
     
    765773 
    766774/** 
    767  * returns the fulldir for each given category id 
    768  * 
    769  * @param array cat_ids 
    770  * @return array 
     775 * Returns the fulldir for each given category id. 
     776 * 
     777 * @param int[] intcat_ids 
     778 * @return string[] 
    771779 */ 
    772780function get_fulldirs($cat_ids) 
     
    817825 
    818826/** 
    819  * returns an array with all file system files according to 
    820  * $conf['file_ext'] 
     827 * Returns an array with all file system files according to $conf['file_ext'] 
    821828 * 
    822829 * @param string $path 
    823  * @param bool recursive 
     830 * @param bool $recursive 
    824831 * @return array 
    825832 */ 
     
    903910 
    904911/** 
    905  * synchronize base users list and related users list 
    906  * 
    907  * compares and synchronizes base users table (USERS_TABLE) with its child 
     912 * Synchronize base users list and related users list. 
     913 * 
     914 * Compares and synchronizes base users table (USERS_TABLE) with its child 
    908915 * tables (USER_INFOS_TABLE, USER_ACCESS, USER_CACHE, USER_GROUP) : each 
    909916 * base user must be present in child tables, users in child tables not 
    910917 * present in base table must be deleted. 
    911  * 
    912  * @return void 
    913918 */ 
    914919function sync_users() 
     
    972977 
    973978/** 
    974  * updates categories.uppercats field based on categories.id + 
    975  * categories.id_uppercat 
    976  * 
    977  * @return void 
     979 * Updates categories.uppercats field based on categories.id + categories.id_uppercat 
    978980 */ 
    979981function update_uppercats() 
     
    10111013 
    10121014/** 
    1013  * update images.path field 
    1014  * 
    1015  * @return void 
     1015 * Update images.path field base on images.file and storage categories fulldirs. 
    10161016 */ 
    10171017function update_path() 
     
    10371037 
    10381038/** 
    1039  * change the parent category of the given categories. The categories are 
     1039 * Change the parent category of the given categories. The categories are 
    10401040 * supposed virtual. 
    10411041 * 
    1042  * @param array category identifiers 
    1043  * @param int parent category identifier 
    1044  * @return void 
     1042 * @param int[] $category_ids 
     1043 * @param int $new_parent (-1 for root) 
    10451044 */ 
    10461045function move_categories($category_ids, $new_parent = -1) 
     
    10961095  } 
    10971096 
    1098   $tables = 
    1099     array( 
    1100       USER_ACCESS_TABLE => 'user_id', 
    1101       GROUP_ACCESS_TABLE => 'group_id' 
    1102       ); 
     1097  $tables = array( 
     1098    USER_ACCESS_TABLE => 'user_id', 
     1099    GROUP_ACCESS_TABLE => 'group_id' 
     1100    ); 
    11031101 
    11041102  $query = ' 
     
    11761174 
    11771175/** 
    1178  * create a virtual category 
    1179  * 
    1180  * @param string category name 
    1181  * @param int parent category id 
    1182  * @return array with ('info' and 'id') or ('error') key 
     1176 * Create a virtual category. 
     1177 * 
     1178 * @param string $category_name 
     1179 * @param int $parent_id 
     1180 * @param array $options 
     1181 *    - boolean commentable 
     1182 *    - boolean visible 
     1183 *    - string status 
     1184 *    - string comment 
     1185 *    - boolean inherit 
     1186 * @return array ('info', 'id') or ('error') 
    11831187 */ 
    11841188function create_virtual_category($category_name, $parent_id=null, $options=array()) 
     
    13231327 
    13241328/** 
    1325  * Set tags to an image. Warning: given tags are all tags associated to the 
    1326  * image, not additionnal tags. 
    1327  * 
    1328  * @param array tag ids 
    1329  * @param int image id 
    1330  * @return void 
     1329 * Set tags to an image. 
     1330 * Warning: given tags are all tags associated to the image, not additionnal tags. 
     1331 * 
     1332 * @param int[] $tags 
     1333 * @param int $image_id 
    13311334 */ 
    13321335function set_tags($tags, $image_id) 
     
    13381341 * Add new tags to a set of images. 
    13391342 * 
    1340  * @param array tag ids 
    1341  * @param array image ids 
    1342  * @return void 
     1343 * @param int[] $tags 
     1344 * @param int[] $images 
    13431345 */ 
    13441346function add_tags($tags, $images) 
     
    13791381 
    13801382/** 
    1381  * 
     1383 * Delete tags and tags associations. 
     1384 * 
     1385 * @param int[] $tag_ids 
    13821386 */ 
    13831387function delete_tags($tag_ids) 
     
    14101414} 
    14111415 
    1412 function tag_id_from_tag_name($tag_name) 
     1416/** 
     1417 * Returns a tag id from its name. If nothing found, create a new tag. 
     1418 * 
     1419 * @param string $tag_name 
     1420 * @return int 
     1421 */ 
     1422function tag_id_from_tag_name($tag_name, $create=true) 
    14131423{ 
    14141424  global $page; 
     
    14551465            ) 
    14561466          ); 
     1467 
     1468        invalidate_user_cache_nb_tags(); 
     1469 
    14571470        $page['tag_id_from_tag_name_cache'][$tag_name] = pwg_db_insert_id(TAGS_TABLE); 
    14581471        return $page['tag_id_from_tag_name_cache'][$tag_name]; 
     
    14651478} 
    14661479 
     1480/** 
     1481 * Set tags of images. Overwrites all existing associations. 
     1482 * 
     1483 * @param array $tags_of - keys are image ids, values are array of tag ids 
     1484 */ 
    14671485function set_tags_of($tags_of) 
    14681486{ 
     
    15041522/** 
    15051523 * Associate a list of images to a list of categories. 
    1506  * 
    1507  * The function will not duplicate links and will preserve ranks 
    1508  * 
    1509  * @param array images 
    1510  * @param array categories 
    1511  * @return void 
     1524 * The function will not duplicate links and will preserve ranks. 
     1525 * 
     1526 * @param int[] $images 
     1527 * @param int[] $categories 
    15121528 */ 
    15131529function associate_images_to_categories($images, $categories) 
     
    15961612 * Dissociate images from all old categories except their storage category and 
    15971613 * associate to new categories. 
    1598  * 
    1599  * This function will preserve ranks 
    1600  * 
    1601  * @param array images 
    1602  * @param array categories 
    1603  * @return void 
     1614 * This function will preserve ranks. 
     1615 * 
     1616 * @param int[] $images 
     1617 * @param int[] $categories 
    16041618 */ 
    16051619function move_images_to_categories($images, $categories) 
     
    16401654 * destination categories. 
    16411655 * 
    1642  * @param array sources 
    1643  * @param array destinations 
    1644  * @return void 
     1656 * @param int[] $sources 
     1657 * @param int[] $destinations 
    16451658 */ 
    16461659function associate_categories_to_categories($sources, $destinations) 
     
    16641677 * Refer main Piwigo URLs (currently PHPWG_DOMAIN domain) 
    16651678 * 
    1666  * @param void 
    1667  * @return array like $conf['links'] 
     1679 * @return string[] 
    16681680 */ 
    16691681function pwg_URL() 
     
    16811693 
    16821694/** 
    1683  * Invalidates cahed data (permissions and category counts) for all users. 
     1695 * Invalidates cached data (permissions and category counts) for all users. 
    16841696 */ 
    16851697function invalidate_user_cache($full = true) 
     
    17041716} 
    17051717 
    1706  
     1718/** 
     1719 * Invalidates cached tags counter for all users. 
     1720 */ 
    17071721function invalidate_user_cache_nb_tags() 
    17081722{ 
    17091723  global $user; 
    17101724  unset($user['nb_available_tags']); 
     1725 
    17111726  $query = ' 
    17121727UPDATE '.USER_CACHE_TABLE.' 
     
    17161731 
    17171732/** 
    1718  * adds the caracter set to a create table sql query. 
    1719  * all CREATE TABLE queries must call this function 
    1720  * @param string query - the sql query 
     1733 * Adds the caracter set to a create table sql query. 
     1734 * All CREATE TABLE queries must call this function 
     1735 * 
     1736 * @param string $query 
     1737 * @return string 
    17211738 */ 
    17221739function create_table_add_character_set($query) 
     
    17631780 
    17641781/** 
    1765  * Returns array use on template with html_options method 
    1766  * @param Min and Max access to use 
    1767  * @return array of user access level 
     1782 * Returns access levels as array used on template with html_options functions. 
     1783 * 
     1784 * @param int $MinLevelAccess 
     1785 * @param int $MaxLevelAccess 
     1786 * @return array 
    17681787 */ 
    17691788function get_user_access_level_html_options($MinLevelAccess = ACCESS_FREE, $MaxLevelAccess = ACCESS_CLOSED) 
     
    17781797 
    17791798/** 
    1780  * returns a list of templates currently available in template-extension 
     1799 * returns a list of templates currently available in template-extension. 
    17811800 * Each .tpl file is extracted from template-extension. 
    1782  * @return array 
     1801 * 
     1802 * @param string $start (internal use) 
     1803 * @return string[] 
    17831804 */ 
    17841805function get_extents($start='') 
     
    18051826} 
    18061827 
     1828/** 
     1829 * Create a new tag. 
     1830 * 
     1831 * @param string $tag_name 
     1832 * @return array ('id', info') or ('error') 
     1833 */ 
    18071834function create_tag($tag_name) 
    18081835{ 
     
    18421869/** 
    18431870 * Is the category accessible to the (Admin) user ? 
    1844  * 
    18451871 * Note : if the user is not authorized to see this category, category jump 
    18461872 * will be replaced by admin cat_modify page 
    18471873 * 
    1848  * @param int category id to verify 
     1874 * @param int $category_id 
    18491875 * @return bool 
    18501876 */ 
     
    18631889 
    18641890/** 
    1865  * Retrieve data from external URL 
    1866  * 
    1867  * @param string $src: URL 
    1868  * @param global $dest: can be a file ressource or string 
     1891 * Retrieve data from external URL. 
     1892 * 
     1893 * @param string $src 
     1894 * @param string|Ressource $dest - can be a file ressource or string 
     1895 * @param array $get_data - data added to request url 
     1896 * @param array $post_data - data transmitted with POST 
     1897 * @param string $user_agent 
     1898 * @param int $step (internal use) 
    18691899 * @return bool 
    18701900 */ 
     
    20202050} 
    20212051 
    2022  
    2023 /** 
    2024  * returns the groupname corresponding to the given group identifier if 
    2025  * exists 
    2026  * 
    2027  * @param int group_id 
    2028  * @return mixed 
     2052/** 
     2053 * Returns the groupname corresponding to the given group identifier if exists. 
     2054 * 
     2055 * @param int $group_id 
     2056 * @return string|false 
    20292057 */ 
    20302058function get_groupname($group_id) 
     
    20492077 
    20502078/** 
    2051  * returns the username corresponding to the given user identifier if exists 
    2052  * 
    2053  * @param int user_id 
    2054  * @return mixed 
     2079 * Returns the username corresponding to the given user identifier if exists. 
     2080 * 
     2081 * @param int $user_id 
     2082 * @return string|false 
    20552083 */ 
    20562084function get_username($user_id) 
     
    20762104} 
    20772105 
    2078 function get_newsletter_subscribe_base_url($language) { 
     2106/** 
     2107 * Get url on piwigo.org for newsletter subscription 
     2108 * 
     2109 * @param string $language (unused) 
     2110 * @return string 
     2111 */ 
     2112function get_newsletter_subscribe_base_url($language='en_UK') 
     2113{ 
    20792114  return PHPWG_URL.'/announcement/subscribe/'; 
    20802115} 
    20812116 
    20822117/** 
    2083  * Accordion menus need to know which section to open by default when 
    2084  * loading the page 
     2118 * Return admin menu id for accordion. 
     2119 * 
     2120 * @param string $menu_page 
     2121 * @return int 
    20852122 */ 
    20862123function get_active_menu($menu_page) 
     
    21372174    case 'languages': 
    21382175      return 5; 
    2139   } 
    2140   return 0; 
    2141 } 
    2142  
    2143 /* 
    2144  * get tags list from SQL query (ids are surrounded by ~~, for get_tag_ids()) 
    2145  * @param string: query 
    2146  * @param boolean: only_user_language, if true, only local name is returned for multilingual tags 
     2176 
     2177    default: 
     2178      return 0; 
     2179  } 
     2180} 
     2181 
     2182/** 
     2183 * Get tags list from SQL query (ids are surrounded by ~~, for get_tag_ids()). 
     2184 * 
     2185 * @param string $query 
     2186 * @param boolean $only_user_language - if true, only local name is returned for 
     2187 *    multilingual tags (if ExtendedDescription plugin is active) 
     2188 * @return array[] ('id', 'name') 
    21472189 */ 
    21482190function get_taglist($query, $only_user_language=true) 
     
    21862228} 
    21872229 
    2188 /* 
    2189  * get tags ids from a list of raw tags (existing tags or new tags) 
    2190  * @param mixed: raw_tags, array or comma separated string 
    2191  * @param boolean: allow_create 
     2230/** 
     2231 * Get tags ids from a list of raw tags (existing tags or new tags). 
     2232 * 
     2233 * In $raw_tags we receive something like array('~~6~~', '~~59~~', 'New 
     2234 * tag', 'Another new tag') The ~~34~~ means that it is an existing 
     2235 * tag. We added the surrounding ~~ to permit creation of tags like "10" 
     2236 * or "1234" (numeric characters only) 
     2237 * 
     2238 * @param string|string[] $raw_tags - array or comma separated string 
     2239 * @param boolean $allow_create 
     2240 * @return int[] 
    21922241 */ 
    21932242function get_tag_ids($raw_tags, $allow_create=true) 
    21942243{ 
    2195   // In $raw_tags we receive something like array('~~6~~', '~~59~~', 'New 
    2196   // tag', 'Another new tag') The ~~34~~ means that it is an existing 
    2197   // tag. I've added the surrounding ~~ to permit creation of tags like "10" 
    2198   // or "1234" (numeric characters only) 
    2199  
    22002244  $tag_ids = array(); 
    22012245  if (!is_array($raw_tags)) 
     
    22202264} 
    22212265 
    2222 /** returns the argument_ids array with new sequenced keys based on related 
     2266/** 
     2267 * Returns the argument_ids array with new sequenced keys based on related 
    22232268 * names. Sequence is not case sensitive. 
    2224  * Warning: By definition, this function breaks original keys 
    2225  */ 
    2226 function order_by_name($element_ids,$name) 
     2269 * Warning: By definition, this function breaks original keys. 
     2270 * 
     2271 * @param int[] $elements_ids 
     2272 * @param string[] $name - names of elements, indexed by ids 
     2273 * @return int[] 
     2274 */ 
     2275function order_by_name($element_ids, $name) 
    22272276{ 
    22282277  $ordered_element_ids = array(); 
     
    22362285} 
    22372286 
     2287/** 
     2288 * Grant access to a list of categories for a list of users. 
     2289 * 
     2290 * @param int[] $category_ids 
     2291 * @param int[] $user_ids 
     2292 */ 
    22382293function add_permission_on_category($category_ids, $user_ids) 
    22392294{ 
    2240   // array-ify categories and users 
    22412295  if (!is_array($category_ids)) 
    22422296  { 
    22432297    $category_ids = array($category_ids); 
    22442298  } 
    2245  
    22462299  if (!is_array($user_ids)) 
    22472300  { 
     
    22952348} 
    22962349 
    2297  
     2350/** 
     2351 * Returns the list of admin users. 
     2352 * 
     2353 * @param boolean $include_webmaster 
     2354 * @return int[] 
     2355 */ 
    22982356function get_admins($include_webmaster=true) 
    22992357{ 
     
    23152373} 
    23162374 
    2317 /** delete all derivative files for one or several types */ 
     2375/** 
     2376 * Delete all derivative files for one or several types 
     2377 * 
     2378 * @param 'all'|int[] $types 
     2379 */ 
    23182380function clear_derivative_cache($types='all') 
    23192381{ 
     
    23722434} 
    23732435 
     2436/** 
     2437 * Used by clear_derivative_cache() 
     2438 * @ignore 
     2439 */ 
    23742440function clear_derivative_cache_rec($path, $pattern) 
    23752441{ 
     
    24182484} 
    24192485 
     2486/** 
     2487 * Deletes derivatives of a particular element 
     2488 * 
     2489 * @param array $infos ('path'[, 'representative_ext']) 
     2490 * @param 'all'|int $type 
     2491 */ 
    24202492function delete_element_derivatives($infos, $type='all') 
    24212493{ 
     
    24492521 
    24502522/** 
    2451  * returns an array contening sub-directories, excluding ".svn" 
    2452  * 
    2453  * @param string $dir 
    2454  * @return array 
     2523 * Returns an array containing sub-directories, excluding ".svn" 
     2524 * 
     2525 * @param string $directory 
     2526 * @return string[] 
    24552527 */ 
    24562528function get_dirs($directory) 
     
    24752547 
    24762548/** 
    2477  * recursively delete a directory 
     2549 * Recursively delete a directory. 
     2550 * 
    24782551 * @param string $path 
    24792552 * @param string $trash_path, try to move the directory to this path if it cannot be delete 
Note: See TracChangeset for help on using the changeset viewer.