WordPress.org

Make WordPress Core

Ticket #4742: taxonomy.6372.phpdoc.diff

File taxonomy.6372.phpdoc.diff, 17.8 KB (added by darkdragon, 6 years ago)

Finishes documentation for the Taxonomy API, based off of r6372

  • taxonomy.php

     
    235235 * name as parameters. Both hooks are expected to return a Term object. 
    236236 * 
    237237 * 'get_term' hook - Takes two parameters the term Object and the taxonomy name. Must return 
    238  * term object. Used in @see get_term() as a catch-all filter for every $term. 
     238 * term object. Used in get_term() as a catch-all filter for every $term. 
    239239 * 
    240240 * 'get_$taxonomy' hook - Takes two parameters the term Object and the taxonomy name. Must return 
    241241 * term object. $taxonomy will be the taxonomy name, so for example, if 'category', it would be 
     
    246246 * @since 2.3 
    247247 * 
    248248 * @uses $wpdb 
     249 * @uses sanitize_term() Cleanses the term based on $filter context before returning. 
     250 * @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param. 
    249251 * 
    250252 * @param int|object $term If integer, will get from database. If object will apply filters and return $term. 
    251253 * @param string $taxonomy Taxonomy name that $term is part of. 
    252254 * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N 
    253  * @param string $filter {@internal Missing Description}} 
     255 * @param string $filter Optional, default is raw or no WordPress defined filter will applied. 
    254256 * @return mixed|null|WP_Error Term Row from database. Will return null if $term is empty. If taxonomy does not 
    255257 * exist then WP_Error will be returned. 
    256258 */ 
     
    305307 * @since 2.3 
    306308 * 
    307309 * @uses $wpdb 
     310 * @uses sanitize_term() Cleanses the term based on $filter context before returning. 
     311 * @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param. 
    308312 * 
    309313 * @param string $field Either 'slug', 'name', or 'id' 
    310314 * @param string|int $value Search for this term value 
    311315 * @param string $taxonomy Taxonomy Name 
    312316 * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N 
    313  * @param string $filter {@internal Missing Description}} 
     317 * @param string $filter Optional, default is raw or no WordPress defined filter will applied. 
    314318 * @return mixed Term Row from database. Will return false if $taxonomy does not exist or $term was not found. 
    315319 */ 
    316320function get_term_by($field, $value, $taxonomy, $output = OBJECT, $filter = 'raw') { 
     
    394398 * get_term_field() - Get sanitized Term field 
    395399 *  
    396400 * Does checks for $term, based on the $taxonomy. The function is for 
    397  * contextual reasons and for simplicity of usage. @see sanitize_term_field() for 
     401 * contextual reasons and for simplicity of usage. See sanitize_term_field() for 
    398402 * more information. 
    399403 * 
    400404 * @package WordPress 
     
    406410 * @param string $field Term field to fetch 
    407411 * @param int $term Term ID 
    408412 * @param string $taxonomy Taxonomy Name 
    409  * @param string $context {@internal Missing Description}} 
     413 * @param string $context Optional, default is display. Look at sanitize_term_field() for available options. 
    410414 * @return mixed Will return an empty string if $term is not an object or if $field is not set in $term. 
    411415 */ 
    412416function get_term_field( $field, $term, $taxonomy, $context = 'display' ) { 
     
    427431/** 
    428432 * get_term_to_edit() - Sanitizes Term for editing 
    429433 * 
    430  * Return value is @see sanitize_term() and usage is for sanitizing the term 
     434 * Return value is sanitize_term() and usage is for sanitizing the term 
    431435 * for editing. Function is for contextual and simplicity. 
    432436 *  
    433437 * @package WordPress 
     
    495499 * @uses $wpdb 
    496500 * @uses wp_parse_args() Merges the defaults with those defined by $args and allows for strings. 
    497501 * 
     502 * 
    498503 * @param string|array Taxonomy name or list of Taxonomy names 
    499504 * @param string|array $args The values of what to search for when returning terms 
    500505 * @return array|WP_Error List of Term Objects and their children. Will return WP_Error, if any of $taxonomies do not exist. 
     
    716721/** 
    717722 * sanitize_term() - Sanitize Term all fields 
    718723 * 
    719  * Relys on @see sanitize_term_field() to sanitize the term. The difference 
     724 * Relys on sanitize_term_field() to sanitize the term. The difference 
    720725 * is that this function will sanitize <strong>all</strong> fields. The context 
    721  * is based on @see sanitize_term_field(). 
     726 * is based on sanitize_term_field(). 
    722727 * 
    723728 * The $term is expected to be either an array or an object. 
    724729 * 
     
    755760} 
    756761 
    757762/** 
    758  * sanitize_term_field() - {@internal Missing Short Description}} 
     763 * sanitize_term_field() - Cleanse the field value in the term based on the context 
    759764 * 
    760  * {@internal Missing Long Description}} 
     765 * Passing a term field value through the function should be assumed to have cleansed 
     766 * the value for whatever context the term field is going to be used. 
    761767 * 
     768 * If no context or an unsupported context is given, then default filters will be applied. 
     769 * 
     770 * There are enough filters for each context to support a custom filtering without creating 
     771 * your own filter function. Simply create a function that hooks into the filter you need. 
     772 * 
    762773 * @package WordPress 
    763774 * @subpackage Taxonomy 
    764775 * @since 2.3 
     
    843854} 
    844855 
    845856/** 
    846  * wp_delete_object_term_relationships() - {@internal Missing Short Description}} 
     857 * wp_delete_object_term_relationships() - Will unlink the term from the taxonomy 
    847858 * 
    848  * {@internal Missing Long Description}} 
     859 * Will remove the term's relationship to the taxonomy, not the term or taxonomy itself. 
     860 * The term and taxonomy will still exist. Will require the term's object ID to perform 
     861 * the operation. 
    849862 * 
    850863 * @package WordPress 
    851864 * @subpackage Taxonomy 
     
    874887/** 
    875888 * wp_delete_term() - Removes a term from the database. 
    876889 * 
    877  * {@internal Missing Long Description}} 
     890 * If the term is a parent of other terms, then the children will be updated 
     891 * to that term's parent. 
    878892 * 
     893 * The $args 'default' will only override the terms found, if there is only one 
     894 * term found. Any other and the found terms are used. 
     895 * 
    879896 * @package WordPress 
    880897 * @subpackage Taxonomy 
    881898 * @since 2.3 
     899 * 
    882900 * @uses $wpdb 
     901 * @uses do_action() Calls both 'delete_term' and 'delete_$taxonomy' action hooks, 
     902 *      passing term object, term id. 'delete_term' gets an additional parameter with 
     903 *      the $taxonomy parameter. 
    883904 * 
    884905 * @param int $term Term ID 
    885906 * @param string $taxonomy Taxonomy Name 
    886  * @param array|string $args Change Default 
    887  * @return bool Returns false if not term; true if completes delete action. 
     907 * @param array|string $args Optional. Change 'default' term id and override found term ids. 
     908 * @return bool|WP_Error Returns false if not term; true if completes delete action. 
    888909 */ 
    889910function wp_delete_term( $term, $taxonomy, $args = array() ) { 
    890911        global $wpdb; 
     
    945966} 
    946967 
    947968/** 
    948  * wp_get_object_terms() - Returns the terms associated with the given object(s), in the supplied taxonomies. 
     969 * wp_get_object_terms() - Retrieves the terms associated with the given object(s), in the supplied taxonomies. 
    949970 * 
    950  * {@internal Missing Long Description}} 
     971 * The following information has to do the $args parameter and for what can be contained in the string 
     972 * or array of that parameter, if it exists. 
    951973 * 
     974 * The first argument is called, 'orderby' and has the default value of 'name'. The other value that is 
     975 * supported is 'count'. 
     976 * 
     977 * The second argument is called, 'order' and has the default value of 'ASC'. The only other value that 
     978 * will be acceptable is 'DESC'. 
     979 * 
     980 * The final argument supported is called, 'fields' and has the default value of 'all'. There are 
     981 * multiple other options that can be used instead. Supported values are as follows: 'all', 'ids', 
     982 * 'names', and finally 'all_with_object_id'. 
     983 * 
     984 * The fields argument also decides what will be returned. If 'all' or 'all_with_object_id' is choosen or 
     985 * the default kept intact, then all matching terms objects will be returned. If either 'ids' or 'names' 
     986 * is used, then an array of all matching term ids or term names will be returned respectively. 
     987 * 
    952988 * @package WordPress 
    953989 * @subpackage Taxonomy 
    954990 * @since 2.3 
    955991 * @uses $wpdb 
    956992 * 
    957  * @param int|array $object_id The id of the object(s)) to retrieve. 
     993 * @param int|array $object_id The id of the object(s) to retrieve. 
    958994 * @param string|array $taxonomies The taxonomies to retrieve terms from. 
    959995 * @param array|string $args Change what is returned 
    960996 * @return array|WP_Error The requested term data or empty array if no terms found. WP_Error if $taxonomy does not exist. 
     
    10151051/** 
    10161052 * wp_insert_term() - Adds a new term to the database. Optionally marks it as an alias of an existing term. 
    10171053 * 
    1018  * {@internal Missing Long Description}} 
     1054 * Error handling is assigned for the nonexistance of the $taxonomy and $term parameters before inserting. 
     1055 * If both the term id and taxonomy exist previously, then an array will be returned that contains the term 
     1056 * id and the contents of what is returned. The keys of the array are 'term_id' and 'term_taxonomy_id' containing 
     1057 * numeric values. 
    10191058 * 
     1059 * It is assumed that the term does not yet exist or the above will apply. The term will be first added to the term 
     1060 * table and then related to the taxonomy if everything is well. If everything is correct, then several actions 
     1061 * will be run prior to a filter and then several actions will be run after the filter is run. 
     1062 * 
     1063 * The arguments decide how the term is handled based on the $args parameter. The following 
     1064 * is a list of the available overrides and the defaults. 
     1065 * 
     1066 * 'alias_of'. There is no default, but if added, expected is the slug that the term will be an alias of. 
     1067 * Expected to be a string. 
     1068 * 
     1069 * 'description'. There is no default. If exists, will be added to the database along with the term. Expected 
     1070 * to be a string. 
     1071 * 
     1072 * 'parent'. Expected to be numeric and default is 0 (zero). Will assign value of 'parent' to the term. 
     1073 * 
     1074 * 'slug'. Expected to be a string. There is no default. 
     1075 * 
     1076 * If 'slug' argument exists then the slug will be checked to see if it is not a valid term. If that check 
     1077 * succeeds (it is not a valid term), then it is added and the term id is given. If it fails, then a check 
     1078 * is made to whether the taxonomy is hierarchical and the parent argument is not empty. If the second check 
     1079 * succeeds, the term will be inserted and the term id will be given. 
     1080 * 
    10201081 * @package WordPress 
    10211082 * @subpackage Taxonomy 
    10221083 * @since 2.3 
    10231084 * @uses $wpdb 
    10241085 * 
     1086 * @uses do_action() Calls 'create_term' hook with the term id and taxonomy id as parameters. 
     1087 * @uses do_action() Calls 'create_$taxonomy' hook with term id and taxonomy id as parameters. 
     1088 * @uses apply_filters() Calls 'term_id_filter' hook with term id and taxonomy id as parameters. 
     1089 * @uses do_action() Calls 'created_term' hook with the term id and taxonomy id as parameters. 
     1090 * @uses do_action() Calls 'created_$taxonomy' hook with term id and taxonomy id as parameters. 
     1091 * 
    10251092 * @param int|string $term The term to add or update. 
    10261093 * @param string $taxonomy The taxonomy to which to add the term 
    10271094 * @param array|string $args Change the values of the inserted term 
     
    11011168} 
    11021169 
    11031170/** 
    1104  * wp_set_object_terms() - {@internal Missing Short Description}} 
     1171 * wp_set_object_terms() - Create Term and Taxonomy Relationships 
    11051172 *  
    1106  * Relates an object (post, link etc) to a term and taxonomy type.  Creates the term and taxonomy 
    1107  * relationship if it doesn't already exist.  Creates a term if it doesn't exist (using the slug). 
     1173 * Relates an object (post, link etc) to a term and taxonomy type. Creates the term and taxonomy 
     1174 * relationship if it doesn't already exist. Creates a term if it doesn't exist (using the slug). 
    11081175 * 
     1176 * A relationship means that the term is grouped in or belongs to the taxonomy. A term has no 
     1177 * meaning until it is given context by defining which taxonomy it exists under. 
     1178 * 
    11091179 * @package WordPress 
    11101180 * @subpackage Taxonomy 
    11111181 * @since 2.3 
     
    12241294} 
    12251295 
    12261296/** 
    1227  * wp_update_term() - {@internal Missing Short Description}} 
     1297 * wp_update_term() - Update term based on arguments provided 
    12281298 * 
    1229  * {@internal Missing Long Description}} 
     1299 * The $args will indiscriminately override all values with the same field name. Care 
     1300 * must be taken to not override important information need to update or update will 
     1301 * fail (or perhaps create a new term, neither would be acceptable). 
    12301302 * 
     1303 * Defaults will set 'alias_of', 'description', 'parent', and 'slug' if not defined 
     1304 * in $args already. 
     1305 * 
     1306 * 'alias_of' will create a term group, if it doesn't already exist, and update it for 
     1307 * the $term. 
     1308 * 
     1309 * If the 'slug' argument in $args is missing, then the 'name' in $args will be used. 
     1310 * It should also be noted that if you set 'slug' and it isn't unique then a WP_Error 
     1311 * will be passed back. If you don't pass any slug, then a unique one will be created 
     1312 * for you. 
     1313 * 
     1314 * For what can be overrode in $args, check the term scheme can contain and stay away 
     1315 * from the term keys. 
     1316 * 
    12311317 * @package WordPress 
    12321318 * @subpackage Taxonomy 
    12331319 * @since 2.3 
     1320 * 
    12341321 * @uses $wpdb 
     1322 * @uses do_action() Will call both 'edit_term' and 'edit_$taxonomy' twice. 
     1323 * @uses apply_filters() Will call the 'term_id_filter' filter and pass the term id and 
     1324 *      taxonomy id. 
    12351325 * 
    12361326 * @param int $term The ID of the term 
    12371327 * @param string $taxonomy The context in which to relate the term to the object. 
    1238  * @param array|string $args Overwrite defaults 
    1239  * @return array Returns Term ID and Taxonomy Term ID 
     1328 * @param array|string $args Overwrite term field values 
     1329 * @return array|WP_Error Returns Term ID and Taxonomy Term ID 
    12401330 */ 
    12411331function wp_update_term( $term, $taxonomy, $args = array() ) { 
    12421332        global $wpdb; 
     
    13671457// 
    13681458 
    13691459/** 
    1370  * clean_object_term_cache() - {@internal Missing Short Description}} 
     1460 * clean_object_term_cache() - Removes the taxonomy relationship to terms from the cache. 
    13711461 * 
    1372  * {@internal Missing Long Description}} 
     1462 * Will remove the entire taxonomy relationship containing term $object_id. The term IDs 
     1463 * have to exist within the taxonomy $object_type for the deletion to take place. 
    13731464 * 
    13741465 * @package WordPress 
    13751466 * @subpackage Taxonomy 
    13761467 * @since 2.3 
    13771468 * 
    13781469 * @see get_object_taxonomies() for more on $object_type 
     1470 * @uses do_action() Will call action hook named, 'clean_object_term_cache' after completion. 
     1471 *      Passes, function params in same order. 
    13791472 * 
    1380  * @param int|array $object_ids {@internal Missing Description}} 
    1381  * @param string $object_type {@internal Missing Description}} 
     1473 * @param int|array $object_ids Single or list of term object ID(s) 
     1474 * @param string $object_type The taxonomy object type 
    13821475 */ 
    13831476function clean_object_term_cache($object_ids, $object_type) { 
    13841477        if ( !is_array($object_ids) ) 
     
    13921485} 
    13931486 
    13941487/** 
    1395  * clean_term_cache() - {@internal Missing Short Description}} 
     1488 * clean_term_cache() - Will remove all of the term ids from the cache 
    13961489 * 
    1397  * {@internal Missing Long Description}} 
    1398  * 
    13991490 * @package WordPress 
    14001491 * @subpackage Taxonomy 
    14011492 * @since 2.3 
    14021493 * @uses $wpdb 
    14031494 * 
    1404  * @param int|array $ids {@internal Missing Description}} 
     1495 * @param int|array $ids Single or list of Term IDs 
    14051496 * @param string $taxonomy Can be empty and will assume tt_ids, else will use for context. 
    14061497 */ 
    14071498function clean_term_cache($ids, $taxonomy = '') { 
     
    14391530} 
    14401531 
    14411532/** 
    1442  * get_object_term_cache() - {@internal Missing Short Description}} 
     1533 * get_object_term_cache() - Retrieves the taxonomy relationship to the term object id. 
    14431534 * 
    1444  * {@internal Missing Long Description}} 
    1445  * 
    14461535 * @package WordPress 
    14471536 * @subpackage Taxonomy 
    14481537 * @since 2.3 
    14491538 * 
    1450  * @param int|array $ids {@internal Missing Description}} 
    1451  * @param string $taxonomy {@internal Missing Description}} 
     1539 * @uses wp_cache_get() Retrieves taxonomy relationship from cache 
     1540 * 
     1541 * @param int|array $id Term object ID 
     1542 * @param string $taxonomy Taxonomy Name 
    14521543 * @return bool|array Empty array if $terms found, but not $taxonomy. False if nothing is in cache for $taxonomy and $id. 
    14531544 */ 
    14541545function &get_object_term_cache($id, $taxonomy) { 
     
    14561547} 
    14571548 
    14581549/** 
    1459  * get_object_term_cache() - {@internal Missing Short Description}} 
     1550 * update_object_term_cache() - Updates the cache for Term ID(s) 
    14601551 * 
    1461  * {@internal Missing Long Description}} 
     1552 * Will only update the cache for terms not already cached. 
    14621553 * 
     1554 * The $object_ids expects that the ids be separated by commas, if it is 
     1555 * a string. 
     1556 * 
     1557 * It should be noted that update_object_term_cache() is very time extensive. 
     1558 * It is advised that the function is not called very often or at least not  
     1559 * for a lot of terms that exist in a lot of taxonomies. The amount of time 
     1560 * increases for each term and it also increases for each taxonomy the term 
     1561 * belongs to. 
     1562 * 
    14631563 * @package WordPress 
    14641564 * @subpackage Taxonomy 
    14651565 * @since 2.3 
    1466  * @uses $wpdb 
     1566 * @uses wp_get_object_terms() Used to get terms from the database to update 
    14671567 * 
    1468  * @param string|array $object_ids {@internal Missing Description}} 
    1469  * @param string $object_type {@internal Missing Description}} 
    1470  * @return null|array Null value is given with empty $object_ids. 
     1568 * @param string|array $object_ids Single or list of term object ID(s) 
     1569 * @param string $object_type The taxonomy object type 
     1570 * @return null|bool Null value is given with empty $object_ids. False if  
    14711571 */ 
    14721572function update_object_term_cache($object_ids, $object_type) { 
    14731573        if ( empty($object_ids) ) 
     
    15431643/** 
    15441644 * _get_term_hierarchy() - Retrieves children of taxonomy 
    15451645 * 
    1546  * {@internal Missing Long Description}} 
    1547  * 
    15481646 * @package WordPress 
    15491647 * @subpackage Taxonomy 
    15501648 * @access private 
    15511649 * @since 2.3 
    15521650 * 
    1553  * @param string $taxonomy {@internal Missing Description}} 
     1651 * @uses update_option() Stores all of the children in "$taxonomy_children" option. 
     1652 *      That is the name of the taxonomy, immediately followed by '_children'. 
     1653 * 
     1654 * @param string $taxonomy Taxonomy Name 
    15541655 * @return array Empty if $taxonomy isn't hierarachical or returns children. 
    15551656 */ 
    15561657function _get_term_hierarchy($taxonomy) { 
     
    17111812        } 
    17121813} 
    17131814 
    1714 ?> 
     1815?> 
     1816 No newline at end of file