WordPress.org

Make WordPress Core

Changeset 6254


Ignore:
Timestamp:
10/15/07 22:49:31 (8 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.