WordPress.org

Make WordPress Core

Changeset 6254


Ignore:
Timestamp:
10/15/2007 10:49:31 PM (11 years ago)
Author:
ryan
Message:

More taxonomy phpdoc from darkdragon. see #4742

File:
1 edited

Legend:

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

    r6251 r6254  
    11<?php
     2/**
     3 * @package WordPress
     4 * @subpackage Taxonomy
     5 * @since 2.3
     6 */
    27
    38//
     
    611
    712/**
    8  * @global array $wp_taxonomies Fill me out please
     13 * @global array $wp_taxonomies Default Taxonomy Objects
    914 */
    1015$wp_taxonomies = array();
     
    2631 *      )</pre>
    2732 *
    28  * @package Taxonomy
     33 * @package WordPress
     34 * @subpackage Taxonomy
     35 *
    2936 * @global array $wp_taxonomies
    3037 * @param string $object_type Name of the type of taxonomy object
     
    5259 * is a taxonomy object and if it is, it will return it.
    5360 *
    54  * @package Taxonomy
     61 * @package WordPress
     62 * @subpackage Taxonomy
     63 *
    5564 * @global array $wp_taxonomies
    5665 * @param string $taxonomy Name of taxonomy object to return
     
    7281 * is_taxonomy() - Checks that the taxonomy name exists
    7382 *
    74  * @package Taxonomy
     83 * @package WordPress
     84 * @subpackage Taxonomy
     85 *
    7586 * @global array $wp_taxonomies
    7687 * @param string $taxonomy Name of taxonomy object
     
    92103 * returns the hierarchical value in the object.
    93104 *
    94  * A false return value, might also mean that the taxonomy does not exist.
    95  *
    96  * @package Taxonomy
     105 * A false return value might also mean that the taxonomy does not exist.
     106 *
     107 * @package WordPress
     108 * @subpackage Taxonomy
     109 *
    97110 * @global array $wp_taxonomies
    98111 * @param string $taxonomy Name of taxonomy object
     
    126139 *      somewhere).
    127140 *
    128  * @package Taxonomy
     141 * @package WordPress
     142 * @subpackage Taxonomy
     143 *
    129144 * @global array $wp_taxonomies
    130145 * @param string $taxonomy Name of taxonomy object
     
    165180 * be in the key named 'order'.
    166181 *
    167  * @package Taxonomy
    168  * @subpackage Term
     182 * @package WordPress
     183 * @subpackage Taxonomy
     184 * @category Term
     185 *
    169186 * @global object $wpdb Database Query
    170187 * @param string|array $terms String of term or array of string values of terms that will be used
     
    212229
    213230/**
    214  * get_term() -
    215  *
    216  *
    217  *
    218  * @package Taxonomy
    219  * @subpackage Term
     231 * get_term() - Get all Term data from database by Term ID.
     232 *
     233 * The usage of the get_term function is to apply filters to a term object.
     234 * It is possible to get a term object from the database before applying the
     235 * filters.
     236 *
     237 * $term ID must be part of $taxonomy, to get from the database. Failure, might be
     238 * able to be captured by the hooks. Failure would be the same value as $wpdb returns for the
     239 * get_row method.
     240 *
     241 * There are two hooks, one is specifically for each term, named 'get_term', and the second is
     242 * for the taxonomy name. Both hooks gets the term object, and the taxonomy name as parameters.
     243 * Both hooks are expected to return a Term object.
     244 *
     245 * @package WordPress
     246 * @subpackage Taxonomy
     247 * @category Term
     248 *
    220249 * @global object $wpdb Database Query
    221  * @param int|object $term
    222  * @param string $taxonomy
    223  * @param string $output Either OBJECT, ARRAY_A, or ARRAY_N
     250 * @param int|object $term If integer, will get from database. If object will apply filters and return $term.
     251 * @param string $taxonomy Taxonomy name that $term is part of.
     252 * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N
     253 * @param string $filter
    224254 * @return mixed Term Row from database
    225255 *
    226256 * @internal
    227  *      This won't appear but just a note to say that this is all conjecture and parts or whole
    228  *      might be inaccurate or wrong.
     257 *   This is all conjecture and might be partially or completely inaccurate.
     258 *   Uses custom hook phpdoc documentation that isn't compatible with phpDoc. Useful for a custom
     259 *   solution if used in an uniform fashion throughout the code base.
    229260 */
    230261function &get_term($term, $taxonomy, $output = OBJECT, $filter = 'raw') {
     
    250281    /**
    251282     * @internal
    252      * Filter tag is basically: filter 'type' 'hook_name' 'description'
    253283     *
    254284     * Takes two parameters the term Object and the taxonomy name. Must return term object.
    255      * @filter object get_term Used in @see get_term() as a catch-all filter for every $term
     285     * Used in @see get_term() as a catch-all filter for every $term.
     286     *
     287     * @hook-name get_term
     288     * @hook-return object
     289     * @hook-param object $_term The current term object
     290     * @hook-param string $taxonomy What taxonomy the term is in.
    256291     */
    257292    $_term = apply_filters('get_term', $_term, $taxonomy);
     293   
    258294    /**
    259295     * @internal
    260      * Filter tag is basically: filter 'type' 'hook_name' 'description'
    261296     *
    262297     * Takes two parameters the term Object and the taxonomy name. Must return term object.
    263298     * $taxonomy will be the taxonomy name, so for example, if 'category', it would be 'get_category'
    264299     * as the filter name.
     300     *
    265301     * Useful for custom taxonomies or plugging into default taxonomies.
    266      * @filter object get_$taxonomy Used in @see get_term() as specific filter for each $taxonomy.
     302     *
     303     * @hook-name get_$taxonomy
     304     * @hook-return object
     305     * @hook-param object $_term The current term object
     306     * @hook-param string $taxonomy What taxonomy the term is in.
    267307     */
    268308    $_term = apply_filters("get_$taxonomy", $_term, $taxonomy);
     
    281321
    282322/**
    283  * get_term_by() -
    284  *
    285  *
    286  *
    287  * @package Taxonomy
    288  * @subpackage Term
     323 * get_term_by() - Get all Term data from database by Term field and data.
     324 *
     325 * Warning: $value is not escaped for 'name' $field. You must do it yourself, if required.
     326 *
     327 * The default $field is 'id', therefore it is possible to also use null for field, but not
     328 * recommended that you do so.
     329 *
     330 * If $value does not exist, the return value will be false. If $taxonomy exists and $field
     331 * and $value combinations exist, the Term will be returned.
     332 *
     333 *
     334 * @package WordPress
     335 * @subpackage Taxonomy
     336 * @category Term
     337 *
    289338 * @global object $wpdb Database Query
    290  * @param string $field
    291  * @param string $value
    292  * @param string $taxonomy
    293  * @param string $output Either OBJECT, ARRAY_A, or ARRAY_N
     339 * @param string $field Either 'slug', 'name', or 'id'
     340 * @param string|int $value Search for this term value
     341 * @param string $taxonomy Taxonomy Name
     342 * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N
     343 * @param string $filter
    294344 * @return mixed Term Row from database
    295345 *
    296346 * @internal
    297  *      This won't appear but just a note to say that this is all conjecture and parts or whole
    298  *      might be inaccurate or wrong.
     347 *      This is all conjecture and might be partially or completely inaccurate.
    299348 */
    300349function get_term_by($field, $value, $taxonomy, $output = OBJECT, $filter = 'raw') {
     
    344393 * Only useful for taxonomies which are hierarchical.
    345394 *
    346  * @package Taxonomy
    347  * @subpackage Term
     395 * @package WordPress
     396 * @subpackage Taxonomy
     397 * @category Term
     398 *
    348399 * @global object $wpdb Database Query
    349400 * @param string $term Name of Term to get children
     
    380431 * more information.
    381432 *
    382  * @package Taxonomy
    383  * @subpackage Term
     433 * @package WordPress
     434 * @subpackage Taxonomy
     435 * @category Term
     436 *
    384437 * @param string $field Term field to fetch
    385438 * @param int $term Term ID
     
    412465 * for editing. Function is for contextual and simplicity.
    413466 *
    414  * @package Taxonomy
    415  * @subpackage Term
     467 * @package WordPress
     468 * @subpackage Taxonomy
     469 * @category Term
     470 *
    416471 * @param int|object $id Term ID or Object
    417472 * @param string $taxonomy Taxonomy Name
     
    438493 *
    439494 *
    440  * @package Taxonomy
    441  * @subpackage Term
     495 * @package WordPress
     496 * @subpackage Taxonomy
     497 * @category Term
     498 *
    442499 * @param string|array Taxonomy name or list of Taxonomy names
    443500 * @param string|array $args ??
     
    625682 * Returns the index of a defined term, or 0 (false) if the term doesn't exist.
    626683 *
     684 * @package WordPress
     685 * @subpackage Taxonomy
     686 * @category Term
     687 *
    627688 * @global $wpdb Database Object
    628689 * @param int|string $term The term to check
     
    658719 * The $term is expected to be either an array or an object.
    659720 *
     721 * @package WordPress
     722 * @subpackage Taxonomy
     723 * @category Term
     724 *
    660725 * @param array|object $term The term to check
    661726 * @param string $taxonomy The taxonomy name to use
     
    684749 *
    685750 *
     751 *
     752 * @package WordPress
     753 * @subpackage Taxonomy
     754 * @category Term
    686755 *
    687756 * @global object $wpdb Database Object
     
    736805 * information on parsing $args.
    737806 *
     807 * @package WordPress
     808 * @subpackage Taxonomy
     809 * @category Term
     810 *
    738811 * @global object $wpdb Database Object
    739812 * @param string $taxonomy Taxonomy name
     
    760833 *
    761834 *
     835 *
     836 * @package WordPress
     837 * @subpackage Taxonomy
     838 * @category Term
    762839 *
    763840 * @global object $wpdb Database Object
     
    782859
    783860/**
    784  * Removes a term from the database.
     861 * wp_delete_term() - Removes a term from the database.
     862 *
     863 *
     864 *
     865 * @package WordPress
     866 * @subpackage Taxonomy
     867 * @category Term
     868 *
     869 * @global object $wpdb Database Object
     870 * @param int $term Term ID
     871 * @param string $taxonomy Taxonomy Name
     872 * @param array|string $args Change Default
     873 * @param bool Returns false if not term; true if completes delete action.
    785874 */
    786875function wp_delete_term( $term, $taxonomy, $args = array() ) {
     
    840929
    841930/**
    842  * Returns the terms associated with the given object(s), in the supplied taxonomies.
     931 * wp_get_object_terms() - Returns the terms associated with the given object(s), in the supplied taxonomies.
     932 *
     933 *
     934 *
     935 * @package WordPress
     936 * @subpackage Taxonomy
     937 * @category Term
     938 *
     939 * @global $wpdb Database Object
    843940 * @param int|array $object_id The id of the object(s)) to retrieve for.
    844941 * @param string|array $taxonomies The taxonomies to retrieve terms from.
    845  * @return array The requested term data.
     942 * @param array|string $args Change what is returned
     943 * @return array The requested term data.           
    846944 */
    847945function wp_get_object_terms($object_ids, $taxonomies, $args = array()) {
     
    9021000 *
    9031001 *
     1002 *
     1003 * @package WordPress
     1004 * @subpackage Taxonomy
     1005 * @category Term
    9041006 *
    9051007 * @global $wpdb Database Object
     
    9841086 * relationship if it doesn't already exist.  Creates a term if it doesn't exist (using the slug).
    9851087 *
     1088 * @package WordPress
     1089 * @subpackage Taxonomy
     1090 * @category Term
     1091 *
    9861092 * @global $wpdb Database Object
    9871093 * @param int $object_id The object to relate to.
     
    9891095 * @param array|string $taxonomy The context in which to relate the term to the object.
    9901096 * @param bool $append If false will delete difference of terms.
     1097 * @return array Affected Term IDs
    9911098 */
    9921099function wp_set_object_terms($object_id, $terms, $taxonomy, $append = false) {
     
    10331140}
    10341141
     1142/**
     1143 * wp_unique_term_slug() - Will make @see $slug unique, if it isn't already
     1144 *
     1145 * The @see $slug has to be unique global to every taxonomy, meaning that one taxonomy
     1146 * term can't have a matching slug with another taxonomy term. Each slug has to be
     1147 * globally unique for every taxonomy.
     1148 *
     1149 * The way this works is that if the taxonomy that the term belongs to is heirarchical
     1150 * and has a parent, it will append that parent to the @see $slug.
     1151 *
     1152 * If that still doesn't return an unique slug, then it try to append a number until
     1153 * it finds a number that is truely unique.
     1154 *
     1155 * The only purpose for @see $term is for appending a parent, if one exists.
     1156 *
     1157 * @package WordPress
     1158 * @subpackage Taxonomy
     1159 * @category Term
     1160 *
     1161 * @global $wpdb Database Object
     1162 * @param string $slug The string that will be tried for a unique slug
     1163 * @param object $term The term object that the $slug will belong too
     1164 * @return string Will return a true unique slug.
     1165 */
    10351166function wp_unique_term_slug($slug, $term) {
    10361167    global $wpdb;
     
    10651196}
    10661197
     1198/**
     1199 * wp_update_term() -
     1200 *
     1201 *
     1202 *
     1203 * @package WordPress
     1204 * @subpackage Taxonomy
     1205 * @category Term
     1206 *
     1207 * @global $wpdb Database Object
     1208 * @param int $term The ID of the term
     1209 * @param string $taxonomy The context in which to relate the term to the object.
     1210 * @param array|string $args Overwrite defaults
     1211 * @return array Returns Term ID and Taxonomy Term ID
     1212 */
    10671213function wp_update_term( $term, $taxonomy, $args = array() ) {
    10681214    global $wpdb;
     
    11401286}
    11411287
     1288/**
     1289 * wp_update_term_count() - Updates the amount of terms in taxonomy
     1290 *
     1291 * If there is a taxonomy callback applyed, then it will be called for updating the count.
     1292 *
     1293 * The default action is to count what the amount of terms have the relationship of term ID.
     1294 * Once that is done, then update the database.
     1295 *
     1296 * @package WordPress
     1297 * @subpackage Taxonomy
     1298 * @category Term
     1299 *
     1300 * @global $wpdb Database Object
     1301 * @param int|array $terms The ID of the terms
     1302 * @param string $taxonomy The context of the term.
     1303 * @return bool If no terms will return false, and if successful will return true.
     1304 */
    11421305function wp_update_term_count( $terms, $taxonomy ) {
    11431306    global $wpdb;
     
    11721335//
    11731336
     1337/**
     1338 * clean_object_term_cache() -
     1339 *
     1340 *
     1341 *
     1342 * @package WordPress
     1343 * @subpackage Taxonomy
     1344 * @category Cache
     1345 *
     1346 * @global $object_term_cache
     1347 * @global $blog_id The id of the blog, in case there is more than one blog using the library.
     1348 * @param int|array $object_ids
     1349 * @param string $object_type @see get_object_taxonomies
     1350 * @return null
     1351 */
    11741352function clean_object_term_cache($object_ids, $object_type) {
    11751353    if ( !is_array($object_ids) )
     
    11821360}
    11831361
     1362/**
     1363 * clean_term_cache() -
     1364 *
     1365 *
     1366 *
     1367 * @package WordPress
     1368 * @subpackage Taxonomy
     1369 * @category Cache
     1370 *
     1371 * @global $object_term_cache
     1372 * @global $blog_id The id of the blog, in case there is more than one blog using the library.
     1373 * @param int|array $ids
     1374 * @param string $taxonomy Can be empty and will assume tt_ids, else will use for context.
     1375 * @return null
     1376 */
    11841377function clean_term_cache($ids, $taxonomy = '') {
    11851378    global $wpdb;
     
    12951488}
    12961489
     1490/**
     1491 * @access private
     1492 * _get_term_children() - Get array of child terms
     1493 *
     1494 * If $terms is an array of objects, then objects will returned from the function.
     1495 * If $terms is an array of IDs, then an array of ids of children will be returned.
     1496 *
     1497 * @package WordPress
     1498 * @subpackage Taxonomy
     1499 *
     1500 * @param int $term_id Look for this Term ID in $terms
     1501 * @param array $terms List of Term IDs
     1502 * @param string $taxonomy Term Context
     1503 * @return array
     1504 */
    12971505function &_get_term_children($term_id, $terms, $taxonomy) {
    12981506    if ( empty($terms) )
     
    13341542}
    13351543
    1336 // Recalculates term counts by including items from child terms
    1337 // Assumes all relevant children are already in the $terms argument
     1544/**
     1545 * @access private
     1546 * _pad_term_counts() - Add count of children to parent count
     1547 *
     1548 * Recalculates term counts by including items from child terms.
     1549 * Assumes all relevant children are already in the $terms argument
     1550 *
     1551 * @package WordPress
     1552 * @subpackage Taxonomy
     1553 *
     1554 * @param array $terms List of Term IDs
     1555 * @param string $taxonomy Term Context
     1556 */
    13381557function _pad_term_counts(&$terms, $taxonomy) {
    13391558    global $wpdb;
     
    13831602//
    13841603
     1604/**
     1605 * @access private
     1606 * _update_post_term_count() - Will update term count based on posts
     1607 *
     1608 * Private function for the default callback for post_tag and category taxonomies.
     1609 *
     1610 * @package WordPress
     1611 * @subpackage Taxonomy
     1612 * @category Callback
     1613 *
     1614 * @global $wpdb Database Object
     1615 * @param array $terms List of Term IDs
     1616 */
    13851617function _update_post_term_count( $terms ) {
    13861618    global $wpdb;
Note: See TracChangeset for help on using the changeset viewer.