WordPress.org

Make WordPress Core

Changeset 8164


Ignore:
Timestamp:
06/22/2008 08:23:23 PM (11 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.