WordPress.org

Make WordPress Core

Changeset 6378


Ignore:
Timestamp:
12/14/2007 12:25:39 AM (10 years ago)
Author:
ryan
Message:

Taxonomy phpdoc from darkdragon. fixes #4742

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/taxonomy.php

    r6376 r6378  
    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
     
    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.
     
    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'
     
    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 */
     
    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 *
     
    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 */
     
    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 *
     
    495499 * @uses $wpdb
    496500 * @uses wp_parse_args() Merges the defaults with those defined by $args and allows for strings.
     501 *
    497502 *
    498503 * @param string|array Taxonomy name or list of Taxonomy names
     
    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.
     
    756761
    757762/**
    758  * sanitize_term_field() - {@internal Missing Short Description}}
    759  *
    760  * {@internal Missing Long Description}}
     763 * sanitize_term_field() - Cleanse the field value in the term based on the context
     764 *
     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.
     767 *
     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.
    761772 *
    762773 * @package WordPress
     
    844855
    845856/**
    846  * wp_delete_object_term_relationships() - {@internal Missing Short Description}}
    847  *
    848  * {@internal Missing Long Description}}
     857 * wp_delete_object_term_relationships() - Will unlink the term from the taxonomy
     858 *
     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
     
    875888 * wp_delete_term() - Removes a term from the database.
    876889 *
    877  * {@internal Missing Long Description}}
    878  *
    879  * @package WordPress
    880  * @subpackage Taxonomy
    881  * @since 2.3
     890 * If the term is a parent of other terms, then the children will be updated
     891 * to that term's parent.
     892 *
     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 *
     896 * @package WordPress
     897 * @subpackage Taxonomy
     898 * @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() ) {
     
    946967
    947968/**
    948  * wp_get_object_terms() - Returns the terms associated with the given object(s), in the supplied taxonomies.
    949  *
    950  * {@internal Missing Long Description}}
     969 * wp_get_object_terms() - Retrieves the terms associated with the given object(s), in the supplied taxonomies.
     970 *
     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.
     973 *
     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.
    951987 *
    952988 * @package WordPress
     
    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
     
    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.
     1058 *
     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.
    10191080 *
    10201081 * @package WordPress
     
    10221083 * @since 2.3
    10231084 * @uses $wpdb
     1085 *
     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.
    10241091 *
    10251092 * @param int|string $term The term to add or update.
     
    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).
     1175 *
     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.
    11081178 *
    11091179 * @package WordPress
     
    12251295
    12261296/**
    1227  * wp_update_term() - {@internal Missing Short Description}}
    1228  *
    1229  * {@internal Missing Long Description}}
    1230  *
    1231  * @package WordPress
    1232  * @subpackage Taxonomy
    1233  * @since 2.3
     1297 * wp_update_term() - Update term based on arguments provided
     1298 *
     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).
     1302 *
     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 *
     1317 * @package WordPress
     1318 * @subpackage Taxonomy
     1319 * @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() ) {
     
    14031493
    14041494/**
    1405  * clean_object_term_cache() - {@internal Missing Short Description}}
    1406  *
    1407  * {@internal Missing Long Description}}
     1495 * clean_object_term_cache() - Removes the taxonomy relationship to terms from the cache.
     1496 *
     1497 * Will remove the entire taxonomy relationship containing term $object_id. The term IDs
     1498 * have to exist within the taxonomy $object_type for the deletion to take place.
    14081499 *
    14091500 * @package WordPress
     
    14121503 *
    14131504 * @see get_object_taxonomies() for more on $object_type
    1414  *
    1415  * @param int|array $object_ids {@internal Missing Description}}
    1416  * @param string $object_type {@internal Missing Description}}
     1505 * @uses do_action() Will call action hook named, 'clean_object_term_cache' after completion.
     1506 *  Passes, function params in same order.
     1507 *
     1508 * @param int|array $object_ids Single or list of term object ID(s)
     1509 * @param string $object_type The taxonomy object type
    14171510 */
    14181511function clean_object_term_cache($object_ids, $object_type) {
     
    14281521
    14291522/**
    1430  * clean_term_cache() - {@internal Missing Short Description}}
    1431  *
    1432  * {@internal Missing Long Description}}
     1523 * clean_term_cache() - Will remove all of the term ids from the cache
    14331524 *
    14341525 * @package WordPress
     
    14371528 * @uses $wpdb
    14381529 *
    1439  * @param int|array $ids {@internal Missing Description}}
     1530 * @param int|array $ids Single or list of Term IDs
    14401531 * @param string $taxonomy Can be empty and will assume tt_ids, else will use for context.
    14411532 */
     
    14751566
    14761567/**
    1477  * get_object_term_cache() - {@internal Missing Short Description}}
    1478  *
    1479  * {@internal Missing Long Description}}
    1480  *
    1481  * @package WordPress
    1482  * @subpackage Taxonomy
    1483  * @since 2.3
    1484  *
    1485  * @param int|array $ids {@internal Missing Description}}
    1486  * @param string $taxonomy {@internal Missing Description}}
     1568 * get_object_term_cache() - Retrieves the taxonomy relationship to the term object id.
     1569 *
     1570 * @package WordPress
     1571 * @subpackage Taxonomy
     1572 * @since 2.3
     1573 *
     1574 * @uses wp_cache_get() Retrieves taxonomy relationship from cache
     1575 *
     1576 * @param int|array $id Term object ID
     1577 * @param string $taxonomy Taxonomy Name
    14871578 * @return bool|array Empty array if $terms found, but not $taxonomy. False if nothing is in cache for $taxonomy and $id.
    14881579 */
     
    14921583
    14931584/**
    1494  * get_object_term_cache() - {@internal Missing Short Description}}
    1495  *
    1496  * {@internal Missing Long Description}}
    1497  *
    1498  * @package WordPress
    1499  * @subpackage Taxonomy
    1500  * @since 2.3
    1501  * @uses $wpdb
    1502  *
    1503  * @param string|array $object_ids {@internal Missing Description}}
    1504  * @param string $object_type {@internal Missing Description}}
    1505  * @return null|array Null value is given with empty $object_ids.
     1585 * update_object_term_cache() - Updates the cache for Term ID(s)
     1586 *
     1587 * Will only update the cache for terms not already cached.
     1588 *
     1589 * The $object_ids expects that the ids be separated by commas, if it is
     1590 * a string.
     1591 *
     1592 * It should be noted that update_object_term_cache() is very time extensive.
     1593 * It is advised that the function is not called very often or at least not
     1594 * for a lot of terms that exist in a lot of taxonomies. The amount of time
     1595 * increases for each term and it also increases for each taxonomy the term
     1596 * belongs to.
     1597 *
     1598 * @package WordPress
     1599 * @subpackage Taxonomy
     1600 * @since 2.3
     1601 * @uses wp_get_object_terms() Used to get terms from the database to update
     1602 *
     1603 * @param string|array $object_ids Single or list of term object ID(s)
     1604 * @param string $object_type The taxonomy object type
     1605 * @return null|bool Null value is given with empty $object_ids. False if
    15061606 */
    15071607function update_object_term_cache($object_ids, $object_type) {
     
    15791679 * _get_term_hierarchy() - Retrieves children of taxonomy
    15801680 *
    1581  * {@internal Missing Long Description}}
    1582  *
    15831681 * @package WordPress
    15841682 * @subpackage Taxonomy
     
    15861684 * @since 2.3
    15871685 *
    1588  * @param string $taxonomy {@internal Missing Description}}
     1686 * @uses update_option() Stores all of the children in "$taxonomy_children" option.
     1687 *  That is the name of the taxonomy, immediately followed by '_children'.
     1688 *
     1689 * @param string $taxonomy Taxonomy Name
    15891690 * @return array Empty if $taxonomy isn't hierarachical or returns children.
    15901691 */
Note: See TracChangeset for help on using the changeset viewer.