WordPress.org

Make WordPress Core

Changeset 8164


Ignore:
Timestamp:
06/22/08 20:23:23 (6 years ago)
Author:
ryan
Message:

phpdoc updates from jacobsantos. see #7038

Location:
trunk/wp-includes
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/comment-template.php

    r7999 r8164  
    1010 
    1111/** 
    12  * get_comment_author() - Retrieve the author of the current comment 
    13  * 
    14  * If the comment has an empty comment_author field, then 'Anonymous' person 
    15  * is assumed. 
     12 * Retrieve the author of the current comment. 
     13 * 
     14 * If the comment has an empty comment_author field, then 'Anonymous' person is 
     15 * assumed. 
    1616 * 
    1717 * @since 1.5 
     
    3030 
    3131/** 
    32  * comment_author() - Displays the author of the current comment 
     32 * Displays the author of the current comment. 
    3333 * 
    3434 * @since 0.71 
     
    4141 
    4242/** 
    43  * get_comment_author_email() - Retrieve the email of the author of the current comment 
     43 * Retrieve the email of the author of the current comment. 
    4444 * 
    4545 * @since 1.5 
     
    5555 
    5656/** 
    57  * comment_author_email() - Display the email of the author of the current global $comment 
    58  * 
    59  * Care should be taken to protect the email address and assure that email harvesters 
    60  * do not capture your commentors' email address. Most assume that their email address will 
    61  * not appear in raw form on the blog. Doing so will enable anyone, including those that 
    62  * people don't want to get the email address and use it for their own means good and bad. 
     57 * Display the email of the author of the current global $comment. 
     58 * 
     59 * Care should be taken to protect the email address and assure that email 
     60 * harvesters do not capture your commentors' email address. Most assume that 
     61 * their email address will not appear in raw form on the blog. Doing so will 
     62 * enable anyone, including those that people don't want to get the email 
     63 * address and use it for their own means good and bad. 
    6364 * 
    6465 * @since 0.71 
     
    7071 
    7172/** 
    72  * comment_author_email_link() - Display the html email link to the author of the current comment 
    73  * 
    74  * Care should be taken to protect the email address and assure that email harvesters 
    75  * do not capture your commentors' email address. Most assume that their email address will 
    76  * not appear in raw form on the blog. Doing so will enable anyone, including those that 
    77  * people don't want to get the email address and use it for their own means good and bad. 
     73 * Display the html email link to the author of the current comment. 
     74 * 
     75 * Care should be taken to protect the email address and assure that email 
     76 * harvesters do not capture your commentors' email address. Most assume that 
     77 * their email address will not appear in raw form on the blog. Doing so will 
     78 * enable anyone, including those that people don't want to get the email 
     79 * address and use it for their own means good and bad. 
    7880 * 
    7981 * @since 0.71 
     
    9799 
    98100/** 
    99  * get_comment_author_link() - Retrieve the html link to the url of the author of the current comment 
     101 * Retrieve the html link to the url of the author of the current comment. 
    100102 * 
    101103 * @since 1.5 
     
    117119 
    118120/** 
    119  * comment_author_link() - Display the html link to the url of the author of the current comment 
     121 * Display the html link to the url of the author of the current comment. 
    120122 * 
    121123 * @since 0.71 
     
    127129 
    128130/** 
    129  * get_comment_author_IP() - Retrieve the IP address of the author of the current comment 
     131 * Retrieve the IP address of the author of the current comment. 
    130132 * 
    131133 * @since 1.5 
     
    141143 
    142144/** 
    143  * comment_author_IP() - Displays the IP address of the author of the current comment 
     145 * Display the IP address of the author of the current comment. 
    144146 * 
    145147 * @since 0.71 
     
    151153 
    152154/** 
    153  * get_comment_author_url() - Returns the url of the author of the current comment 
     155 * Retrieve the url of the author of the current comment. 
    154156 * 
    155157 * @since 1.5 
     
    164166 
    165167/** 
    166  * comment_author_url() - Display the url of the author of the current comment 
     168 * Display the url of the author of the current comment. 
    167169 * 
    168170 * @since 0.71 
     
    175177 
    176178/** 
    177  * get_comment_author_url_link() - Retrieves the HTML link of the url of the author of the current comment 
    178  * 
    179  * $linktext parameter is only used if the URL does not exist for the comment author. If the URL does 
    180  * exist then the URL will be used and the $linktext will be ignored. 
    181  * 
    182  * Encapsulate the HTML link between the $before and $after. So it will appear in the order of $before, 
    183  * link, and finally $after. 
     179 * Retrieves the HTML link of the url of the author of the current comment. 
     180 * 
     181 * $linktext parameter is only used if the URL does not exist for the comment 
     182 * author. If the URL does exist then the URL will be used and the $linktext 
     183 * will be ignored. 
     184 * 
     185 * Encapsulate the HTML link between the $before and $after. So it will appear 
     186 * in the order of $before, link, and finally $after. 
    184187 * 
    185188 * @since 1.5 
     
    203206 
    204207/** 
    205  * comment_author_url_link() - Displays the HTML link of the url of the author of the current comment 
     208 * Displays the HTML link of the url of the author of the current comment. 
    206209 * 
    207210 * @since 0.71 
     
    217220 
    218221/** 
    219  * get_comment_date() - Retrieve the comment date of the current comment 
     222 * Retrieve the comment date of the current comment. 
    220223 * 
    221224 * @since 1.5 
     
    236239 
    237240/** 
    238  * comment_date() - Display the comment date of the current comment 
     241 * Display the comment date of the current comment. 
    239242 * 
    240243 * @since 0.71 
     
    247250 
    248251/** 
    249  * get_comment_excerpt() - Retrieve the excerpt of the current comment 
     252 * Retrieve the excerpt of the current comment. 
    250253 * 
    251254 * Will cut each word and only output the first 20 words with '...' at the end. 
     
    279282 
    280283/** 
    281  * comment_excerpt() - Returns the excerpt of the current comment 
     284 * Display the excerpt of the current comment. 
    282285 * 
    283286 * @since 1.2 
     
    289292 
    290293/** 
    291  * get_comment_ID() - Retrieve the comment id of the current comment 
     294 * Retrieve the comment id of the current comment. 
    292295 * 
    293296 * @since 1.5 
     
    303306 
    304307/** 
    305  * comment_ID() - Displays the comment id of the current comment 
     308 * Displays the comment id of the current comment. 
    306309 * 
    307310 * @since 0.71 
     
    313316 
    314317/** 
    315  * get_comment_link() - Retrieve the link to the current comment 
     318 * Retrieve the link to the current comment. 
    316319 * 
    317320 * @since 1.5 
     
    326329 
    327330/** 
    328  * get_comments_link() - Retrieves the link to the current post comments 
     331 * Retrieves the link to the current post comments. 
    329332 * 
    330333 * @since 1.5 
     
    337340 
    338341/** 
    339  * comments_link() - Displays the link to the current post comments 
     342 * Displays the link to the current post comments. 
    340343 * 
    341344 * @since 0.71 
     
    349352 
    350353/** 
    351  * get_comments_number() - Retrieve the amount of comments a post has 
     354 * Retrieve the amount of comments a post has. 
    352355 * 
    353356 * @since 1.5 
     
    374377 
    375378/** 
    376  * comments_number() - Display the language string for the number of comments the current post has 
     379 * Display the language string for the number of comments the current post has. 
    377380 * 
    378381 * @since 0.71 
     
    400403 
    401404/** 
    402  * get_comment_text() - Retrieve the text of the current comment 
     405 * Retrieve the text of the current comment. 
    403406 * 
    404407 * @since 1.5 
     
    413416 
    414417/** 
    415  * comment_text() - Displays the text of the current comment 
     418 * Displays the text of the current comment. 
    416419 * 
    417420 * @since 0.71 
     
    424427 
    425428/** 
    426  * get_comment_time() - Retrieve the comment time of the current comment 
     429 * Retrieve the comment time of the current comment. 
    427430 * 
    428431 * @since 1.5 
     
    445448 
    446449/** 
    447  * comment_time() - Display the comment time of the current comment 
     450 * Display the comment time of the current comment. 
    448451 * 
    449452 * @since 0.71 
     
    456459 
    457460/** 
    458  * get_comment_type() - Retrieve the comment type of the current comment 
     461 * Retrieve the comment type of the current comment. 
    459462 * 
    460463 * @since 1.5 
     
    474477 
    475478/** 
    476  * comment_type() - Display the comment type of the current comment 
     479 * Display the comment type of the current comment. 
    477480 * 
    478481 * @since 0.71 
     
    497500 
    498501/** 
    499  * get_trackback_url() - Retrieve The current post's trackback URL 
    500  * 
    501  * There is a check to see if permalink's have been enabled and if so, will retrieve 
    502  * the pretty path. If permalinks weren't enabled, the ID of the current post is used 
    503  * and appended to the correct page to go to. 
     502 * Retrieve The current post's trackback URL. 
     503 * 
     504 * There is a check to see if permalink's have been enabled and if so, will 
     505 * retrieve the pretty path. If permalinks weren't enabled, the ID of the 
     506 * current post is used and appended to the correct page to go to. 
    504507 * 
    505508 * @since 1.5 
     
    520523 
    521524/** 
    522  * trackback_url() - Displays the current post's trackback URL 
     525 * Displays the current post's trackback URL. 
    523526 * 
    524527 * @since 0.71 
     
    534537 
    535538/** 
    536  * trackback_rdf() - Generates and displays the RDF for the trackback information of current post 
     539 * Generates and displays the RDF for the trackback information of current post. 
    537540 * 
    538541 * @since 0.71 
     
    558561 
    559562/** 
    560  * comments_open() - Whether the current post is open for comments 
     563 * Whether the current post is open for comments. 
    561564 * 
    562565 * @since 1.5 
     
    575578 
    576579/** 
    577  * pings_open() - Whether the current post is open for pings 
     580 * Whether the current post is open for pings. 
    578581 * 
    579582 * @since 1.5 
     
    592595 
    593596/** 
    594  * wp_comment_form_unfiltered_html_nonce() - Displays form token for unfiltered comments 
    595  * 
    596  * Will only display nonce token if the current user has permissions for unfiltered html. 
    597  * Won't display the token for other users. 
    598  * 
    599  * The function was backported to 2.0.10 and was added to versions 2.1.3 and above. Does not 
    600  * exist in versions prior to 2.0.10 in the 2.0 branch and in the 2.1 branch, prior to 2.1.3. 
    601  * Technically added in 2.2.0. 
     597 * Displays form token for unfiltered comments. 
     598 * 
     599 * Will only display nonce token if the current user has permissions for 
     600 * unfiltered html. Won't display the token for other users. 
     601 * 
     602 * The function was backported to 2.0.10 and was added to versions 2.1.3 and 
     603 * above. Does not exist in versions prior to 2.0.10 in the 2.0 branch and in 
     604 * the 2.1 branch, prior to 2.1.3. Technically added in 2.2.0. 
    602605 * 
    603606 * @since 2.0.10 Backported to 2.0 branch 
     
    612615 
    613616/** 
    614  * comments_template() - Loads the comment template specified in $file 
    615  * 
    616  * Will not display the comments template if not on single post or page, or 
    617  * if the post does not have comments. 
     617 * Loads the comment template specified in $file. 
     618 * 
     619 * Will not display the comments template if not on single post or page, or if 
     620 * the post does not have comments. 
    618621 * 
    619622 * Uses the WordPress database object to query for the comments. The comments 
     
    670673 
    671674/** 
    672  * comments_popup_script() - Displays the JS popup script to show a comment 
     675 * Displays the JS popup script to show a comment. 
    673676 * 
    674677 * If the $file parameter is empty, then the home page is assumed. The defaults 
     
    701704 
    702705/** 
    703  * comments_popup_link() - Displays the link to the comments popup window for the current post ID. 
    704  * 
    705  * Is not meant to be displayed on single posts and pages. Should be used on the lists of posts 
     706 * Displays the link to the comments popup window for the current post ID. 
     707 * 
     708 * Is not meant to be displayed on single posts and pages. Should be used on the 
     709 * lists of posts 
    706710 * 
    707711 * @since 0.71 
  • trunk/wp-includes/pluggable.php

    r8098 r8164  
    11<?php 
    22/** 
    3  * These functions can be replaced via plugins. They are loaded after 
    4  * plugins are loaded. 
     3 * These functions can be replaced via plugins. If plugins do not redefine these 
     4 * functions, then these will be used instead. 
    55 * 
    66 * @package WordPress 
     
    99if ( !function_exists('set_current_user') ) : 
    1010/** 
    11  * set_current_user() - Populates global user information for any user 
    12  * 
    13  * Set $id to null and specify a name if you do not know a user's ID 
     11 * Changes the current user by ID or name. 
     12 * 
     13 * Set $id to null and specify a name if you do not know a user's ID. 
    1414 * 
    1515 * @since 2.0.1 
     
    2727if ( !function_exists('wp_set_current_user') ) : 
    2828/** 
    29  * wp_set_current_user() - Changes the current user by ID or name 
    30  * 
    31  * Set $id to null and specify a name if you do not know a user's ID 
    32  * 
    33  * Some WordPress functionality is based on the current user and 
    34  * not based on the signed in user. Therefore, it opens the ability 
    35  * to edit and perform actions on users who aren't signed in. 
     29 * Changes the current user by ID or name. 
     30 * 
     31 * Set $id to null and specify a name if you do not know a user's ID. 
     32 * 
     33 * Some WordPress functionality is based on the current user and not based on 
     34 * the signed in user. Therefore, it opens the ability to edit and perform 
     35 * actions on users who aren't signed in. 
    3636 * 
    3737 * @since 2.0.4 
     
    6161if ( !function_exists('wp_get_current_user') ) : 
    6262/** 
    63  * wp_get_current_user() - Retrieve the current user object 
     63 * Retrieve the current user object. 
    6464 * 
    6565 * @since 2.0.4 
     
    7878if ( !function_exists('get_currentuserinfo') ) : 
    7979/** 
    80  * get_currentuserinfo() - Populate global variables with information about the currently logged in user 
    81  * 
    82  * Will set the current user, if the current user is not set. The current 
    83  * user will be set to the logged in person. If no user is logged in, then 
    84  * it will set the current user to 0, which is invalid and won't have any 
    85  * permissions. 
     80 * Populate global variables with information about the currently logged in user. 
     81 * 
     82 * Will set the current user, if the current user is not set. The current user 
     83 * will be set to the logged in person. If no user is logged in, then it will 
     84 * set the current user to 0, which is invalid and won't have any permissions. 
    8685 * 
    8786 * @since 0.71 
     
    113112if ( !function_exists('get_userdata') ) : 
    114113/** 
    115  * get_userdata() - Retrieve user info by user ID 
     114 * Retrieve user info by user ID. 
    116115 * 
    117116 * @since 0.71 
     
    143142if ( !function_exists('update_user_cache') ) : 
    144143/** 
    145  * update_user_cache() - Updates a users cache when overridden by a plugin 
     144 * Updates a users cache when overridden by a plugin. 
    146145 * 
    147146 * Core function does nothing. 
     
    158157if ( !function_exists('get_userdatabylogin') ) : 
    159158/** 
    160  * get_userdatabylogin() - Retrieve user info by login name 
     159 * Retrieve user info by login name. 
    161160 * 
    162161 * @since 0.71 
     
    192191if ( !function_exists('get_user_by_email') ) : 
    193192/** 
    194  * get_user_by_email() - Retrieve user info by email 
     193 * Retrieve user info by email. 
    195194 * 
    196195 * @since 2.5 
     
    222221if ( !function_exists( 'wp_mail' ) ) : 
    223222/** 
    224  * wp_mail() - Function to send mail, similar to PHP's mail 
    225  * 
    226  * A true return value does not automatically mean that the 
    227  * user received the email successfully. It just only means 
    228  * that the method used was able to process the request 
    229  * without any errors. 
    230  * 
    231  * Using the two 'wp_mail_from' and 'wp_mail_from_name' hooks 
    232  * allow from creating a from address like 'Name <email@address.com>' 
    233  * when both are set. If just 'wp_mail_from' is set, then just 
    234  * the email address will be used with no name. 
    235  * 
    236  * The default content type is 'text/plain' which does not 
    237  * allow using HTML. However, you can set the content type 
    238  * of the email by using the 'wp_mail_content_type' filter. 
    239  * 
    240  * The default charset is based on the charset used on the 
    241  * blog. The charset can be set using the 'wp_mail_charset' 
    242  * filter. 
     223 * Send mail, similar to PHP's mail 
     224 * 
     225 * A true return value does not automatically mean that the user received the 
     226 * email successfully. It just only means that the method used was able to 
     227 * process the request without any errors. 
     228 * 
     229 * Using the two 'wp_mail_from' and 'wp_mail_from_name' hooks allow from 
     230 * creating a from address like 'Name <email@address.com>' when both are set. If 
     231 * just 'wp_mail_from' is set, then just the email address will be used with no 
     232 * name. 
     233 * 
     234 * The default content type is 'text/plain' which does not allow using HTML. 
     235 * However, you can set the content type of the email by using the 
     236 * 'wp_mail_content_type' filter. 
     237 * 
     238 * The default charset is based on the charset used on the blog. The charset can 
     239 * be set using the 'wp_mail_charset' filter. 
    243240 * 
    244241 * @since 1.2.1 
     
    420417 
    421418/** 
    422  * wp_authenticate() - Checks a user's login information and logs them in if it checks out 
     419 * Checks a user's login information and logs them in if it checks out. 
     420 * 
    423421 * @since 2.5 
    424422 * 
     
    460458 
    461459/** 
    462  * wp_logout() - Log the current user out 
     460 * Log the current user out. 
     461 * 
    463462 * @since 2.5 
    464  * 
    465463 */ 
    466464if ( !function_exists('wp_logout') ) : 
     
    473471if ( !function_exists('wp_validate_auth_cookie') ) : 
    474472/** 
    475  * wp_validate_auth_cookie() - Validates authentication cookie 
    476  * 
    477  * The checks include making sure that the authentication cookie 
    478  * is set and pulling in the contents (if $cookie is not used). 
    479  * 
    480  * Makes sure the cookie is not expired. Verifies the hash in 
    481  * cookie is what is should be and compares the two. 
     473 * Validates authentication cookie. 
     474 * 
     475 * The checks include making sure that the authentication cookie is set and 
     476 * pulling in the contents (if $cookie is not used). 
     477 * 
     478 * Makes sure the cookie is not expired. Verifies the hash in cookie is what is 
     479 * should be and compares the two. 
    482480 * 
    483481 * @since 2.5 
     
    534532if ( !function_exists('wp_generate_auth_cookie') ) : 
    535533/** 
    536  * wp_generate_auth_cookie() - Generate authentication cookie contents 
     534 * Generate authentication cookie contents. 
    537535 * 
    538536 * @since 2.5 
     
    559557if ( !function_exists('wp_set_auth_cookie') ) : 
    560558/** 
    561  * wp_set_auth_cookie() - Sets the authentication cookies based User ID 
    562  * 
    563  * The $remember parameter increases the time that the cookie will 
    564  * be kept. The default the cookie is kept without remembering is 
    565  * two days. When $remember is set, the cookies will be kept for 
    566  * 14 days or two weeks. 
     559 * Sets the authentication cookies based User ID. 
     560 * 
     561 * The $remember parameter increases the time that the cookie will be kept. The 
     562 * default the cookie is kept without remembering is two days. When $remember is 
     563 * set, the cookies will be kept for 14 days or two weeks. 
    567564 * 
    568565 * @since 2.5 
     
    605602if ( !function_exists('wp_clear_auth_cookie') ) : 
    606603/** 
    607  * wp_clear_auth_cookie() - Deletes all of the cookies associated with authentication 
     604 * Removes all of the cookies associated with authentication. 
    608605 * 
    609606 * @since 2.5 
     
    627624if ( !function_exists('is_user_logged_in') ) : 
    628625/** 
    629  * is_user_logged_in() - Checks if the current visitor is a logged in user 
     626 * Checks if the current visitor is a logged in user. 
    630627 * 
    631628 * @since 2.0.0 
     
    645642if ( !function_exists('auth_redirect') ) : 
    646643/** 
    647  * auth_redirect() - Checks if a user is logged in, if not it redirects them to the login page 
     644 * Checks if a user is logged in, if not it redirects them to the login page. 
    648645 * 
    649646 * @since 1.5 
     
    688685if ( !function_exists('check_admin_referer') ) : 
    689686/** 
    690  * check_admin_referer() - Makes sure that a user was referred from another admin page, to avoid security exploits 
     687 * Makes sure that a user was referred from another admin page. 
     688 * 
     689 * To avoid security exploits. 
    691690 * 
    692691 * @since 1.2.0 
     
    710709if ( !function_exists('check_ajax_referer') ) : 
    711710/** 
    712  * check_ajax_referer() - Verifies the AJAX request to prevent processing requests external of the blog. 
     711 * Verifies the AJAX request to prevent processing requests external of the blog. 
    713712 * 
    714713 * @since 2.0.4 
     
    736735if ( !function_exists('wp_redirect') ) : 
    737736/** 
    738  * wp_redirect() - Redirects to another page, with a workaround for the IIS Set-Cookie bug 
     737 * Redirects to another page, with a workaround for the IIS Set-Cookie bug. 
    739738 * 
    740739 * @link http://support.microsoft.com/kb/q176113/ 
     
    769768if ( !function_exists('wp_sanitize_redirect') ) : 
    770769/** 
    771  * wp_sanitize_redirect() - Sanitizes a URL for use in a redirect 
     770 * Sanitizes a URL for use in a redirect. 
    772771 * 
    773772 * @since 2.3 
     
    797796if ( !function_exists('wp_safe_redirect') ) : 
    798797/** 
    799  * wp_safe_redirect() - Performs a safe (local) redirect, using wp_redirect() 
     798 * Performs a safe (local) redirect, using wp_redirect(). 
    800799 * 
    801800 * Checks whether the $location is using an allowed host, if it has an absolute 
    802  * path. A plugin can therefore set or remove allowed host(s) to or from the list. 
     801 * path. A plugin can therefore set or remove allowed host(s) to or from the 
     802 * list. 
    803803 * 
    804804 * If the host is not allowed, then the redirect is to wp-admin on the siteurl 
    805  * instead. This prevents malicious redirects which redirect to another host, but 
    806  * only used in a few places. 
     805 * instead. This prevents malicious redirects which redirect to another host, 
     806 * but only used in a few places. 
    807807 * 
    808808 * @since 2.3 
     
    835835if ( ! function_exists('wp_notify_postauthor') ) : 
    836836/** 
    837  * wp_notify_postauthor() - Notify an author of a comment/trackback/pingback to one of their posts 
     837 * Notify an author of a comment/trackback/pingback to one of their posts. 
    838838 * 
    839839 * @since 1.0.0 
     
    914914if ( !function_exists('wp_notify_moderator') ) : 
    915915/** 
    916  * wp_notify_moderator() - Notifies the moderator of the blog about a new comment that is awaiting approval 
     916 * Notifies the moderator of the blog about a new comment that is awaiting approval. 
    917917 * 
    918918 * @since 1.0 
     
    983983if ( !function_exists('wp_new_user_notification') ) : 
    984984/** 
    985  * wp_new_user_notification() - Notify the blog admin of a new user, normally via email 
     985 * Notify the blog admin of a new user, normally via email. 
    986986 * 
    987987 * @since 2.0 
     
    10161016if ( !function_exists('wp_nonce_tick') ) : 
    10171017/** 
    1018  * wp_nonce_tick() - Get the time-dependent variable for nonce creation 
    1019  * 
    1020  * A nonce has a lifespan of two ticks. Nonces in their second tick may be updated, e.g. by autosave. 
     1018 * Get the time-dependent variable for nonce creation. 
     1019 * 
     1020 * A nonce has a lifespan of two ticks. Nonces in their second tick may be 
     1021 * updated, e.g. by autosave. 
    10211022 * 
    10221023 * @since 2.5 
     
    10331034if ( !function_exists('wp_verify_nonce') ) : 
    10341035/** 
    1035  * wp_verify_nonce() - Verify that correct nonce was used with time limit 
    1036  * 
    1037  * The user is given an amount of time to use the token, so therefore, since 
    1038  * the UID and $action remain the same, the independent variable is the time. 
     1036 * Verify that correct nonce was used with time limit. 
     1037 * 
     1038 * The user is given an amount of time to use the token, so therefore, since the 
     1039 * UID and $action remain the same, the independent variable is the time. 
    10391040 * 
    10401041 * @since 2.0.4 
     
    10631064if ( !function_exists('wp_create_nonce') ) : 
    10641065/** 
    1065  * wp_create_nonce() - Creates a random, one time use token 
     1066 * Creates a random, one time use token. 
    10661067 * 
    10671068 * @since 2.0.4 
     
    10821083if ( !function_exists('wp_salt') ) : 
    10831084/** 
    1084  * wp_salt() - Get salt to add to hashes to help prevent attacks 
    1085  * 
    1086  * You can set the salt by defining two areas. One is in the database and 
    1087  * the other is in your wp-config.php file. The database location is defined 
    1088  * in the option named 'secret', but most likely will not need to be changed. 
    1089  * 
    1090  * The second, located in wp-config.php, is a constant named 'SECRET_KEY', but 
    1091  * is not required. If the constant is not defined then the database constants 
    1092  * will be used, since they are most likely given to be unique. However, given 
    1093  * that the salt will be added to the password and can be seen, the constant 
    1094  * is recommended to be set manually. 
     1085 * Get salt to add to hashes to help prevent attacks. 
     1086 * 
     1087 * The secret key is located in two places: the database in case the secret key 
     1088 * isn't defined in the second place, which is in the wp-config.php file. If you 
     1089 * are going to set the secret key, then you must do so in the wp-config.php 
     1090 * file. 
     1091 * 
     1092 * The secret key in the database is randomly generated and will be appended to 
     1093 * the secret key that is in wp-config.php file in some instances. It is 
     1094 * important to have the secret key defined or changed in wp-config.php. 
     1095 * 
     1096 * If you have installed WordPress 2.5 or later, then you will have the 
     1097 * SECRET_KEY defined in the wp-config.php already. You will want to change the 
     1098 * value in it because hackers will know what it is. If you have upgraded to 
     1099 * WordPress 2.5 or later version from a version before WordPress 2.5, then you 
     1100 * should add the constant to your wp-config.php file. 
     1101 * 
     1102 * Below is an example of how the SECRET_KEY constant is defined with a value. 
     1103 * You must not copy the below example and paste into your wp-config.php. If you 
     1104 * need an example, then you can have a 
     1105 * {@link http://api.wordpress.org/secret-key/1.0/ secret key created} for you. 
    10951106 * 
    10961107 * <code> 
     
    10981109 * </code> 
    10991110 * 
    1100  * Attention: Do not use above example! 
    1101  * 
    1102  * Salting passwords helps against tools which has stored hashed values 
    1103  * of common dictionary strings. The added values makes it harder to crack 
    1104  * if given salt string is not weak. 
    1105  * 
    1106  * Salting only helps if the string is not predictable and should be 
    1107  * made up of various characters. Think of the salt as a password for 
    1108  * securing your passwords, but common among all of your passwords. 
    1109  * Therefore the salt should be as long as possible as as difficult as 
    1110  * possible, because you will not have to remember it. 
     1111 * Salting passwords helps against tools which has stored hashed values of 
     1112 * common dictionary strings. The added values makes it harder to crack if given 
     1113 * salt string is not weak. 
    11111114 * 
    11121115 * @since 2.5 
     1116 * @link http://api.wordpress.org/secret-key/1.0/ Create a Secret Key for wp-config.php 
    11131117 * 
    11141118 * @return string Salt value from either 'SECRET_KEY' or 'secret' option 
     
    11691173if ( !function_exists('wp_hash') ) : 
    11701174/** 
    1171  * wp_hash() - Get hash of given string 
     1175 * Get hash of given string. 
    11721176 * 
    11731177 * @since 2.0.4 
     
    11861190if ( !function_exists('wp_hash_password') ) : 
    11871191/** 
    1188  * wp_hash_password() - Create a hash (encrypt) of a plain text password 
    1189  * 
    1190  * For integration with other applications, this function can be 
    1191  * overwritten to instead use the other package password checking 
    1192  * algorithm. 
     1192 * Create a hash (encrypt) of a plain text password. 
     1193 * 
     1194 * For integration with other applications, this function can be overwritten to 
     1195 * instead use the other package password checking algorithm. 
    11931196 * 
    11941197 * @since 2.5 
     
    12141217if ( !function_exists('wp_check_password') ) : 
    12151218/** 
    1216  * wp_check_password() - Checks the plaintext password against the encrypted Password 
    1217  * 
    1218  * Maintains compatibility between old version and the new cookie 
    1219  * authentication protocol using PHPass library. The $hash parameter 
    1220  * is the encrypted password and the function compares the plain text 
    1221  * password when encypted similarly against the already encrypted 
    1222  * password to see if they match. 
    1223  * 
    1224  * For integration with other applications, this function can be 
    1225  * overwritten to instead use the other package password checking 
    1226  * algorithm. 
     1219 * Checks the plaintext password against the encrypted Password. 
     1220 * 
     1221 * Maintains compatibility between old version and the new cookie authentication 
     1222 * protocol using PHPass library. The $hash parameter is the encrypted password 
     1223 * and the function compares the plain text password when encypted similarly 
     1224 * against the already encrypted password to see if they match. 
     1225 * 
     1226 * For integration with other applications, this function can be overwritten to 
     1227 * instead use the other package password checking algorithm. 
    12271228 * 
    12281229 * @since 2.5 
     
    12661267if ( !function_exists('wp_generate_password') ) : 
    12671268/** 
    1268  * wp_generate_password() - Generates a random password drawn from the defined set of characters 
     1269 * Generates a random password drawn from the defined set of characters. 
    12691270 * 
    12701271 * @since 2.5 
     
    12861287if ( !function_exists('wp_set_password') ) : 
    12871288/** 
    1288  * wp_set_password() - Updates the user's password with a new encrypted one 
    1289  * 
    1290  * For integration with other applications, this function can be 
    1291  * overwritten to instead use the other package password checking 
    1292  * algorithm. 
     1289 * Updates the user's password with a new encrypted one. 
     1290 * 
     1291 * For integration with other applications, this function can be overwritten to 
     1292 * instead use the other package password checking algorithm. 
    12931293 * 
    12941294 * @since 2.5 
     
    13111311if ( !function_exists( 'get_avatar' ) ) : 
    13121312/** 
    1313  * get_avatar() - Get avatar for a user 
    1314  * 
    1315  * Retrieve the avatar for a user provided a user ID or email address 
     1313 * Retrieve the avatar for a user who provided a user ID or email address. 
    13161314 * 
    13171315 * @since 2.5 
     
    13891387if ( !function_exists('wp_setcookie') ) : 
    13901388/** 
    1391  * wp_setcookie() - Sets a cookie for a user who just logged in 
     1389 * Sets a cookie for a user who just logged in. 
    13921390 * 
    13931391 * @since 1.5 
     
    14111409if ( !function_exists('wp_clearcookie') ) : 
    14121410/** 
    1413  * wp_clearcookie() - Clears the authentication cookie, logging the user out 
     1411 * Clears the authentication cookie, logging the user out. 
    14141412 * 
    14151413 * @since 1.5 
     
    14251423if ( !function_exists('wp_get_cookie_login') ): 
    14261424/** 
    1427  * wp_get_cookie_login() - Gets the user cookie login 
    1428  * 
    1429  * This function is deprecated and should no longer be extended as it won't 
    1430  * be used anywhere in WordPress. Also, plugins shouldn't use it either. 
     1425 * Gets the user cookie login. 
     1426 * 
     1427 * This function is deprecated and should no longer be extended as it won't be 
     1428 * used anywhere in WordPress. Also, plugins shouldn't use it either. 
    14311429 * 
    14321430 * @since 2.0.4 
     
    14431441if ( !function_exists('wp_login') ) : 
    14441442/** 
    1445  * wp_login() - Checks a users login information and logs them in if it checks out 
    1446  * 
    1447  * Use the global $error to get the reason why the login failed. 
    1448  * If the username is blank, no error will be set, so assume 
    1449  * blank username on that case. 
    1450  * 
    1451  * Plugins extending this function should also provide the global 
    1452  * $error and set what the error is, so that those checking the 
    1453  * global for why there was a failure can utilize it later. 
     1443 * Checks a users login information and logs them in if it checks out. 
     1444 * 
     1445 * Use the global $error to get the reason why the login failed. If the username 
     1446 * is blank, no error will be set, so assume blank username on that case. 
     1447 * 
     1448 * Plugins extending this function should also provide the global $error and set 
     1449 * what the error is, so that those checking the global for why there was a 
     1450 * failure can utilize it later. 
    14541451 * 
    14551452 * @since 1.2.2 
     
    14771474if ( !function_exists( 'wp_text_diff' ) ) : 
    14781475/** 
    1479  * wp_text_diff() - compares two strings and outputs a human readable HTML representation of their difference 
    1480  * 
    1481  * Basically a wrapper for man diff(1) 
    1482  * 
    1483  * Must accept an optional third parameter, $args @see wp_parse_args() 
    1484  *    (string) title: optional.  If present, titles the diff in a manner compatible with the output 
    1485  * 
    1486  * Must return the empty string if the two compared strings are found to be equivalent according to whatever metric 
     1476 * Displays a human readable HTML representation of the difference between two strings. 
     1477 * 
     1478 * The Diff is available for getting the changes between versions. The output is 
     1479 * HTML, so the primary use is for displaying the changes. If the two strings 
     1480 * are equivalent, then an empty string will be returned. 
     1481 * 
     1482 * The arguments supported and can be changed are listed below. 
     1483 * 
     1484 * 'title' : Default is an empty string. Titles the diff in a manner compatible 
     1485 *      with the output. 
     1486 * 'title_left' : Default is an empty string. Change the HTML to the left of the 
     1487 *      title. 
     1488 * 'title_right' : Default is an empty string. Change the HTML to the right of 
     1489 *      the title. 
    14871490 * 
    14881491 * @since 2.6 
     1492 * @see wp_parse_args() Used to change defaults to user defined settings. 
    14891493 * @uses Text_Diff 
    14901494 * @uses WP_Text_Diff_Renderer_Table 
     
    14921496 * @param string $left_string "old" (left) version of string 
    14931497 * @param string $right_string "new" (right) version of string 
    1494  * @param string|array $args @see wp_parse_args() 
    1495  * @return string human readable HTML of string differences.  Empty string if strings are equivalent 
     1498 * @param string|array $args Optional. Change 'title', 'title_left', and 'title_right' defaults. 
     1499 * @return string Empty string if strings are equivalent or HTML with differences. 
    14961500 */ 
    14971501function wp_text_diff( $left_string, $right_string, $args = null ) { 
  • trunk/wp-includes/taxonomy.php

    r7952 r8164  
    2121 
    2222/** 
    23  * get_object_taxonomies() - Return all of the taxonomy names that are of $object_type 
     23 * Return all of the taxonomy names that are of $object_type. 
    2424 * 
    2525 * It appears that this function can be used to find all of the names inside of 
    2626 * $wp_taxonomies global variable. 
    2727 * 
    28  * <code><?php $taxonomies = get_object_taxonomies('post'); ?></code> 
    29  * Should result in <code>Array('category', 'post_tag')</code> 
     28 * <code><?php $taxonomies = get_object_taxonomies('post'); ?></code> Should 
     29 * result in <code>Array('category', 'post_tag')</code> 
    3030 * 
    3131 * @package WordPress 
     
    5959 
    6060/** 
    61  * get_taxonomy() - Returns the taxonomy object of $taxonomy. 
     61 * Retrieves the taxonomy object of $taxonomy. 
    6262 * 
    6363 * The get_taxonomy function will first check that the parameter string given 
     
    8484 
    8585/** 
    86  * is_taxonomy() - Checks that the taxonomy name exists 
     86 * Checks that the taxonomy name exists. 
    8787 * 
    8888 * @package WordPress 
     
    102102 
    103103/** 
    104  * is_taxonomy_hierarchical() - Whether the taxonomy object is hierarchical 
    105  * 
    106  * Checks to make sure that the taxonomy is an object first. Then Gets the object, and finally 
    107  * returns the hierarchical value in the object. 
     104 * Whether the taxonomy object is hierarchical. 
     105 * 
     106 * Checks to make sure that the taxonomy is an object first. Then Gets the 
     107 * object, and finally returns the hierarchical value in the object. 
    108108 * 
    109109 * A false return value might also mean that the taxonomy does not exist. 
     
    128128 
    129129/** 
    130  * register_taxonomy() - Create or modify a taxonomy object. Do not use before init. 
    131  * 
    132  * A simple function for creating or modifying a taxonomy object based on the parameters given. 
    133  * The function will accept an array (third optional parameter), along with strings for the 
    134  * taxonomy name and another string for the object type. 
    135  * 
    136  * Nothing is returned, so expect error maybe or use is_taxonomy() to check whether taxonomy exists. 
     130 * Create or modify a taxonomy object. Do not use before init. 
     131 * 
     132 * A simple function for creating or modifying a taxonomy object based on the 
     133 * parameters given. The function will accept an array (third optional 
     134 * parameter), along with strings for the taxonomy name and another string for 
     135 * the object type. 
     136 * 
     137 * Nothing is returned, so expect error maybe or use is_taxonomy() to check 
     138 * whether taxonomy exists. 
    137139 * 
    138140 * Optional $args contents: 
    139  * hierarachical - has some defined purpose at other parts of the API and is a boolean value. 
    140  * update_count_callback - works much like a hook, in that it will be called when the count is updated. 
    141  * rewrite - false to prevent rewrite, or array('slug'=>$slug) to customize permastruct; default will use $taxonomy as slug 
    142  * query_var - false to prevent queries, or string to customize query var (?$query_var=$term); default will use $taxonomy as query var 
     141 * 
     142 * hierarachical - has some defined purpose at other parts of the API and is a 
     143 * boolean value. 
     144 * 
     145 * update_count_callback - works much like a hook, in that it will be called 
     146 * when the count is updated. 
     147 * 
     148 * rewrite - false to prevent rewrite, or array('slug'=>$slug) to customize 
     149 * permastruct; default will use $taxonomy as slug. 
     150 * 
     151 * query_var - false to prevent queries, or string to customize query var 
     152 * (?$query_var=$term); default will use $taxonomy as query var. 
    143153 * 
    144154 * @package WordPress 
     
    185195 
    186196/** 
    187  * get_objects_in_term() - Return object_ids of valid taxonomy and term 
    188  * 
    189  * The strings of $taxonomies must exist before this function will continue. On failure of finding 
    190  * a valid taxonomy, it will return an WP_Error class, kind of like Exceptions in PHP 5, except you 
    191  * can't catch them. Even so, you can still test for the WP_Error class and get the error message. 
    192  * 
    193  * The $terms aren't checked the same as $taxonomies, but still need to exist for $object_ids to 
    194  * be returned. 
    195  * 
    196  * It is possible to change the order that object_ids is returned by either using PHP sort family 
    197  * functions or using the database by using $args with either ASC or DESC array. The value should 
    198  * be in the key named 'order'. 
     197 * Retrieve object_ids of valid taxonomy and term. 
     198 * 
     199 * The strings of $taxonomies must exist before this function will continue. On 
     200 * failure of finding a valid taxonomy, it will return an WP_Error class, kind 
     201 * of like Exceptions in PHP 5, except you can't catch them. Even so, you can 
     202 * still test for the WP_Error class and get the error message. 
     203 * 
     204 * The $terms aren't checked the same as $taxonomies, but still need to exist 
     205 * for $object_ids to be returned. 
     206 * 
     207 * It is possible to change the order that object_ids is returned by either 
     208 * using PHP sort family functions or using the database by using $args with 
     209 * either ASC or DESC array. The value should be in the key named 'order'. 
    199210 * 
    200211 * @package WordPress 
     
    245256 
    246257/** 
    247  * get_term() - Get all Term data from database by Term ID. 
    248  * 
    249  * The usage of the get_term function is to apply filters to a term object. 
    250  * It is possible to get a term object from the database before applying the 
     258 * Get all Term data from database by Term ID. 
     259 * 
     260 * The usage of the get_term function is to apply filters to a term object. It 
     261 * is possible to get a term object from the database before applying the 
    251262 * filters. 
    252263 * 
    253  * $term ID must be part of $taxonomy, to get from the database. Failure, might be 
    254  * able to be captured by the hooks. Failure would be the same value as $wpdb returns for the 
    255  * get_row method. 
    256  * 
    257  * There are two hooks, one is specifically for each term, named 'get_term', and the second is 
    258  * for the taxonomy name, 'term_$taxonomy'. Both hooks gets the term object, and the taxonomy 
    259  * name as parameters. Both hooks are expected to return a Term object. 
    260  * 
    261  * 'get_term' hook - Takes two parameters the term Object and the taxonomy name. Must return 
    262  * term object. Used in get_term() as a catch-all filter for every $term. 
    263  * 
    264  * 'get_$taxonomy' hook - Takes two parameters the term Object and the taxonomy name. Must return 
    265  * term object. $taxonomy will be the taxonomy name, so for example, if 'category', it would be 
    266  * 'get_category' as the filter name. Useful for custom taxonomies or plugging into default taxonomies. 
     264 * $term ID must be part of $taxonomy, to get from the database. Failure, might 
     265 * be able to be captured by the hooks. Failure would be the same value as $wpdb 
     266 * returns for the get_row method. 
     267 * 
     268 * There are two hooks, one is specifically for each term, named 'get_term', and 
     269 * the second is for the taxonomy name, 'term_$taxonomy'. Both hooks gets the 
     270 * term object, and the taxonomy name as parameters. Both hooks are expected to 
     271 * return a Term object. 
     272 * 
     273 * 'get_term' hook - Takes two parameters the term Object and the taxonomy name. 
     274 * Must return term object. Used in get_term() as a catch-all filter for every 
     275 * $term. 
     276 * 
     277 * 'get_$taxonomy' hook - Takes two parameters the term Object and the taxonomy 
     278 * name. Must return term object. $taxonomy will be the taxonomy name, so for 
     279 * example, if 'category', it would be 'get_category' as the filter name. Useful 
     280 * for custom taxonomies or plugging into default taxonomies. 
    267281 * 
    268282 * @package WordPress 
     
    317331 
    318332/** 
    319  * get_term_by() - Get all Term data from database by Term field and data. 
    320  * 
    321  * Warning: $value is not escaped for 'name' $field. You must do it yourself, if required. 
    322  * 
    323  * The default $field is 'id', therefore it is possible to also use null for field, but not 
    324  * recommended that you do so. 
    325  * 
    326  * If $value does not exist, the return value will be false. If $taxonomy exists and $field 
    327  * and $value combinations exist, the Term will be returned. 
     333 * Get all Term data from database by Term field and data. 
     334 * 
     335 * Warning: $value is not escaped for 'name' $field. You must do it yourself, if 
     336 * required. 
     337 * 
     338 * The default $field is 'id', therefore it is possible to also use null for 
     339 * field, but not recommended that you do so. 
     340 * 
     341 * If $value does not exist, the return value will be false. If $taxonomy exists 
     342 * and $field and $value combinations exist, the Term will be returned. 
    328343 * 
    329344 * @package WordPress 
     
    381396 
    382397/** 
    383  * get_term_children() - Merge all term children into a single array. 
    384  * 
    385  * This recursive function will merge all of the children of $term into 
    386  * the same array. Only useful for taxonomies which are hierarchical. 
     398 * Merge all term children into a single array. 
     399 * 
     400 * This recursive function will merge all of the children of $term into the same 
     401 * array. Only useful for taxonomies which are hierarchical. 
    387402 * 
    388403 * Will return an empty array if $term does not exist in $taxonomy. 
     
    420435 
    421436/** 
    422  * get_term_field() - Get sanitized Term field 
    423  * 
    424  * Does checks for $term, based on the $taxonomy. The function is for 
    425  * contextual reasons and for simplicity of usage. See sanitize_term_field() for 
    426  * more information. 
     437 * Get sanitized Term field. 
     438 * 
     439 * Does checks for $term, based on the $taxonomy. The function is for contextual 
     440 * reasons and for simplicity of usage. See sanitize_term_field() for more 
     441 * information. 
    427442 * 
    428443 * @package WordPress 
     
    454469 
    455470/** 
    456  * get_term_to_edit() - Sanitizes Term for editing 
    457  * 
    458  * Return value is sanitize_term() and usage is for sanitizing the term 
    459  * for editing. Function is for contextual and simplicity. 
     471 * Sanitizes Term for editing. 
     472 * 
     473 * Return value is sanitize_term() and usage is for sanitizing the term for 
     474 * editing. Function is for contextual and simplicity. 
    460475 * 
    461476 * @package WordPress 
     
    482497 
    483498/** 
    484  * get_terms() - Retrieve the terms in taxonomy or list of taxonomies. 
    485  * 
    486  * You can fully inject any customizations to the query before it is sent, as well as control 
    487  * the output with a filter. 
    488  * 
    489  * The 'get_terms' filter will be called when the cache has the term and will pass the found 
    490  * term along with the array of $taxonomies and array of $args. This filter is also called 
    491  * before the array of terms is passed and will pass the array of terms, along with the $taxonomies 
    492  * and $args. 
    493  * 
    494  * The 'list_terms_exclusions' filter passes the compiled exclusions along with the $args. 
     499 * Retrieve the terms in taxonomy or list of taxonomies. 
     500 * 
     501 * You can fully inject any customizations to the query before it is sent, as 
     502 * well as control the output with a filter. 
     503 * 
     504 * The 'get_terms' filter will be called when the cache has the term and will 
     505 * pass the found term along with the array of $taxonomies and array of $args. 
     506 * This filter is also called before the array of terms is passed and will pass 
     507 * the array of terms, along with the $taxonomies and $args. 
     508 * 
     509 * The 'list_terms_exclusions' filter passes the compiled exclusions along with 
     510 * the $args. 
    495511 * 
    496512 * The list that $args can contain, which will overwrite the defaults. 
    497  * orderby - Default is 'name'. Can be name, count, or nothing (will use term_id). 
     513 * 
     514 * orderby - Default is 'name'. Can be name, count, or nothing (will use 
     515 * term_id). 
     516 * 
    498517 * order - Default is ASC. Can use DESC. 
    499518 * hide_empty - Default is true. Will not return empty $terms. 
     
    503522 * name__like - Default is empty string. 
    504523 * 
    505  * The argument 'pad_counts' will count all of the children along with the $terms. 
    506  * 
    507  * The 'get' argument allows for overwriting 'hide_empty' and 'child_of', which can be done by 
    508  * setting the value to 'all', instead of its default empty string value. 
    509  * 
    510  * The 'child_of' argument will be used if you use multiple taxonomy or the first $taxonomy 
    511  * isn't hierarchical or 'parent' isn't used. The default is 0, which will be translated to 
    512  * a false value. If 'child_of' is set, then 'child_of' value will be tested against 
    513  * $taxonomy to see if 'child_of' is contained within. Will return an empty array if test 
    514  * fails. 
    515  * 
    516  * If 'parent' is set, then it will be used to test against the first taxonomy. Much like 
    517  * 'child_of'. Will return an empty array if the test fails. 
     524 * The argument 'pad_counts' will count all of the children along with the 
     525 * $terms. 
     526 * 
     527 * The 'get' argument allows for overwriting 'hide_empty' and 'child_of', which 
     528 * can be done by setting the value to 'all', instead of its default empty 
     529 * string value. 
     530 * 
     531 * The 'child_of' argument will be used if you use multiple taxonomy or the 
     532 * first $taxonomy isn't hierarchical or 'parent' isn't used. The default is 0, 
     533 * which will be translated to a false value. If 'child_of' is set, then 
     534 * 'child_of' value will be tested against $taxonomy to see if 'child_of' is 
     535 * contained within. Will return an empty array if test fails. 
     536 * 
     537 * If 'parent' is set, then it will be used to test against the first taxonomy. 
     538 * Much like 'child_of'. Will return an empty array if the test fails. 
    518539 * 
    519540 * @package WordPress 
     
    523544 * @uses $wpdb 
    524545 * @uses wp_parse_args() Merges the defaults with those defined by $args and allows for strings. 
    525  * 
    526546 * 
    527547 * @param string|array Taxonomy name or list of Taxonomy names 
     
    724744 
    725745/** 
    726  * is_term() - Check if Term exists 
     746 * Check if Term exists. 
    727747 * 
    728748 * Returns the index of a defined term, or 0 (false) if the term doesn't exist. 
     
    758778 
    759779/** 
    760  * sanitize_term() - Sanitize Term all fields 
    761  * 
    762  * Relys on sanitize_term_field() to sanitize the term. The difference 
    763  * is that this function will sanitize <strong>all</strong> fields. The context 
    764  * is based on sanitize_term_field(). 
     780 * Sanitize Term all fields. 
     781 * 
     782 * Relys on sanitize_term_field() to sanitize the term. The difference is that 
     783 * this function will sanitize <strong>all</strong> fields. The context is based 
     784 * on sanitize_term_field(). 
    765785 * 
    766786 * The $term is expected to be either an array or an object. 
     
    799819 
    800820/** 
    801  * sanitize_term_field() - Cleanse the field value in the term based on the context 
    802  * 
    803  * Passing a term field value through the function should be assumed to have cleansed 
    804  * the value for whatever context the term field is going to be used. 
    805  * 
    806  * If no context or an unsupported context is given, then default filters will be applied. 
    807  * 
    808  * There are enough filters for each context to support a custom filtering without creating 
    809  * your own filter function. Simply create a function that hooks into the filter you need. 
     821 * Cleanse the field value in the term based on the context. 
     822 * 
     823 * Passing a term field value through the function should be assumed to have 
     824 * cleansed the value for whatever context the term field is going to be used. 
     825 * 
     826 * If no context or an unsupported context is given, then default filters will 
     827 * be applied. 
     828 * 
     829 * There are enough filters for each context to support a custom filtering 
     830 * without creating your own filter function. Simply create a function that 
     831 * hooks into the filter you need. 
    810832 * 
    811833 * @package WordPress 
     
    864886 
    865887/** 
    866  * wp_count_terms() - Count how many terms are in Taxonomy 
    867  * 
    868  * Default $args is 'ignore_empty' which can be <code>'ignore_empty=true'</code> or 
    869  * <code>array('ignore_empty' => true);</code>. 
     888 * Count how many terms are in Taxonomy. 
     889 * 
     890 * Default $args is 'ignore_empty' which can be <code>'ignore_empty=true'</code> 
     891 * or <code>array('ignore_empty' => true);</code>. 
    870892 * 
    871893 * @package WordPress 
     
    895917 
    896918/** 
    897  * wp_delete_object_term_relationships() - Will unlink the term from the taxonomy 
    898  * 
    899  * Will remove the term's relationship to the taxonomy, not the term or taxonomy itself. 
    900  * The term and taxonomy will still exist. Will require the term's object ID to perform 
    901  * the operation. 
     919 * Will unlink the term from the taxonomy. 
     920 * 
     921 * Will remove the term's relationship to the taxonomy, not the term or taxonomy 
     922 * itself. The term and taxonomy will still exist. Will require the term's 
     923 * object ID to perform the operation. 
    902924 * 
    903925 * @package WordPress 
     
    926948 
    927949/** 
    928  * wp_delete_term() - Removes a term from the database. 
    929  * 
    930  * If the term is a parent of other terms, then the children will be updated 
    931  * to that term's parent. 
     950 * Removes a term from the database. 
     951 * 
     952 * If the term is a parent of other terms, then the children will be updated to 
     953 * that term's parent. 
    932954 * 
    933955 * The $args 'default' will only override the terms found, if there is only one 
     
    939961 * 
    940962 * @uses $wpdb 
    941  * @uses do_action() Calls both 'delete_term' and 'delete_$taxonomy' action hooks, 
    942  *  passing term object, term id. 'delete_term' gets an additional parameter with 
    943  *  the $taxonomy parameter. 
     963 * @uses do_action() Calls both 'delete_term' and 'delete_$taxonomy' action 
     964 *  hooks, passing term object, term id. 'delete_term' gets an additional 
     965 *  parameter with the $taxonomy parameter. 
    944966 * 
    945967 * @param int $term Term ID 
     
    10071029 
    10081030/** 
    1009  * wp_get_object_terms() - Retrieves the terms associated with the given object(s), in the supplied taxonomies. 
    1010  * 
    1011  * The following information has to do the $args parameter and for what can be contained in the string 
    1012  * or array of that parameter, if it exists. 
    1013  * 
    1014  * The first argument is called, 'orderby' and has the default value of 'name'. The other value that is 
    1015  * supported is 'count'. 
    1016  * 
    1017  * The second argument is called, 'order' and has the default value of 'ASC'. The only other value that 
    1018  * will be acceptable is 'DESC'. 
    1019  * 
    1020  * The final argument supported is called, 'fields' and has the default value of 'all'. There are 
    1021  * multiple other options that can be used instead. Supported values are as follows: 'all', 'ids', 
    1022  * 'names', and finally 'all_with_object_id'. 
    1023  * 
    1024  * The fields argument also decides what will be returned. If 'all' or 'all_with_object_id' is choosen or 
    1025  * the default kept intact, then all matching terms objects will be returned. If either 'ids' or 'names' 
    1026  * is used, then an array of all matching term ids or term names will be returned respectively. 
     1031 * Retrieves the terms associated with the given object(s), in the supplied taxonomies. 
     1032 * 
     1033 * The following information has to do the $args parameter and for what can be 
     1034 * contained in the string or array of that parameter, if it exists. 
     1035 * 
     1036 * The first argument is called, 'orderby' and has the default value of 'name'. 
     1037 * The other value that is supported is 'count'. 
     1038 * 
     1039 * The second argument is called, 'order' and has the default value of 'ASC'. 
     1040 * The only other value that will be acceptable is 'DESC'. 
     1041 * 
     1042 * The final argument supported is called, 'fields' and has the default value of 
     1043 * 'all'. There are multiple other options that can be used instead. Supported 
     1044 * values are as follows: 'all', 'ids', 'names', and finally 
     1045 * 'all_with_object_id'. 
     1046 * 
     1047 * The fields argument also decides what will be returned. If 'all' or 
     1048 * 'all_with_object_id' is choosen or the default kept intact, then all matching 
     1049 * terms objects will be returned. If either 'ids' or 'names' is used, then an 
     1050 * array of all matching term ids or term names will be returned respectively. 
    10271051 * 
    10281052 * @package WordPress 
     
    11151139 
    11161140/** 
    1117  * wp_insert_term() - Adds a new term to the database. Optionally marks it as an alias of an existing term. 
    1118  * 
    1119  * Error handling is assigned for the nonexistance of the $taxonomy and $term parameters before inserting. 
    1120  * If both the term id and taxonomy exist previously, then an array will be returned that contains the term 
    1121  * id and the contents of what is returned. The keys of the array are 'term_id' and 'term_taxonomy_id' containing 
    1122  * numeric values. 
    1123  * 
    1124  * It is assumed that the term does not yet exist or the above will apply. The term will be first added to the term 
    1125  * table and then related to the taxonomy if everything is well. If everything is correct, then several actions 
    1126  * will be run prior to a filter and then several actions will be run after the filter is run. 
    1127  * 
    1128  * The arguments decide how the term is handled based on the $args parameter. The following 
    1129  * is a list of the available overrides and the defaults. 
    1130  * 
    1131  * 'alias_of'. There is no default, but if added, expected is the slug that the term will be an alias of. 
    1132  * Expected to be a string. 
    1133  * 
    1134  * 'description'. There is no default. If exists, will be added to the database along with the term. Expected 
    1135  * to be a string. 
    1136  * 
    1137  * 'parent'. Expected to be numeric and default is 0 (zero). Will assign value of 'parent' to the term. 
     1141 * Adds a new term to the database. Optionally marks it as an alias of an existing term. 
     1142 * 
     1143 * Error handling is assigned for the nonexistance of the $taxonomy and $term 
     1144 * parameters before inserting. If both the term id and taxonomy exist 
     1145 * previously, then an array will be returned that contains the term id and the 
     1146 * contents of what is returned. The keys of the array are 'term_id' and 
     1147 * 'term_taxonomy_id' containing numeric values. 
     1148 * 
     1149 * It is assumed that the term does not yet exist or the above will apply. The 
     1150 * term will be first added to the term table and then related to the taxonomy 
     1151 * if everything is well. If everything is correct, then several actions will be 
     1152 * run prior to a filter and then several actions will be run after the filter 
     1153 * is run. 
     1154 * 
     1155 * The arguments decide how the term is handled based on the $args parameter. 
     1156 * The following is a list of the available overrides and the defaults. 
     1157 * 
     1158 * 'alias_of'. There is no default, but if added, expected is the slug that the 
     1159 * term will be an alias of. Expected to be a string. 
     1160 * 
     1161 * 'description'. There is no default. If exists, will be added to the database 
     1162 * along with the term. Expected to be a string. 
     1163 * 
     1164 * 'parent'. Expected to be numeric and default is 0 (zero). Will assign value 
     1165 * of 'parent' to the term. 
    11381166 * 
    11391167 * 'slug'. Expected to be a string. There is no default. 
    11401168 * 
    1141  * If 'slug' argument exists then the slug will be checked to see if it is not a valid term. If that check 
    1142  * succeeds (it is not a valid term), then it is added and the term id is given. If it fails, then a check 
    1143  * is made to whether the taxonomy is hierarchical and the parent argument is not empty. If the second check 
    1144  * succeeds, the term will be inserted and the term id will be given. 
     1169 * If 'slug' argument exists then the slug will be checked to see if it is not 
     1170 * a valid term. If that check succeeds (it is not a valid term), then it is 
     1171 * added and the term id is given. If it fails, then a check is made to whether 
     1172 * the taxonomy is hierarchical and the parent argument is not empty. If the 
     1173 * second check succeeds, the term will be inserted and the term id will be 
     1174 * given. 
    11451175 * 
    11461176 * @package WordPress 
     
    12361266 
    12371267/** 
    1238  * wp_set_object_terms() - Create Term and Taxonomy Relationships 
    1239  * 
    1240  * Relates an object (post, link etc) to a term and taxonomy type. Creates the term and taxonomy 
    1241  * relationship if it doesn't already exist. Creates a term if it doesn't exist (using the slug). 
    1242  * 
    1243  * A relationship means that the term is grouped in or belongs to the taxonomy. A term has no 
    1244  * meaning until it is given context by defining which taxonomy it exists under. 
     1268 * Create Term and Taxonomy Relationships. 
     1269 * 
     1270 * Relates an object (post, link etc) to a term and taxonomy type. Creates the 
     1271 * term and taxonomy relationship if it doesn't already exist. Creates a term if 
     1272 * it doesn't exist (using the slug). 
     1273 * 
     1274 * A relationship means that the term is grouped in or belongs to the taxonomy. 
     1275 * A term has no meaning until it is given context by defining which taxonomy it 
     1276 * exists under. 
    12451277 * 
    12461278 * @package WordPress 
     
    13161348 
    13171349/** 
    1318  * wp_unique_term_slug() - Will make slug unique, if it isn't already 
    1319  * 
    1320  * The $slug has to be unique global to every taxonomy, meaning that one taxonomy 
    1321  * term can't have a matching slug with another taxonomy term. Each slug has to be 
    1322  * globally unique for every taxonomy. 
    1323  * 
    1324  * The way this works is that if the taxonomy that the term belongs to is heirarchical 
    1325  * and has a parent, it will append that parent to the $slug. 
    1326  * 
    1327  * If that still doesn't return an unique slug, then it try to append a number until 
    1328  * it finds a number that is truely unique. 
     1350 * Will make slug unique, if it isn't already. 
     1351 * 
     1352 * The $slug has to be unique global to every taxonomy, meaning that one 
     1353 * taxonomy term can't have a matching slug with another taxonomy term. Each 
     1354 * slug has to be globally unique for every taxonomy. 
     1355 * 
     1356 * The way this works is that if the taxonomy that the term belongs to is 
     1357 * heirarchical and has a parent, it will append that parent to the $slug. 
     1358 * 
     1359 * If that still doesn't return an unique slug, then it try to append a number 
     1360 * until it finds a number that is truely unique. 
    13291361 * 
    13301362 * The only purpose for $term is for appending a parent, if one exists. 
     
    13771409 
    13781410/** 
    1379  * wp_update_term() - Update term based on arguments provided 
    1380  * 
    1381  * The $args will indiscriminately override all values with the same field name. Care 
    1382  * must be taken to not override important information need to update or update will 
    1383  * fail (or perhaps create a new term, neither would be acceptable). 
    1384  * 
    1385  * Defaults will set 'alias_of', 'description', 'parent', and 'slug' if not defined 
    1386  * in $args already. 
    1387  * 
    1388  * 'alias_of' will create a term group, if it doesn't already exist, and update it for 
    1389  * the $term. 
    1390  * 
    1391  * If the 'slug' argument in $args is missing, then the 'name' in $args will be used. 
    1392  * It should also be noted that if you set 'slug' and it isn't unique then a WP_Error 
    1393  * will be passed back. If you don't pass any slug, then a unique one will be created 
    1394  * for you. 
    1395  * 
    1396  * For what can be overrode in $args, check the term scheme can contain and stay away 
    1397  * from the term keys. 
     1411 * Update term based on arguments provided. 
     1412 * 
     1413 * The $args will indiscriminately override all values with the same field name. 
     1414 * Care must be taken to not override important information need to update or 
     1415 * update will fail (or perhaps create a new term, neither would be acceptable). 
     1416 * 
     1417 * Defaults will set 'alias_of', 'description', 'parent', and 'slug' if not 
     1418 * defined in $args already. 
     1419 * 
     1420 * 'alias_of' will create a term group, if it doesn't already exist, and update 
     1421 * it for the $term. 
     1422 * 
     1423 * If the 'slug' argument in $args is missing, then the 'name' in $args will be 
     1424 * used. It should also be noted that if you set 'slug' and it isn't unique then 
     1425 * a WP_Error will be passed back. If you don't pass any slug, then a unique one 
     1426 * will be created for you. 
     1427 * 
     1428 * For what can be overrode in $args, check the term scheme can contain and stay 
     1429 * away from the term keys. 
    13981430 * 
    13991431 * @package WordPress 
     
    14031435 * @uses $wpdb 
    14041436 * @uses do_action() Will call both 'edit_term' and 'edit_$taxonomy' twice. 
    1405  * @uses apply_filters() Will call the 'term_id_filter' filter and pass the term id and 
    1406  *  taxonomy id. 
     1437 * @uses apply_filters() Will call the 'term_id_filter' filter and pass the term 
     1438 *  id and taxonomy id. 
    14071439 * 
    14081440 * @param int $term The ID of the term 
     
    14901522} 
    14911523 
    1492 // enable or disable term count deferring 
    1493 // if no value is supplied, the current value of the defer setting is returned 
     1524/** 
     1525 * Enable or disable term counting. 
     1526 * 
     1527 * @since 2.6 
     1528 * 
     1529 * @param bool $defer Optional. 
     1530 * @return bool 
     1531 */ 
    14941532function wp_defer_term_counting($defer=NULL) { 
    14951533    static $_defer = false; 
     
    15061544 
    15071545/** 
    1508  * wp_update_term_count() - Updates the amount of terms in taxonomy 
    1509  * 
    1510  * If there is a taxonomy callback applyed, then it will be called for updating the count. 
    1511  * 
    1512  * The default action is to count what the amount of terms have the relationship of term ID. 
    1513  * Once that is done, then update the database. 
     1546 * Updates the amount of terms in taxonomy. 
     1547 * 
     1548 * If there is a taxonomy callback applyed, then it will be called for updating 
     1549 * the count. 
     1550 * 
     1551 * The default action is to count what the amount of terms have the relationship 
     1552 * of term ID. Once that is done, then update the database. 
    15141553 * 
    15151554 * @package WordPress 
     
    15481587} 
    15491588 
     1589/** 
     1590 * Perform term count update immediately. 
     1591 * 
     1592 * @since 2.6 
     1593 * 
     1594 * @param array $terms IDs of Terms to update. 
     1595 * @param string $taxonomy The context of the term. 
     1596 * @return bool Always true when complete. 
     1597 */ 
    15501598function wp_update_term_count_now( $terms, $taxonomy ) { 
    15511599    global $wpdb; 
     
    15741622// 
    15751623 
    1576 /** 
    1577  * clean_object_term_cache() - Removes the taxonomy relationship to terms from the cache. 
    1578  * 
    1579  * Will remove the entire taxonomy relationship containing term $object_id. The term IDs 
    1580  * have to exist within the taxonomy $object_type for the deletion to take place. 
     1624 
     1625/** 
     1626 * Removes the taxonomy relationship to terms from the cache. 
     1627 * 
     1628 * Will remove the entire taxonomy relationship containing term $object_id. The 
     1629 * term IDs have to exist within the taxonomy $object_type for the deletion to 
     1630 * take place. 
    15811631 * 
    15821632 * @package WordPress 
     
    16021652} 
    16031653 
    1604 /** 
    1605  * clean_term_cache() - Will remove all of the term ids from the cache 
     1654 
     1655/** 
     1656 * Will remove all of the term ids from the cache. 
    16061657 * 
    16071658 * @package WordPress 
     
    16471698} 
    16481699 
    1649 /** 
    1650  * get_object_term_cache() - Retrieves the taxonomy relationship to the term object id. 
     1700 
     1701/** 
     1702 * Retrieves the taxonomy relationship to the term object id. 
    16511703 * 
    16521704 * @package WordPress 
     
    16651717} 
    16661718 
    1667 /** 
    1668  * update_object_term_cache() - Updates the cache for Term ID(s) 
     1719 
     1720/** 
     1721 * Updates the cache for Term ID(s). 
    16691722 * 
    16701723 * Will only update the cache for terms not already cached. 
    16711724 * 
    1672  * The $object_ids expects that the ids be separated by commas, if it is 
    1673  * a string. 
    1674  * 
    1675  * It should be noted that update_object_term_cache() is very time extensive. 
    1676  * It is advised that the function is not called very often or at least not 
    1677  * for a lot of terms that exist in a lot of taxonomies. The amount of time 
    1678  * increases for each term and it also increases for each taxonomy the term 
    1679  * belongs to. 
     1725 * The $object_ids expects that the ids be separated by commas, if it is a 
     1726 * string. 
     1727 * 
     1728 * It should be noted that update_object_term_cache() is very time extensive. It 
     1729 * is advised that the function is not called very often or at least not for a 
     1730 * lot of terms that exist in a lot of taxonomies. The amount of time increases 
     1731 * for each term and it also increases for each taxonomy the term belongs to. 
    16801732 * 
    16811733 * @package WordPress 
     
    17351787} 
    17361788 
    1737 /** 
    1738  * update_term_cache() - Updates Terms to Taxonomy in cache. 
     1789 
     1790/** 
     1791 * Updates Terms to Taxonomy in cache. 
    17391792 * 
    17401793 * @package WordPress 
     
    17591812// 
    17601813 
    1761 /** 
    1762  * _get_term_hierarchy() - Retrieves children of taxonomy 
     1814 
     1815/** 
     1816 * Retrieves children of taxonomy. 
    17631817 * 
    17641818 * @package WordPress 
     
    17671821 * @since 2.3 
    17681822 * 
    1769  * @uses update_option() Stores all of the children in "$taxonomy_children" option. 
    1770  *  That is the name of the taxonomy, immediately followed by '_children'. 
     1823 * @uses update_option() Stores all of the children in "$taxonomy_children" 
     1824 *   option. That is the name of the taxonomy, immediately followed by '_children'. 
    17711825 * 
    17721826 * @param string $taxonomy Taxonomy Name 
     
    17911845} 
    17921846 
    1793 /** 
    1794  * _get_term_children() - Get array of child terms 
    1795  * 
    1796  * If $terms is an array of objects, then objects will returned from the function. 
    1797  * If $terms is an array of IDs, then an array of ids of children will be returned. 
     1847 
     1848/** 
     1849 * Get array of child terms. 
     1850 * 
     1851 * If $terms is an array of objects, then objects will returned from the 
     1852 * function. If $terms is an array of IDs, then an array of ids of children will 
     1853 * be returned. 
    17981854 * 
    17991855 * @package WordPress 
     
    18471903} 
    18481904 
    1849 /** 
    1850  * _pad_term_counts() - Add count of children to parent count 
    1851  * 
    1852  * Recalculates term counts by including items from child terms. 
    1853  * Assumes all relevant children are already in the $terms argument 
     1905 
     1906/** 
     1907 * Add count of children to parent count. 
     1908 * 
     1909 * Recalculates term counts by including items from child terms. Assumes all 
     1910 * relevant children are already in the $terms argument. 
    18541911 * 
    18551912 * @package WordPress 
     
    19111968 
    19121969/** 
    1913  * _update_post_term_count() - Will update term count based on posts 
    1914  * 
    1915  * Private function for the default callback for post_tag and category taxonomies. 
     1970 * Will update term count based on posts. 
     1971 * 
     1972 * Private function for the default callback for post_tag and category 
     1973 * taxonomies. 
    19161974 * 
    19171975 * @package WordPress 
     
    19321990} 
    19331991 
    1934 /** 
    1935  * get_term_link() - Generates a permalink for a taxonomy term archive 
     1992 
     1993/** 
     1994 * Generates a permalink for a taxonomy term archive. 
     1995 * 
     1996 * @since 2.6 
    19361997 * 
    19371998 * @param object|int|string $term 
     
    19762037} 
    19772038 
     2039/** 
     2040 * Display the taxonomies of a post with available options. 
     2041 * 
     2042 * This function can be used within the loop to display the taxonomies for a 
     2043 * post without specifying the Post ID. You can also use it outside the Loop to 
     2044 * display the taxonomies for a specific post. 
     2045 * 
     2046 * The available defaults are: 
     2047 * 'post' : default is 0. The post ID to get taxonomies of. 
     2048 * 'before' : default is empty string. Display before taxonomies list. 
     2049 * 'sep' : default is empty string. Separate every taxonomy with value in this. 
     2050 * 'after' : default is empty string. Display this after the taxonomies list. 
     2051 * 
     2052 * @since 2.6 
     2053 * @uses get_the_taxonomies() 
     2054 * 
     2055 * @param array $args Override the defaults. 
     2056 */ 
    19782057function the_taxonomies($args = array()) { 
    19792058    $defaults = array( 
     
    19902069} 
    19912070 
     2071/** 
     2072 * Retrieve all taxonomies associated with a post. 
     2073 * 
     2074 * This function can be used within the loop. It will also return an array of 
     2075 * the taxonomies with links to the taxonomy and name. 
     2076 * 
     2077 * @since 2.6 
     2078 * 
     2079 * @param int $post Optional. Post ID or will use Global Post ID (in loop). 
     2080 * @return array 
     2081 */ 
    19922082function get_the_taxonomies($post = 0) { 
    19932083    if ( is_int($post) ) 
     
    20272117} 
    20282118 
     2119/** 
     2120 * Retrieve all taxonomies of a post with just the names. 
     2121 * 
     2122 * @since 2.6 
     2123 * @uses get_object_taxonomies() 
     2124 * 
     2125 * @param int $post Optional. Post ID 
     2126 * @return array 
     2127 */ 
    20292128function get_post_taxonomies($post = 0) { 
    20302129    $post =& get_post($post); 
  • trunk/wp-includes/wp-db.php

    r8134 r8164  
    11<?php 
    2 //  WordPress DB Class 
    3  
    4 //  ORIGINAL CODE FROM: 
    5 //  Justin Vincent (justin@visunet.ie) 
    6 //  http://php.justinvincent.com 
    7  
     2/** 
     3 * WordPress DB Class 
     4 * 
     5 * Original code from {@link http://php.justinvincent.com Justin Vincent (justin@visunet.ie)} 
     6 * 
     7 * @package WordPress 
     8 * @subpackage Database 
     9 * @since 0.71 
     10 */ 
     11 
     12/** 
     13 * @since 0.71 
     14 */ 
    815define('EZSQL_VERSION', 'WP1.25'); 
     16 
     17/** 
     18 * @since 0.71 
     19 */ 
    920define('OBJECT', 'OBJECT', true); 
     21 
     22/** 
     23 * @since {@internal Version Unknown}} 
     24 */ 
    1025define('OBJECT_K', 'OBJECT_K', false); 
     26 
     27/** 
     28 * @since 0.71 
     29 */ 
    1130define('ARRAY_A', 'ARRAY_A', false); 
     31 
     32/** 
     33 * @since 0.71 
     34 */ 
    1235define('ARRAY_N', 'ARRAY_N', false); 
    1336 
     37/** 
     38 * WordPress Database Access Abstraction Object 
     39 * 
     40 * It is possible to replace this class with your own 
     41 * by setting the $wpdb global variable in wp-content/wpdb.php 
     42 * file with your class. You can name it wpdb also, since 
     43 * this file will not be included, if the other file is 
     44 * available. 
     45 * 
     46 * @link http://codex.wordpress.org/Function_Reference/wpdb_Class 
     47 * 
     48 * @package WordPress 
     49 * @subpackage Database 
     50 * @since 0.71 
     51 * @final 
     52 */ 
    1453class wpdb { 
    1554 
     55    /** 
     56     * Whether to show SQL/DB errors 
     57     * 
     58     * @since 0.71 
     59     * @access private 
     60     * @var bool 
     61     */ 
    1662    var $show_errors = false; 
     63 
     64    /** 
     65     * Whether to suppress errors during the DB bootstrapping. 
     66     * 
     67     * @access private 
     68     * @since {@internal Version Unknown}} 
     69     * @var bool 
     70     */ 
    1771    var $suppress_errors = false; 
     72 
     73    /** 
     74     * The last error during query. 
     75     * 
     76     * @since {@internal Version Unknown}} 
     77     * @var string 
     78     */ 
    1879    var $last_error = ''; 
     80 
     81    /** 
     82     * Amount of queries made 
     83     * 
     84     * @since 1.2.0 
     85     * @access private 
     86     * @var int 
     87     */ 
    1988    var $num_queries = 0; 
     89 
     90    /** 
     91     * Saved result of the last query made 
     92     * 
     93     * @since 1.2.0 
     94     * @access private 
     95     * @var array 
     96     */ 
    2097    var $last_query; 
     98 
     99    /** 
     100     * Saved info on the table column 
     101     * 
     102     * @since 1.2.0 
     103     * @access private 
     104     * @var array 
     105     */ 
    21106    var $col_info; 
     107 
     108    /** 
     109     * Saved queries that were executed 
     110     * 
     111     * @since 1.5.0 
     112     * @access private 
     113     * @var array 
     114     */ 
    22115    var $queries; 
     116 
     117    /** 
     118     * WordPress table prefix 
     119     * 
     120     * You can set this to have multiple WordPress installations 
     121     * in a single database. The second reason is for possible 
     122     * security precautions. 
     123     * 
     124     * @since 0.71 
     125     * @access private 
     126     * @var string 
     127     */ 
    23128    var $prefix = ''; 
     129 
     130    /** 
     131     * Whether the database queries are ready to start executing. 
     132     * 
     133     * @since 2.5.0 
     134     * @access private 
     135     * @var bool 
     136     */ 
    24137    var $ready = false; 
    25138 
    26     // Our tables 
     139    /** 
     140     * WordPress Posts table 
     141     * 
     142     * @since 1.5.0 
     143     * @access public 
     144     * @var string 
     145     */ 
    27146    var $posts; 
     147 
     148    /** 
     149     * WordPress Users table 
     150     * 
     151     * @since 1.5.0 
     152     * @access public 
     153     * @var string 
     154     */ 
    28155    var $users; 
     156 
     157    /** 
     158     * WordPress Categories table 
     159     * 
     160     * @since 1.5.0 
     161     * @access public 
     162     * @var string 
     163     */ 
    29164    var $categories; 
     165 
     166    /** 
     167     * WordPress Post to Category table 
     168     * 
     169     * @since 1.5.0 
     170     * @access public 
     171     * @var string 
     172     */ 
    30173    var $post2cat; 
     174 
     175    /** 
     176     * WordPress Comments table 
     177     * 
     178     * @since 1.5.0 
     179     * @access public 
     180     * @var string 
     181     */ 
    31182    var $comments; 
     183 
     184    /** 
     185     * WordPress Links table 
     186     * 
     187     * @since 1.5.0 
     188     * @access public 
     189     * @var string 
     190     */ 
    32191    var $links; 
     192 
     193    /** 
     194     * WordPress Options table 
     195     * 
     196     * @since 1.5.0 
     197     * @access public 
     198     * @var string 
     199     */ 
    33200    var $options; 
     201 
     202    /** 
     203     * WordPress Post Metadata table 
     204     * 
     205     * @since {@internal Version Unknown}} 
     206     * @access public 
     207     * @var string 
     208     */ 
    34209    var $postmeta; 
     210 
     211    /** 
     212     * WordPress User Metadata table 
     213     * 
     214     * @since 2.3.0 
     215     * @access public 
     216     * @var string 
     217     */ 
    35218    var $usermeta; 
     219 
     220    /** 
     221     * WordPress Terms table 
     222     * 
     223     * @since 2.3.0 
     224     * @access public 
     225     * @var string 
     226     */ 
    36227    var $terms; 
     228 
     229    /** 
     230     * WordPress Term Taxonomy table 
     231     * 
     232     * @since 2.3.0 
     233     * @access public 
     234     * @var string 
     235     */ 
    37236    var $term_taxonomy; 
     237 
     238    /** 
     239     * WordPress Term Relationships table 
     240     * 
     241     * @since 2.3.0 
     242     * @access public 
     243     * @var string 
     244     */ 
    38245    var $term_relationships; 
     246 
     247    /** 
     248     * List of WordPress tables 
     249     * 
     250     * @since {@internal Version Unknown}} 
     251     * @access private 
     252     * @var array 
     253     */ 
    39254    var $tables = array('users', 'usermeta', 'posts', 'categories', 'post2cat', 'comments', 'links', 'link2cat', 'options', 
    40255            'postmeta', 'terms', 'term_taxonomy', 'term_relationships'); 
     256 
     257    /** 
     258     * Database table columns charset 
     259     * 
     260     * @since 2.2.0 
     261     * @access public 
     262     * @var string 
     263     */ 
    41264    var $charset; 
     265 
     266    /** 
     267     * Database table columns collate 
     268     * 
     269     * @since 2.2.0 
     270     * @access public 
     271     * @var string 
     272     */ 
    42273    var $collate; 
    43274 
    44275    /** 
    45276     * Connects to the database server and selects a database 
    46      * @param string $dbuser 
    47      * @param string $dbpassword 
    48      * @param string $dbname 
    49      * @param string $dbhost 
     277     * 
     278     * PHP4 compatibility layer for calling the PHP5 constructor. 
     279     * 
     280     * @uses wpdb::__construct() Passes parameters and returns result 
     281     * @since 0.71 
     282     * 
     283     * @param string $dbuser MySQL database user 
     284     * @param string $dbpassword MySQL database password 
     285     * @param string $dbname MySQL database name 
     286     * @param string $dbhost MySQL database host 
    50287     */ 
    51288    function wpdb($dbuser, $dbpassword, $dbname, $dbhost) { 
     
    53290    } 
    54291 
     292    /** 
     293     * Connects to the database server and selects a database 
     294     * 
     295     * PHP5 style constructor for compatibility with PHP5. Does 
     296     * the actual setting up of the class properties and connection 
     297     * to the database. 
     298     * 
     299     * @since 2.0.8 
     300     * 
     301     * @param string $dbuser MySQL database user 
     302     * @param string $dbpassword MySQL database password 
     303     * @param string $dbname MySQL database name 
     304     * @param string $dbhost MySQL database host 
     305     */ 
    55306    function __construct($dbuser, $dbpassword, $dbname, $dbhost) { 
    56307        register_shutdown_function(array(&$this, "__destruct")); 
     
    98349    } 
    99350 
     351    /** 
     352     * PHP5 style destructor and will run when database object is destroyed. 
     353     * 
     354     * @since 2.0.8 
     355     * 
     356     * @return bool Always true 
     357     */ 
    100358    function __destruct() { 
    101359        return true; 
    102360    } 
    103361 
     362    /** 
     363     * Sets the table prefix for the WordPress tables. 
     364     * 
     365     * Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to 
     366     * override the WordPress users and usersmeta tables. 
     367     * 
     368     * @since 2.5.0 
     369     * 
     370     * @param string $prefix Alphanumeric name for the new prefix. 
     371     * @return string Old prefix 
     372     */ 
    104373    function set_prefix($prefix) { 
    105374 
     
    123392 
    124393    /** 
    125      * Selects a database using the current class's $this->dbh 
    126      * @param string $db name 
     394     * Selects a database using the current database connection. 
     395     * 
     396     * The database name will be changed based on the current database 
     397     * connection. On failure, the execution will bail and display an DB error. 
     398     * 
     399     * @since 0.71 
     400     * 
     401     * @param string $db MySQL database name 
     402     * @return null Always null. 
    127403     */ 
    128404    function select($db) { 
     
    145421     * Escapes content for insertion into the database, for security 
    146422     * 
     423     * @since 0.71 
     424     * 
    147425     * @param string $string 
    148426     * @return string query safe string 
     
    161439    /** 
    162440     * Escapes content by reference for insertion into the database, for security 
     441     * 
     442     * @since 2.3.0 
     443     * 
    163444     * @param string $s 
    164445     */ 
     
    168449 
    169450    /** 
    170      * Prepares a SQL query for safe use, using sprintf() syntax 
    171      */ 
    172     function prepare($args=NULL) { 
    173         if ( NULL === $args ) 
     451     * Prepares a SQL query for safe use, using sprintf() syntax. 
     452     * 
     453     * @link http://php.net/sprintf See for syntax to use for query string. 
     454     * @since 2.3.0 
     455     * 
     456     * @param null|string $args If string, first parameter must be query statement 
     457     * @param mixed $args,... If additional parameters, they will be set inserted into the query. 
     458     * @return null|string Sanitized query string 
     459     */ 
     460    function prepare($args=null) { 
     461        if ( is_null( $args ) ) 
    174462            return; 
    175463        $args = func_get_args(); 
     
    182470    } 
    183471 
    184     // ================================================================== 
    185     //  Print SQL/DB error. 
    186  
     472    /** 
     473     * Print SQL/DB error. 
     474     * 
     475     * @since 0.71 
     476     * @global array $EZSQL_ERROR Stores error information of query and error string 
     477     * 
     478     * @param string $str The error to display 
     479     * @return bool False if the showing of errors is disabled. 
     480     */ 
    187481    function print_error($str = '') { 
    188482        global $EZSQL_ERROR; 
    189483 
    190484        if (!$str) $str = mysql_error($this->dbh); 
    191         $EZSQL_ERROR[] = 
    192         array ('query' => $this->last_query, 'error_str' => $str); 
     485        $EZSQL_ERROR[] = array ('query' => $this->last_query, 'error_str' => $str); 
    193486 
    194487        if ( $this->suppress_errors ) 
     
    224517    } 
    225518 
    226     // ================================================================== 
    227     //  Turn error handling on or off.. 
    228  
     519    /** 
     520     * Enables showing of database errors. 
     521     * 
     522     * This function should be used only to enable showing of errors. 
     523     * wpdb::hide_errors() should be used instead for hiding of errors. However, 
     524     * this function can be used to enable and disable showing of database 
     525     * errors. 
     526     * 
     527     * @since 0.71 
     528     * 
     529     * @param bool $show Whether to show or hide errors 
     530     * @return bool Old value for showing errors. 
     531     */ 
    229532    function show_errors( $show = true ) { 
    230533        $errors = $this->show_errors; 
     
    233536    } 
    234537 
     538    /** 
     539     * Disables showing of database errors. 
     540     * 
     541     * @since 0.71 
     542     * 
     543     * @return bool Whether showing of errors was active or not 
     544     */ 
    235545    function hide_errors() { 
    236546        $show = $this->show_errors; 
     
    239549    } 
    240550 
     551    /** 
     552     * Whether to suppress database errors. 
     553     * 
     554     * @param unknown_type $suppress 
     555     * @return unknown 
     556     */ 
    241557    function suppress_errors( $suppress = true ) { 
    242558        $errors = $this->suppress_errors; 
     
    245561    } 
    246562 
    247     // ================================================================== 
    248     //  Kill cached query results 
    249  
     563    /** 
     564     * Kill cached query results. 
     565     * 
     566     * @since 0.71 
     567     */ 
    250568    function flush() { 
    251569        $this->last_result = array(); 
     
    254572    } 
    255573 
    256     // ================================================================== 
    257     //  Basic Query - see docs for more detail 
    258  
     574    /** 
     575     * Perform a MySQL database query, using current database connection. 
     576     * 
     577     * More information can be found on the codex page. 
     578     * 
     579     * @since 0.71 
     580     * 
     581     * @param string $query 
     582     * @return unknown 
     583     */ 
    259584    function query($query) { 
    260585        if ( ! $this->ready ) 
     
    325650 
    326651    /** 
    327      * Insert an array of data into a table 
     652     * Insert an array of data into a table. 
     653     * 
     654     * @since 2.5.0 
     655     * 
    328656     * @param string $table WARNING: not sanitized! 
    329      * @param array $data should not already be SQL-escaped 
    330      * @return mixed results of $this->query() 
     657     * @param array $data Should not already be SQL-escaped 
     658     * @return mixed Results of $this->query() 
    331659     */ 
    332660    function insert($table, $data) { 
     
    337665 
    338666    /** 
    339      * Update a row in the table with an array of data 
     667     * Update a row in the table with an array of data. 
     668     * 
     669     * @since 2.5.0 
     670     * 
    340671     * @param string $table WARNING: not sanitized! 
    341      * @param array $data should not already be SQL-escaped 
    342      * @param array $where a named array of WHERE column => value relationships.  Multiple member pairs will be joined with ANDs.  WARNING: the column names are not currently sanitized! 
    343      * @return mixed results of $this->query() 
     672     * @param array $data Should not already be SQL-escaped 
     673     * @param array $where A named array of WHERE column => value relationships.  Multiple member pairs will be joined with ANDs.  WARNING: the column names are not currently sanitized! 
     674     * @return mixed Results of $this->query() 
    344675     */ 
    345676    function update($table, $data, $where){ 
     
    358689 
    359690    /** 
    360      * Get one variable from the database 
    361      * @param string $query (can be null as well, for caching, see codex) 
    362      * @param int $x = 0 row num to return 
    363      * @param int $y = 0 col num to return 
    364      * @return mixed results 
     691     * Retrieve one variable from the database. 
     692     * 
     693     * This combines the functionality of wpdb::get_row() and wpdb::get_col(), 
     694     * so both the column and row can be picked. 
     695     * 
     696     * It is possible to use this function without executing more queries. If 
     697     * you already made a query, you can set the $query to 'null' value and just 
     698     * retrieve either the column and row of the last query result. 
     699     * 
     700     * @since 0.71 
     701     * 
     702     * @param string $query Can be null as well, for caching 
     703     * @param int $x Column num to return 
     704     * @param int $y Row num to return 
     705     * @return mixed Database query results 
    365706     */ 
    366707    function get_var($query=null, $x = 0, $y = 0) { 
     
    379720 
    380721    /** 
    381      * Get one row from the database 
    382      * @param string $query 
     722     * Retrieve one row from the database. 
     723     * 
     724     * @since 0.71 
     725     * 
     726     * @param string $query SQL query 
    383727     * @param string $output ARRAY_A | ARRAY_N | OBJECT 
    384      * @param int $y row num to return 
    385      * @return mixed results 
     728     * @param int $y Row num to return 
     729     * @return mixed Database query results 
    386730     */ 
    387731    function get_row($query = null, $output = OBJECT, $y = 0) { 
     
    407751 
    408752    /** 
    409      * Gets one column from the database 
    410      * @param string $query (can be null as well, for caching, see codex) 
    411      * @param int $x col num to return 
    412      * @return array results 
     753     * Retrieve one column from the database. 
     754     * 
     755     * @since 0.71 
     756     * 
     757     * @param string $query Can be null as well, for caching 
     758     * @param int $x Col num to return. Starts from 0. 
     759     * @return array Column results 
    413760     */ 
    414761    function get_col($query = null , $x = 0) { 
     
    425772 
    426773    /** 
    427      * Return an entire result set from the database 
    428      * @param string $query (can also be null to pull from the cache) 
     774     * Retrieve an entire result set from the database. 
     775     * 
     776     * @since 0.71 
     777     * 
     778     * @param string|null $query Can also be null to pull from the cache 
    429779     * @param string $output ARRAY_A | ARRAY_N | OBJECT_K | OBJECT 
    430      * @return mixed results 
     780     * @return mixed Database query results 
    431781     */ 
    432782    function get_results($query = null, $output = OBJECT) { 
     
    470820 
    471821    /** 
    472      * Grabs column metadata from the last query 
     822     * Retrieve column metadata from the last query. 
     823     * 
     824     * @since 0.71 
     825     * 
    473826     * @param string $info_type one of name, table, def, max_length, not_null, primary_key, multiple_key, unique_key, numeric, blob, type, unsigned, zerofill 
    474827     * @param int $col_offset 0: col name. 1: which table the col's in. 2: col's max length. 3: if the col is numeric. 4: col's type 
    475      * @return mixed results 
     828     * @return mixed Column Results 
    476829     */ 
    477830    function get_col_info($info_type = 'name', $col_offset = -1) { 
     
    491844 
    492845    /** 
    493      * Starts the timer, for debugging purposes 
     846     * Starts the timer, for debugging purposes. 
     847     * 
     848     * @since 1.5.0 
     849     * 
     850     * @return bool Always returns true 
    494851     */ 
    495852    function timer_start() { 
     
    501858 
    502859    /** 
    503      * Stops the debugging timer 
    504      * @return int total time spent on the query, in milliseconds 
     860     * Stops the debugging timer. 
     861     * 
     862     * @since 1.5.0 
     863     * 
     864     * @return int Total time spent on the query, in milliseconds 
    505865     */ 
    506866    function timer_stop() { 
     
    514874    /** 
    515875     * Wraps fatal errors in a nice header and footer and dies. 
     876     * 
     877     * @since 1.5.0 
     878     * 
    516879     * @param string $message 
    517      */ 
    518     function bail($message) { // Just wraps errors in a nice header and footer 
     880     * @return unknown 
     881     */ 
     882    function bail($message) { 
    519883        if ( !$this->show_errors ) { 
    520884            if ( class_exists('WP_Error') ) 
     
    528892 
    529893    /** 
    530      * Checks wether of not the database version is high enough to support the features WordPress uses 
    531      * @global $wp_version 
     894     * Whether or not MySQL database is minimal required version. 
     895     * 
     896     * @since 2.5.0 
     897     * @uses $wp_version 
     898     * 
     899     * @return WP_Error 
    532900     */ 
    533901    function check_database_version() 
     
    541909 
    542910    /** 
    543      * This function is called when WordPress is generating the table schema to determine wether or not the current database 
    544      * supports or needs the collation statements. 
     911     * Whether of not the database version supports collation. 
     912     * 
     913     * Called when WordPress is generating the table scheme. 
     914     * 
     915     * @since 2.5.0 
     916     * 
     917     * @return bool True if collation is supported, false if version does not 
    545918     */ 
    546919    function supports_collation() 
     
    550923 
    551924    /** 
    552      * Get the name of the function that called wpdb. 
    553      * @return string the name of the calling function 
     925     * Retrieve the name of the function that called wpdb. 
     926     * 
     927     * Requires PHP 4.3 and searches up the list of functions until it reaches 
     928     * the one that would most logically had called this method. 
     929     * 
     930     * @since 2.5.0 
     931     * 
     932     * @return string The name of the calling function 
    554933     */ 
    555934    function get_caller() { 
     
    579958} 
    580959 
    581 if ( ! isset($wpdb) ) 
     960if ( ! isset($wpdb) ) { 
     961    /** 
     962     * WordPress Database Object, if it isn't set already in wp-content/wpdb.php 
     963     * @global object $wpdb Creates a new wpdb object based on wp-config.php Constants for the database 
     964     * @since 0.71 
     965     */ 
    582966    $wpdb = new wpdb(DB_USER, DB_PASSWORD, DB_NAME, DB_HOST); 
     967} 
    583968?> 
Note: See TracChangeset for help on using the changeset viewer.