[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

title

Body

[close]

/wp-includes/ -> pluggable.php (summary)

These functions can be replaced via plugins. If plugins do not redefine these functions, then these will be used instead.

File Size: 2745 lines (98 kb)
Included or required: 6 times
Referenced: 0 times
Includes or requires: 4 files
 wp-includes/wp-diff.php
 wp-includes/class-smtp.php
 wp-includes/class-phpmailer.php
 wp-includes/class-phpass.php

Defines 38 functions

  wp_set_current_user()
  wp_get_current_user()
  get_userdata()
  get_user_by()
  cache_users()
  wp_mail()
  wp_authenticate()
  wp_logout()
  wp_validate_auth_cookie()
  wp_generate_auth_cookie()
  wp_parse_auth_cookie()
  wp_set_auth_cookie()
  wp_clear_auth_cookie()
  is_user_logged_in()
  auth_redirect()
  check_admin_referer()
  check_ajax_referer()
  wp_redirect()
  wp_sanitize_redirect()
  _wp_sanitize_utf8_in_redirect()
  wp_safe_redirect()
  wp_validate_redirect()
  wp_notify_postauthor()
  wp_notify_moderator()
  wp_password_change_notification()
  wp_new_user_notification()
  wp_nonce_tick()
  wp_verify_nonce()
  wp_create_nonce()
  wp_salt()
  wp_hash()
  wp_hash_password()
  wp_check_password()
  wp_generate_password()
  wp_rand()
  wp_set_password()
  get_avatar()
  wp_text_diff()

Functions
Functions that are not part of a class:

wp_set_current_user( $id, $name = '' )   X-Ref
Changes the current user by ID or name.

Set $id to null and specify a name if you do not know a user's ID.

Some WordPress functionality is based on the current user and not based on
the signed in user. Therefore, it opens the ability to edit and perform
actions on users who aren't signed in.

param: int    $id   User ID
param: string $name User's username
return: WP_User Current user User object

wp_get_current_user()   X-Ref
Retrieve the current user object.

Will set the current user, if the current user is not set. The current user
will be set to the logged-in person. If no user is logged-in, then it will
set the current user to 0, which is invalid and won't have any permissions.

return: WP_User Current WP_User instance.

get_userdata( $user_id )   X-Ref
Retrieve user info by user ID.

param: int $user_id User ID
return: WP_User|false WP_User object on success, false on failure.

get_user_by( $field, $value )   X-Ref
Retrieve user info by a given field

param: string     $field The field to retrieve the user with. id | ID | slug | email | login.
param: int|string $value A value for $field. A user ID, slug, email address, or login name.
return: WP_User|false WP_User object on success, false on failure.

cache_users( $user_ids )   X-Ref
Retrieve info for user lists to prevent multiple queries by get_userdata()

param: array $user_ids User ID numbers list

wp_mail( $to, $subject, $message, $headers = '', $attachments = array()   X-Ref
Send mail, similar to PHP's mail

A true return value does not automatically mean that the user received the
email successfully. It just only means that the method used was able to
process the request without any errors.

Using the two 'wp_mail_from' and 'wp_mail_from_name' hooks allow from
creating a from address like 'Name <email@address.com>' when both are set. If
just 'wp_mail_from' is set, then just the email address will be used with no
name.

The default content type is 'text/plain' which does not allow using HTML.
However, you can set the content type of the email by using the
{@see 'wp_mail_content_type'} filter.

The default charset is based on the charset used on the blog. The charset can
be set using the {@see 'wp_mail_charset'} filter.

param: string|array $to          Array or comma-separated list of email addresses to send message.
param: string       $subject     Email subject
param: string       $message     Message contents
param: string|array $headers     Optional. Additional headers.
param: string|array $attachments Optional. Files to attach.
return: bool Whether the email contents were sent successfully.

wp_authenticate( $username, $password )   X-Ref
Authenticate a user, confirming the login credentials are valid.

param: string $username User's username or email address.
param: string $password User's password.
return: WP_User|WP_Error WP_User object if the credentials are valid,

wp_logout()   X-Ref
Log the current user out.


wp_validate_auth_cookie( $cookie = '', $scheme = '' )   X-Ref
Validates authentication cookie.

The checks include making sure that the authentication cookie is set and
pulling in the contents (if $cookie is not used).

Makes sure the cookie is not expired. Verifies the hash in cookie is what is
should be and compares the two.

param: string $cookie Optional. If used, will validate contents instead of cookie's
param: string $scheme Optional. The cookie scheme to use: auth, secure_auth, or logged_in
return: false|int False if invalid cookie, User ID if valid.

wp_generate_auth_cookie( $user_id, $expiration, $scheme = 'auth', $token = '' )   X-Ref
Generate authentication cookie contents.

param: int    $user_id    User ID
param: int    $expiration The time the cookie expires as a UNIX timestamp.
param: string $scheme     Optional. The cookie scheme to use: auth, secure_auth, or logged_in
param: string $token      User's session token to use for this cookie
return: string Authentication cookie contents. Empty string if user does not exist.

wp_parse_auth_cookie( $cookie = '', $scheme = '' )   X-Ref
Parse a cookie into its components

param: string $cookie
param: string $scheme Optional. The cookie scheme to use: auth, secure_auth, or logged_in
return: array|false Authentication cookie components

wp_set_auth_cookie( $user_id, $remember = false, $secure = '', $token = '' )   X-Ref
Log in a user by setting authentication cookies.

The $remember parameter increases the time that the cookie will be kept. The
default the cookie is kept without remembering is two days. When $remember is
set, the cookies will be kept for 14 days or two weeks.

param: int    $user_id  User ID
param: bool   $remember Whether to remember the user
param: mixed  $secure   Whether the admin cookies should only be sent over HTTPS.
param: string $token    Optional. User's session token to use for this cookie.

wp_clear_auth_cookie()   X-Ref
Removes all of the cookies associated with authentication.


is_user_logged_in()   X-Ref
Determines whether the current visitor is a logged in user.

For more information on this and similar theme functions, check out
the {@link https://developer.wordpress.org/themes/basics/conditional-tags/
Conditional Tags} article in the Theme Developer Handbook.

return: bool True if user is logged in, false if not logged in.

auth_redirect()   X-Ref
Checks if a user is logged in, if not it redirects them to the login page.


check_admin_referer( $action = -1, $query_arg = '_wpnonce' )   X-Ref
Makes sure that a user was referred from another admin page.

To avoid security exploits.

param: int|string $action    Action nonce.
param: string     $query_arg Optional. Key to check for nonce in `$_REQUEST` (since 2.5).
return: false|int False if the nonce is invalid, 1 if the nonce is valid and generated between

check_ajax_referer( $action = -1, $query_arg = false, $die = true )   X-Ref
Verifies the Ajax request to prevent processing requests external of the blog.

param: int|string   $action    Action nonce.
param: false|string $query_arg Optional. Key to check for the nonce in `$_REQUEST` (since 2.5). If false,
param: bool         $die       Optional. Whether to die early when the nonce cannot be verified.
return: false|int False if the nonce is invalid, 1 if the nonce is valid and generated between

wp_redirect( $location, $status = 302, $x_redirect_by = 'WordPress' )   X-Ref
Redirects to another page.

Note: wp_redirect() does not exit automatically, and should almost always be
followed by a call to `exit;`:

wp_redirect( $url );
exit;

Exiting can also be selectively manipulated by using wp_redirect() as a conditional
in conjunction with the {@see 'wp_redirect'} and {@see 'wp_redirect_location'} filters:

if ( wp_redirect( $url ) ) {
exit;
}

param: string $location      The path or URL to redirect to.
param: int    $status        Optional. HTTP response status code to use. Default '302' (Moved Temporarily).
param: string $x_redirect_by Optional. The application doing the redirect. Default 'WordPress'.
return: bool False if the redirect was cancelled, true otherwise.

wp_sanitize_redirect( $location )   X-Ref
Sanitizes a URL for use in a redirect.

param: string $location The path to redirect to.
return: string Redirect-sanitized URL.

_wp_sanitize_utf8_in_redirect( $matches )   X-Ref
URL encode UTF-8 characters in a URL.

param: array $matches RegEx matches against the redirect location.
return: string URL-encoded version of the first RegEx match.

wp_safe_redirect( $location, $status = 302, $x_redirect_by = 'WordPress' )   X-Ref
Performs a safe (local) redirect, using wp_redirect().

Checks whether the $location is using an allowed host, if it has an absolute
path. A plugin can therefore set or remove allowed host(s) to or from the
list.

If the host is not allowed, then the redirect defaults to wp-admin on the siteurl
instead. This prevents malicious redirects which redirect to another host,
but only used in a few places.

Note: wp_safe_redirect() does not exit automatically, and should almost always be
followed by a call to `exit;`:

wp_safe_redirect( $url );
exit;

Exiting can also be selectively manipulated by using wp_safe_redirect() as a conditional
in conjunction with the {@see 'wp_redirect'} and {@see 'wp_redirect_location'} filters:

if ( wp_safe_redirect( $url ) ) {
exit;
}

param: string $location      The path or URL to redirect to.
param: int    $status        Optional. HTTP response status code to use. Default '302' (Moved Temporarily).
param: string $x_redirect_by Optional. The application doing the redirect. Default 'WordPress'.
return: bool  $redirect False if the redirect was cancelled, true otherwise.

wp_validate_redirect( $location, $default = '' )   X-Ref
Validates a URL for use in a redirect.

Checks whether the $location is using an allowed host, if it has an absolute
path. A plugin can therefore set or remove allowed host(s) to or from the
list.

If the host is not allowed, then the redirect is to $default supplied

param: string $location The redirect to validate
param: string $default  The value to return if $location is not allowed
return: string redirect-sanitized URL

wp_notify_postauthor( $comment_id, $deprecated = null )   X-Ref
Notify an author (and/or others) of a comment/trackback/pingback on a post.

param: int|WP_Comment  $comment_id Comment ID or WP_Comment object.
param: string          $deprecated Not used
return: bool True on completion. False if no email addresses were specified.

wp_notify_moderator( $comment_id )   X-Ref
Notifies the moderator of the site about a new comment that is awaiting approval.

param: int $comment_id Comment ID.
return: true Always returns true.

wp_password_change_notification( $user )   X-Ref
Notify the blog admin of a user changing password, normally via email.

param: WP_User $user User object.

wp_new_user_notification( $user_id, $deprecated = null, $notify = '' )   X-Ref
Email login credentials to a newly-registered user.

A new user registration notification is also sent to admin email.

param: int    $user_id    User ID.
param: null   $deprecated Not used (argument deprecated).
param: string $notify     Optional. Type of notification that should happen. Accepts 'admin' or an empty

wp_nonce_tick()   X-Ref
Get the time-dependent variable for nonce creation.

A nonce has a lifespan of two ticks. Nonces in their second tick may be
updated, e.g. by autosave.

return: float Float value rounded up to the next highest integer.

wp_verify_nonce( $nonce, $action = -1 )   X-Ref
Verify that correct nonce was used with time limit.

The user is given an amount of time to use the token, so therefore, since the
UID and $action remain the same, the independent variable is the time.

param: string     $nonce  Nonce that was used in the form to verify
param: string|int $action Should give context to what is taking place and be the same when nonce was created.
return: false|int False if the nonce is invalid, 1 if the nonce is valid and generated between

wp_create_nonce( $action = -1 )   X-Ref
Creates a cryptographic token tied to a specific action, user, user session,
and window of time.

param: string|int $action Scalar value to add context to the nonce.
return: string The token.

wp_salt( $scheme = 'auth' )   X-Ref
Get salt to add to hashes.

Salts are created using secret keys. Secret keys are located in two places:
in the database and in the wp-config.php file. The secret key in the database
is randomly generated and will be appended to the secret keys in wp-config.php.

The secret keys in wp-config.php should be updated to strong, random keys to maximize
security. Below is an example of how the secret key constants are defined.
Do not paste this example directly into wp-config.php. Instead, have a
{@link https://api.wordpress.org/secret-key/1.1/salt/ secret key created} just
for you.

define('AUTH_KEY',         ' Xakm<o xQy rw4EMsLKM-?!T+,PFF})H4lzcW57AF0U@N@< >M%G4Yt>f`z]MON');
define('SECURE_AUTH_KEY',  'LzJ}op]mr|6+![P}Ak:uNdJCJZd>(Hx.-Mh#Tz)pCIU#uGEnfFz|f ;;eU%/U^O~');
define('LOGGED_IN_KEY',    '|i|Ux`9<p-h$aFf(qnT:sDO:D1P^wZ$$/Ra@miTJi9G;ddp_<q}6H1)o|a +&JCM');
define('NONCE_KEY',        '%:R{[P|,s.KuMltH5}cI;/k<Gx~j!f0I)m_sIyu+&NJZ)-iO>z7X>QYR0Z_XnZ@|');
define('AUTH_SALT',        'eZyT)-Naw]F8CwA*VaW#q*|.)g@o}||wf~@C-YSt}(dh_r6EbI#A,y|nU2{B#JBW');
define('SECURE_AUTH_SALT', '!=oLUTXh,QW=H `}`L|9/^4-3 STz},T(w}W<I`.JjPi)<Bmf1v,HpGe}T1:Xt7n');
define('LOGGED_IN_SALT',   '+XSqHc;@Q*K_b|Z?NC[3H!!EONbh.n<+=uKR:>*c(u`g~EJBf#8u#R{mUEZrozmm');
define('NONCE_SALT',       'h`GXHhD>SLWVfg1(1(N{;.V!MoE(SfbA_ksP@&`+AycHcAV$+?@3q+rxV{%^VyKT');

Salting passwords helps against tools which has stored hashed values of
common dictionary strings. The added values makes it harder to crack.

param: string $scheme Authentication scheme (auth, secure_auth, logged_in, nonce)
return: string Salt value

wp_hash( $data, $scheme = 'auth' )   X-Ref
Get hash of given string.

param: string $data   Plain text to hash
param: string $scheme Authentication scheme (auth, secure_auth, logged_in, nonce)
return: string Hash of $data

wp_hash_password( $password )   X-Ref
Create a hash (encrypt) of a plain text password.

For integration with other applications, this function can be overwritten to
instead use the other package password checking algorithm.

param: string $password Plain text user password to hash
return: string The hash string of the password

wp_check_password( $password, $hash, $user_id = '' )   X-Ref
Checks the plaintext password against the encrypted Password.

Maintains compatibility between old version and the new cookie authentication
protocol using PHPass library. The $hash parameter is the encrypted password
and the function compares the plain text password when encrypted similarly
against the already encrypted password to see if they match.

For integration with other applications, this function can be overwritten to
instead use the other package password checking algorithm.

param: string     $password Plaintext user's password
param: string     $hash     Hash of the user's password to check against.
param: string|int $user_id  Optional. User ID.
return: bool False, if the $password does not match the hashed password

wp_generate_password( $length = 12, $special_chars = true, $extra_special_chars = false )   X-Ref
Generates a random password drawn from the defined set of characters.

Uses wp_rand() is used to create passwords with far less predictability
than similar native PHP functions like `rand()` or `mt_rand()`.

param: int  $length              Optional. The length of password to generate. Default 12.
param: bool $special_chars       Optional. Whether to include standard special characters.
param: bool $extra_special_chars Optional. Whether to include other special characters.
return: string The random password.

wp_rand( $min = 0, $max = 0 )   X-Ref
Generates a random number.

param: int $min Lower limit for the generated number
param: int $max Upper limit for the generated number
return: int A random number between min and max

wp_set_password( $password, $user_id )   X-Ref
Updates the user's password with a new encrypted one.

For integration with other applications, this function can be overwritten to
instead use the other package password checking algorithm.

Please note: This function should be used sparingly and is really only meant for single-time
application. Leveraging this improperly in a plugin or theme could result in an endless loop
of password resets if precautions are not taken to ensure it does not execute on every page load.

param: string $password The plaintext new user password
param: int    $user_id  User ID

get_avatar( $id_or_email, $size = 96, $default = '', $alt = '', $args = null )   X-Ref
Retrieve the avatar `<img>` tag for a user, email address, MD5 hash, comment, or post.

param: mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
param: int    $size       Optional. Height and width of the avatar image file in pixels. Default 96.
param: string $default    Optional. URL for the default image or a default type. Accepts '404'
param: string $alt        Optional. Alternative text to use in &lt;img&gt; tag. Default empty.
param: array  $args       {
return: false|string `<img>` tag for the user's avatar. False on failure.

wp_text_diff( $left_string, $right_string, $args = null )   X-Ref
Displays a human readable HTML representation of the difference between two strings.

The Diff is available for getting the changes between versions. The output is
HTML, so the primary use is for displaying the changes. If the two strings
are equivalent, then an empty string will be returned.

The arguments supported and can be changed are listed below.

'title' : Default is an empty string. Titles the diff in a manner compatible
with the output.
'title_left' : Default is an empty string. Change the HTML to the left of the
title.
'title_right' : Default is an empty string. Change the HTML to the right of
the title.

param: string       $left_string  "old" (left) version of string
param: string       $right_string "new" (right) version of string
param: string|array $args         Optional. Change 'title', 'title_left', and 'title_right' defaults.
return: string Empty string if strings are equivalent or HTML with differences.



Generated: Sun Apr 21 08:20:01 2019 Cross-referenced by PHPXref 0.7