[ Index ]

PHP Cross Reference of WordPress

title

Body

[close]

/wp-includes/ -> ms-functions.php (summary)

Multisite WordPress API

File Size: 2979 lines (94 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 61 functions

  get_sitestats()
  get_active_blog_for_user()
  get_blog_count()
  get_blog_post()
  add_user_to_blog()
  remove_user_from_blog()
  get_blog_permalink()
  get_blog_id_from_url()
  is_email_address_unsafe()
  wpmu_validate_user_signup()
  wpmu_validate_blog_signup()
  wpmu_signup_blog()
  wpmu_signup_user()
  wpmu_signup_blog_notification()
  wpmu_signup_user_notification()
  wpmu_activate_signup()
  wp_delete_signup_on_user_delete()
  wpmu_create_user()
  wpmu_create_blog()
  newblog_notify_siteadmin()
  newuser_notify_siteadmin()
  domain_exists()
  wpmu_welcome_notification()
  wpmu_new_site_admin_notification()
  wpmu_welcome_user_notification()
  get_current_site()
  get_most_recent_post_of_user()
  check_upload_mimes()
  update_posts_count()
  wpmu_log_new_registrations()
  global_terms()
  redirect_this_site()
  upload_is_file_too_big()
  signup_nonce_fields()
  signup_nonce_check()
  maybe_redirect_404()
  maybe_add_existing_user_to_blog()
  add_existing_user_to_blog()
  add_new_user_to_blog()
  fix_phpmailer_messageid()
  is_user_spammy()
  update_blog_public()
  users_can_register_signup_filter()
  welcome_user_msg_filter()
  force_ssl_content()
  filter_SSL()
  wp_schedule_update_network_counts()
  wp_update_network_counts()
  wp_maybe_update_network_site_counts()
  wp_maybe_update_network_user_counts()
  wp_update_network_site_counts()
  wp_update_network_user_counts()
  get_space_used()
  get_space_allowed()
  get_upload_space_available()
  is_upload_space_available()
  upload_size_limit_filter()
  wp_is_large_network()
  get_subdirectory_reserved_names()
  update_network_option_new_admin_email()
  wp_network_admin_email_change_notification()

Functions
Functions that are not part of a class:

get_sitestats()   X-Ref
Gets the network's site and user counts.

since: MU (3.0.0)
return: int[] {

get_active_blog_for_user( $user_id )   X-Ref
Gets one of a user's active blogs.

Returns the user's primary blog, if they have one and
it is active. If it's inactive, function returns another
active blog of the user. If none are found, the user
is added as a Subscriber to the Dashboard Blog and that blog
is returned.

since: MU (3.0.0)
return: WP_Site|void The blog object
param: int $user_id The unique ID of the user

get_blog_count( $network_id = null )   X-Ref
Gets the number of active sites on the installation.

The count is cached and updated twice daily. This is not a live count.

since: MU (3.0.0)
since: 3.7.0 The `$network_id` parameter has been deprecated.
since: 4.8.0 The `$network_id` parameter is now being used.
return: int Number of active sites on the network.
param: int|null $network_id ID of the network. Default is the current network.

get_blog_post( $blog_id, $post_id )   X-Ref
Gets a blog post from any site on the network.

This function is similar to get_post(), except that it can retrieve a post
from any site on the network, not just the current site.

since: MU (3.0.0)
return: WP_Post|null WP_Post object on success, null on failure
param: int $blog_id ID of the blog.
param: int $post_id ID of the post being looked for.

add_user_to_blog( $blog_id, $user_id, $role )   X-Ref
Adds a user to a blog, along with specifying the user's role.

Use the {@see 'add_user_to_blog'} action to fire an event when users are added to a blog.

since: MU (3.0.0)
return: true|WP_Error True on success or a WP_Error object if the user doesn't exist
param: int    $blog_id ID of the blog the user is being added to.
param: int    $user_id ID of the user being added.
param: string $role    The role you want the user to have.

remove_user_from_blog( $user_id, $blog_id = 0, $reassign = 0 )   X-Ref
Removes a user from a blog.

Use the {@see 'remove_user_from_blog'} action to fire an event when
users are removed from a blog.

Accepts an optional `$reassign` parameter, if you want to
reassign the user's blog posts to another user upon removal.

since: MU (3.0.0)
return: true|WP_Error True on success or a WP_Error object if the user doesn't exist.
param: int $user_id  ID of the user being removed.
param: int $blog_id  Optional. ID of the blog the user is being removed from. Default 0.
param: int $reassign Optional. ID of the user to whom to reassign posts. Default 0.

get_blog_permalink( $blog_id, $post_id )   X-Ref
Gets the permalink for a post on another blog.

since: MU (3.0.0) 1.0
return: string The post's permalink
param: int $blog_id ID of the source blog.
param: int $post_id ID of the desired post.

get_blog_id_from_url( $domain, $path = '/' )   X-Ref
Gets a blog's numeric ID from its URL.

On a subdirectory installation like example.com/blog1/,
$domain will be the root 'example.com' and $path the
subdirectory '/blog1/'. With subdomains like blog1.example.com,
$domain is 'blog1.example.com' and $path is '/'.

since: MU (3.0.0)
return: int 0 if no blog found, otherwise the ID of the matching blog
param: string $domain
param: string $path   Optional. Not required for subdomain installations.

is_email_address_unsafe( $user_email )   X-Ref
Checks an email address against a list of banned domains.

This function checks against the Banned Email Domains list
at wp-admin/network/settings.php. The check is only run on
self-registrations; user creation at wp-admin/network/users.php
bypasses this check.

since: MU (3.0.0)
return: bool True when the email address is banned, false otherwise.
param: string $user_email The email provided by the user at registration.

wpmu_validate_user_signup( $user_name, $user_email )   X-Ref
Sanitizes and validates data required for a user sign-up.

Verifies the validity and uniqueness of user names and user email addresses,
and checks email addresses against allowed and disallowed domains provided by
administrators.

The {@see 'wpmu_validate_user_signup'} hook provides an easy way to modify the sign-up
process. The value $result, which is passed to the hook, contains both the user-provided
info and the error messages created by the function. {@see 'wpmu_validate_user_signup'}
allows you to process the data in any way you'd like, and unset the relevant errors if
necessary.

since: MU (3.0.0)
return: array {
param: string $user_name  The login name provided by the user.
param: string $user_email The email provided by the user.

wpmu_validate_blog_signup( $blogname, $blog_title, $user = '' )   X-Ref
Processes new site registrations.

Checks the data provided by the user during blog signup. Verifies
the validity and uniqueness of blog paths and domains.

This function prevents the current user from registering a new site
with a blogname equivalent to another user's login name. Passing the
$user parameter to the function, where $user is the other user, is
effectively an override of this limitation.

Filter {@see 'wpmu_validate_blog_signup'} if you want to modify
the way that WordPress validates new site signups.

since: MU (3.0.0)
return: array {
param: string         $blogname   The blog name provided by the user. Must be unique.
param: string         $blog_title The blog title provided by the user.
param: WP_User|string $user       Optional. The user object to check against the new site name.

wpmu_signup_blog( $domain, $path, $title, $user, $user_email, $meta = array()   X-Ref
Records site signup information for future activation.

since: MU (3.0.0)
param: string $domain     The requested domain.
param: string $path       The requested path.
param: string $title      The requested site title.
param: string $user       The user's requested login name.
param: string $user_email The user's email address.
param: array  $meta       Optional. Signup meta data. By default, contains the requested privacy setting and lang_id.

wpmu_signup_user( $user, $user_email, $meta = array()   X-Ref
Records user signup information for future activation.

This function is used when user registration is open but
new site registration is not.

since: MU (3.0.0)
param: string $user       The user's requested login name.
param: string $user_email The user's email address.
param: array  $meta       Optional. Signup meta data. Default empty array.

wpmu_signup_blog_notification( $domain, $path, $title, $user_login, $user_email, $key, $meta = array()   X-Ref
Sends a confirmation request email to a user when they sign up for a new site. The new site will not become active
until the confirmation link is clicked.

This is the notification function used when site registration
is enabled.

Filter {@see 'wpmu_signup_blog_notification'} to bypass this function or
replace it with your own notification behavior.

Filter {@see 'wpmu_signup_blog_notification_email'} and
{@see 'wpmu_signup_blog_notification_subject'} to change the content
and subject line of the email sent to newly registered users.

since: MU (3.0.0)
return: bool
param: string $domain     The new blog domain.
param: string $path       The new blog path.
param: string $title      The site title.
param: string $user_login The user's login name.
param: string $user_email The user's email address.
param: string $key        The activation key created in wpmu_signup_blog()
param: array  $meta       Optional. Signup meta data. By default, contains the requested privacy setting and lang_id.

wpmu_signup_user_notification( $user_login, $user_email, $key, $meta = array()   X-Ref
Sends a confirmation request email to a user when they sign up for a new user account (without signing up for a site
at the same time). The user account will not become active until the confirmation link is clicked.

This is the notification function used when no new site has
been requested.

Filter {@see 'wpmu_signup_user_notification'} to bypass this function or
replace it with your own notification behavior.

Filter {@see 'wpmu_signup_user_notification_email'} and
{@see 'wpmu_signup_user_notification_subject'} to change the content
and subject line of the email sent to newly registered users.

since: MU (3.0.0)
return: bool
param: string $user_login The user's login name.
param: string $user_email The user's email address.
param: string $key        The activation key created in wpmu_signup_user()
param: array  $meta       Optional. Signup meta data. Default empty array.

wpmu_activate_signup( $key )   X-Ref
Activates a signup.

Hook to {@see 'wpmu_activate_user'} or {@see 'wpmu_activate_blog'} for events
that should happen only when users or sites are self-created (since
those actions are not called when users and sites are created
by a Super Admin).

since: MU (3.0.0)
return: array|WP_Error An array containing information about the activated user and/or blog
param: string $key The activation key provided to the user.

wp_delete_signup_on_user_delete( $id, $reassign, $user )   X-Ref
Deletes an associated signup entry when a user is deleted from the database.

since: 5.5.0
param: int      $id       ID of the user to delete.
param: int|null $reassign ID of the user to reassign posts and links to.
param: WP_User  $user     User object.

wpmu_create_user( $user_name, $password, $email )   X-Ref
Creates a user.

This function runs when a user self-registers as well as when
a Super Admin creates a new user. Hook to {@see 'wpmu_new_user'} for events
that should affect all new users, but only on Multisite (otherwise
use {@see 'user_register'}).

since: MU (3.0.0)
return: int|false Returns false on failure, or int $user_id on success
param: string $user_name The new user's login name.
param: string $password  The new user's password.
param: string $email     The new user's email address.

wpmu_create_blog( $domain, $path, $title, $user_id, $options = array()   X-Ref
Creates a site.

This function runs when a user self-registers a new site as well
as when a Super Admin creates a new site. Hook to {@see 'wpmu_new_blog'}
for events that should affect all new sites.

On subdirectory installations, $domain is the same as the main site's
domain, and the path is the subdirectory name (eg 'example.com'
and '/blog1/'). On subdomain installations, $domain is the new subdomain +
root domain (eg 'blog1.example.com'), and $path is '/'.

since: MU (3.0.0)
return: int|WP_Error Returns WP_Error object on failure, the new site ID on success.
param: string $domain     The new site's domain.
param: string $path       The new site's path.
param: string $title      The new site's title.
param: int    $user_id    The user ID of the new site's admin.
param: array  $options    Optional. Array of key=>value pairs used to set initial site options.
param: int    $network_id Optional. Network ID. Only relevant on multi-network installations.

newblog_notify_siteadmin( $blog_id, $deprecated = '' )   X-Ref
Notifies the network admin that a new site has been activated.

Filter {@see 'newblog_notify_siteadmin'} to change the content of
the notification email.

since: MU (3.0.0)
since: 5.1.0 $blog_id now supports input from the {@see 'wp_initialize_site'} action.
return: bool
param: WP_Site|int $blog_id    The new site's object or ID.
param: string      $deprecated Not used.

newuser_notify_siteadmin( $user_id )   X-Ref
Notifies the network admin that a new user has been activated.

Filter {@see 'newuser_notify_siteadmin'} to change the content of
the notification email.

since: MU (3.0.0)
return: bool
param: int $user_id The new user's ID.

domain_exists( $domain, $path, $network_id = 1 )   X-Ref
Checks whether a site name is already taken.

The name is the site's subdomain or the site's subdirectory
path depending on the network settings.

Used during the new site registration process to ensure
that each site name is unique.

since: MU (3.0.0)
return: int|null The site ID if the site name exists, null otherwise.
param: string $domain     The domain to be checked.
param: string $path       The path to be checked.
param: int    $network_id Optional. Network ID. Relevant only on multi-network installations.

wpmu_welcome_notification( $blog_id, $user_id, $password, $title, $meta = array()   X-Ref
Notifies the site administrator that their site activation was successful.

Filter {@see 'wpmu_welcome_notification'} to disable or bypass.

Filter {@see 'update_welcome_email'} and {@see 'update_welcome_subject'} to
modify the content and subject line of the notification email.

since: MU (3.0.0)
return: bool Whether the email notification was sent.
param: int    $blog_id  Site ID.
param: int    $user_id  User ID.
param: string $password User password, or "N/A" if the user account is not new.
param: string $title    Site title.
param: array  $meta     Optional. Signup meta data. By default, contains the requested privacy setting and lang_id.

wpmu_new_site_admin_notification( $site_id, $user_id )   X-Ref
Notifies the Multisite network administrator that a new site was created.

Filter {@see 'send_new_site_email'} to disable or bypass.

Filter {@see 'new_site_email'} to filter the contents.

since: 5.6.0
return: bool Whether the email notification was sent.
param: int $site_id Site ID of the new site.
param: int $user_id User ID of the administrator of the new site.

wpmu_welcome_user_notification( $user_id, $password, $meta = array()   X-Ref
Notifies a user that their account activation has been successful.

Filter {@see 'wpmu_welcome_user_notification'} to disable or bypass.

Filter {@see 'update_welcome_user_email'} and {@see 'update_welcome_user_subject'} to
modify the content and subject line of the notification email.

since: MU (3.0.0)
return: bool
param: int    $user_id  User ID.
param: string $password User password.
param: array  $meta     Optional. Signup meta data. Default empty array.

get_current_site()   X-Ref
Gets the current network.

Returns an object containing the 'id', 'domain', 'path', and 'site_name'
properties of the network being viewed.

since: MU (3.0.0)
return: WP_Network

get_most_recent_post_of_user( $user_id )   X-Ref
Gets a user's most recent post.

Walks through each of a user's blogs to find the post with
the most recent post_date_gmt.

since: MU (3.0.0)
return: array Contains the blog_id, post_id, post_date_gmt, and post_gmt_ts
param: int $user_id

check_upload_mimes( $mimes )   X-Ref
Checks an array of MIME types against a list of allowed types.

WordPress ships with a set of allowed upload filetypes,
which is defined in wp-includes/functions.php in
get_allowed_mime_types(). This function is used to filter
that list against the filetypes allowed provided by Multisite
Super Admins at wp-admin/network/settings.php.

since: MU (3.0.0)
return: array
param: array $mimes

update_posts_count( $deprecated = '' )   X-Ref
Updates a blog's post count.

WordPress MS stores a blog's post count as an option so as
to avoid extraneous COUNTs when a blog's details are fetched
with get_site(). This function is called when posts are published
or unpublished to make sure the count stays current.

since: MU (3.0.0)
param: string $deprecated Not used.

wpmu_log_new_registrations( $blog_id, $user_id )   X-Ref
Logs the user email, IP, and registration date of a new site.

since: MU (3.0.0)
since: 5.1.0 Parameters now support input from the {@see 'wp_initialize_site'} action.
param: WP_Site|int $blog_id The new site's object or ID.
param: int|array   $user_id User ID, or array of arguments including 'user_id'.

global_terms( $term_id, $deprecated = '' )   X-Ref
Maintains a canonical list of terms by syncing terms created for each blog with the global terms table.

since: 3.0.0
return: int An ID from the global terms table mapped from $term_id.
param: int    $term_id    An ID for a term on the current blog.
param: string $deprecated Not used.

redirect_this_site( $deprecated = '' )   X-Ref
Ensures that the current site's domain is listed in the allowed redirect host list.

since: MU (3.0.0)
return: string[] {
param: array|string $deprecated Not used.

upload_is_file_too_big( $upload )   X-Ref
Checks whether an upload is too big.

since: MU (3.0.0)
return: string|array If the upload is under the size limit, $upload is returned. Otherwise returns an error message.
param: array $upload

signup_nonce_fields()   X-Ref
Adds a nonce field to the signup page.

since: MU (3.0.0)

signup_nonce_check( $result )   X-Ref
Processes the signup nonce created in signup_nonce_fields().

since: MU (3.0.0)
return: array
param: array $result

maybe_redirect_404()   X-Ref
Corrects 404 redirects when NOBLOGREDIRECT is defined.

since: MU (3.0.0)

maybe_add_existing_user_to_blog()   X-Ref
Adds a new user to a blog by visiting /newbloguser/{key}/.

This will only work when the user's details are saved as an option
keyed as 'new_user_{key}', where '{key}' is a hash generated for the user to be
added, as when a user is invited through the regular WP Add User interface.

since: MU (3.0.0)

add_existing_user_to_blog( $details = false )   X-Ref
Adds a user to a blog based on details from maybe_add_existing_user_to_blog().

since: MU (3.0.0)
return: true|WP_Error|void True on success or a WP_Error object if the user doesn't exist
param: array|false $details {

add_new_user_to_blog( $user_id, $password, $meta )   X-Ref
Adds a newly created user to the appropriate blog

To add a user in general, use add_user_to_blog(). This function
is specifically hooked into the {@see 'wpmu_activate_user'} action.

since: MU (3.0.0)
param: int    $user_id  User ID.
param: string $password User password. Ignored.
param: array  $meta     Signup meta data.

fix_phpmailer_messageid( $phpmailer )   X-Ref
Corrects From host on outgoing mail to match the site domain

since: MU (3.0.0)
param: PHPMailer $phpmailer The PHPMailer instance (passed by reference).

is_user_spammy( $user = null )   X-Ref
Determines whether a user is marked as a spammer, based on user login.

since: MU (3.0.0)
return: bool
param: string|WP_User $user Optional. Defaults to current user. WP_User object,

update_blog_public( $old_value, $value )   X-Ref
Updates this blog's 'public' setting in the global blogs table.

Public blogs have a setting of 1, private blogs are 0.

since: MU (3.0.0)
param: int $old_value
param: int $value     The new public value

users_can_register_signup_filter()   X-Ref
Determines whether users can self-register, based on Network settings.

since: MU (3.0.0)
return: bool

welcome_user_msg_filter( $text )   X-Ref
Ensures that the welcome message is not empty. Currently unused.

since: MU (3.0.0)
return: string
param: string $text

force_ssl_content( $force = '' )   X-Ref
Determines whether to force SSL on content.

since: 2.8.5
return: bool True if forced, false if not forced.
param: bool $force

filter_SSL( $url )   X-Ref
Formats a URL to use https.

Useful as a filter.

since: 2.8.5
return: string URL with https as the scheme
param: string $url URL

wp_schedule_update_network_counts()   X-Ref
Schedules update of the network-wide counts for the current network.

since: 3.1.0

wp_update_network_counts( $network_id = null )   X-Ref
Updates the network-wide counts for the current network.

since: 3.1.0
since: 4.8.0 The `$network_id` parameter has been added.
param: int|null $network_id ID of the network. Default is the current network.

wp_maybe_update_network_site_counts( $network_id = null )   X-Ref
Updates the count of sites for the current network.

If enabled through the {@see 'enable_live_network_counts'} filter, update the sites count
on a network when a site is created or its status is updated.

since: 3.7.0
since: 4.8.0 The `$network_id` parameter has been added.
param: int|null $network_id ID of the network. Default is the current network.

wp_maybe_update_network_user_counts( $network_id = null )   X-Ref
Updates the network-wide users count.

If enabled through the {@see 'enable_live_network_counts'} filter, update the users count
on a network when a user is created or its status is updated.

since: 3.7.0
since: 4.8.0 The `$network_id` parameter has been added.
param: int|null $network_id ID of the network. Default is the current network.

wp_update_network_site_counts( $network_id = null )   X-Ref
Updates the network-wide site count.

since: 3.7.0
since: 4.8.0 The `$network_id` parameter has been added.
param: int|null $network_id ID of the network. Default is the current network.

wp_update_network_user_counts( $network_id = null )   X-Ref
Updates the network-wide user count.

since: 3.7.0
since: 4.8.0 The `$network_id` parameter has been added.
since: 6.0.0 This function is now a wrapper for wp_update_user_counts().
param: int|null $network_id ID of the network. Default is the current network.

get_space_used()   X-Ref
Returns the space used by the current site.

since: 3.5.0
return: int Used space in megabytes.

get_space_allowed()   X-Ref
Returns the upload quota for the current blog.

since: MU (3.0.0)
return: int Quota in megabytes

get_upload_space_available()   X-Ref
Determines if there is any upload space left in the current blog's quota.

since: 3.0.0
return: int of upload space available in bytes

is_upload_space_available()   X-Ref
Determines if there is any upload space left in the current blog's quota.

since: 3.0.0
return: bool True if space is available, false otherwise.

upload_size_limit_filter( $size )   X-Ref
Filters the maximum upload file size allowed, in bytes.

since: 3.0.0
return: int Upload size limit in bytes.
param: int $size Upload size limit in bytes.

wp_is_large_network( $using = 'sites', $network_id = null )   X-Ref
Determines whether or not we have a large network.

The default criteria for a large network is either more than 10,000 users or more than 10,000 sites.
Plugins can alter this criteria using the {@see 'wp_is_large_network'} filter.

since: 3.3.0
since: 4.8.0 The `$network_id` parameter has been added.
return: bool True if the network meets the criteria for large. False otherwise.
param: string   $using      'sites or 'users'. Default is 'sites'.
param: int|null $network_id ID of the network. Default is the current network.

get_subdirectory_reserved_names()   X-Ref
Retrieves a list of reserved site on a sub-directory Multisite installation.

since: 4.4.0
return: string[] Array of reserved names.

update_network_option_new_admin_email( $old_value, $value )   X-Ref
Sends a confirmation request email when a change of network admin email address is attempted.

The new network admin address will not become active until confirmed.

since: 4.9.0
param: string $old_value The old network admin email address.
param: string $value     The proposed new network admin email address.

wp_network_admin_email_change_notification( $option_name, $new_email, $old_email, $network_id )   X-Ref
Sends an email to the old network admin email address when the network admin email address changes.

since: 4.9.0
param: string $option_name The relevant database option name.
param: string $new_email   The new network admin email address.
param: string $old_email   The old network admin email address.
param: int    $network_id  ID of the network.



Generated: Tue Mar 19 01:00:02 2024 Cross-referenced by PHPXref 0.7.1