[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

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

Multisite WordPress API

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

Defines 60 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()
  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.

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.

param: int $user_id The unique ID of the user
return: WP_Site|void The blog object

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.

param: int|null $network_id ID of the network. Default is the current network.
return: int Number of active sites on the 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.

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

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.

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    User role.
return: true|WP_Error True on success or a WP_Error object if the user doesn't exist

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.

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.
return: true|WP_Error True on success or a WP_Error object if the user doesn't exist.

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

param: int $blog_id ID of the source blog.
param: int $post_id ID of the desired post.
return: string The post's permalink.

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 '/'.

param: string $domain Website domain.
param: string $path   Optional. Not required for subdomain installations. Default '/'.
return: int 0 if no blog found, otherwise the ID of the matching blog.

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.

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

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.

param: string $user_name  The login name provided by the user.
param: string $user_email The email provided by the user.
return: array {

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.

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

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

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.

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.

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.
return: bool

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.

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.
return: bool

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).

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

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

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'}).

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.
return: int|false Returns false on failure, or int $user_id on success.

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 '/'.

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.
return: int|WP_Error Returns WP_Error object on failure, the new site ID on success.

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.

param: WP_Site|int $blog_id    The new site's object or ID.
param: string      $deprecated Not used.
return: bool

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.

param: int $user_id The new user's ID.
return: bool

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.

param: string $domain     The domain to be checked.
param: string $path       The path to be checked.
param: int    $network_id Optional. Network ID. Only relevant on multi-network installations.
return: int|null The site ID if the site name exists, null otherwise.

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.

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.
return: bool Whether the email notification was sent.

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.

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

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.

param: int    $user_id  User ID.
param: string $password User password.
param: array  $meta     Optional. Signup meta data. Default empty array.
return: bool

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.

return: WP_Network The current 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.

param: int $user_id User ID.
return: array Contains the blog_id, post_id, post_date_gmt, and post_gmt_ts.

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.

param: array $mimes
return: array

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.

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.

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'.

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

param: array|string $deprecated Not used.
return: string[] {

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

param: array $upload An array of information about the newly-uploaded file.
return: string|array If the upload is under the size limit, $upload is returned. Otherwise returns an error message.

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


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

param: array $result
return: array

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


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.


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().

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

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.

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.

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.

param: string|WP_User $user Optional. Defaults to current user. WP_User object,
return: bool

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.

param: int $old_value The old public 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.

return: bool

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

param: string $text
return: string

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

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

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

Useful as a filter.

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

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


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

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.

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.

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.

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.

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.

return: int Used space in megabytes.

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

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.

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.

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.

param: int $size Upload size limit in bytes.
return: int 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.

param: string   $using      'sites' or 'users'. Default is 'sites'.
param: int|null $network_id ID of the network. Default is the current network.
return: bool True if the network meets the criteria for large. False otherwise.

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

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.

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.

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 08:20:01 2024 Cross-referenced by PHPXref