WordPress.org
Get WordPress

Make WordPress Core

Changeset 26538


Ignore:
Timestamp:
12/02/2013 08:44:28 PM (10 years ago)
Author:
DrewAPicture
Message:

Inline documentation for hooks in wp-includes/ms-functions.php.

Props ShinichiN, ericlewis, rzen.
Fixes #25598.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/ms-functions.php

    r26368 r26538  
    195195    $user->set_role($role);
    196196
    197     do_action('add_user_to_blog', $user_id, $role, $blog_id);
     197    /**
     198     * Fires immediately after a user is added to a site.
     199     *
     200     * @since MU
     201     *
     202     * @param int    $user_id User ID.
     203     * @param string $role    User role.
     204     * @param int    $blog_id Blog ID.
     205     */
     206    do_action( 'add_user_to_blog', $user_id, $role, $blog_id );
    198207    wp_cache_delete( $user_id, 'users' );
    199208    restore_current_blog();
    … …  
    221230    switch_to_blog($blog_id);
    222231    $user_id = (int) $user_id;
    223     do_action('remove_user_from_blog', $user_id, $blog_id);
     232    /**
     233     * Fires before a user is removed from a site.
     234     *
     235     * @since MU
     236     *
     237     * @param int $user_id User ID.
     238     * @param int $blog_id Blog ID.
     239     */
     240    do_action( 'remove_user_from_blog', $user_id, $blog_id );
    224241
    225242    // If being removed from the primary blog, set a new primary if the user is assigned
    … …  
    402419    }
    403420
     421    /**
     422     * Filter whether an email address is unsafe.
     423     *
     424     * @since 3.5.0
     425     *
     426     * @param bool   $is_email_address_unsafe Whether the email address is "unsafe". Default false.
     427     * @param string $user_email              User email address.
     428     */
    404429    return apply_filters( 'is_email_address_unsafe', $is_email_address_unsafe, $user_email );
    405430}
    … …  
    511536    $result = array('user_name' => $user_name, 'orig_username' => $orig_username, 'user_email' => $user_email, 'errors' => $errors);
    512537
    513     return apply_filters('wpmu_validate_user_signup', $result);
     538    /**
     539     * Filter the validated user registration details.
     540     *
     541     * This does not allow you to override the username or email of the user during
     542     * registration. The values are solely used for validation and error handling.
     543     *
     544     * @since MU
     545     *
     546     * @param array $result {
     547     *     The array of user name, email and the error messages.
     548     *
     549     *     @type string   $user_name     Sanitized and unique username.
     550     *     @type string   $orig_username Original username.
     551     *     @type string   $user_email    User email address.
     552     *     @type WP_Error $errors        WP_Error object containing any errors found.
     553     * }
     554     */
     555    return apply_filters( 'wpmu_validate_user_signup', $result );
    514556}
    515557
    … …  
    552594    }
    553595
    554     // On sub dir installs, Some names are so illegal, only a filter can spring them from jail
    555     if (! is_subdomain_install() )
    556         $illegal_names = array_merge($illegal_names, apply_filters( 'subdirectory_reserved_names', array( 'page', 'comments', 'blog', 'files', 'feed' ) ) );
     596    /*
     597     * On sub dir installs, some names are so illegal, only a filter can
     598     * spring them from jail.
     599     */
     600    if ( ! is_subdomain_install() ) {
     601        $illegal_names = array_merge(
     602            $illegal_names,
     603            /**
     604             * Filter reserved site names on a sub-directory Multisite install.
     605             *
     606             * @since 3.0.0
     607             *
     608             * @param array $subdirectory_reserved_names Array of reserved names.
     609             */
     610            apply_filters( 'subdirectory_reserved_names', array( 'page', 'comments', 'blog', 'files', 'feed' ) )
     611        );
     612    }
    557613
    558614    if ( empty( $blogname ) )
    … …  
    579635        $errors->add('blogname', __('Sorry, site names must have letters too!'));
    580636
     637    /**
     638     * Filter the new site name during registration.
     639     *
     640     * The name is the site's subdomain or the site's subdirectory
     641     * path depending on the network settings.
     642     *
     643     * @since MU
     644     *
     645     * @param string $blogname Site name.
     646     */
    581647    $blogname = apply_filters( 'newblogname', $blogname );
    582648
    … …  
    614680
    615681    $result = array('domain' => $mydomain, 'path' => $path, 'blogname' => $blogname, 'blog_title' => $blog_title, 'user' => $user, 'errors' => $errors);
    616     return apply_filters('wpmu_validate_blog_signup', $result);
     682
     683    /**
     684     * Filter site details and error messages following registration.
     685     *
     686     * @since MU
     687     *
     688     * @param array $result {
     689     *     Array of domain, path, blog name, blog title, user and error messages.
     690     *
     691     *     @type string   $domain     Domain for the site.
     692     *     @type string   $path       Path for the site. Used in subdirectory installs.
     693     *     @type string   $blogname   The unique site name (slug).
     694     *     @type string   $blog_title Blog title.
     695     *     @type string   $user       User email address.
     696     *     @type WP_Error $errors     WP_Error containing any errors found.
     697     * }
     698     */
     699    return apply_filters( 'wpmu_validate_blog_signup', $result );
    617700}
    618701
    … …  
    711794 */
    712795function wpmu_signup_blog_notification( $domain, $path, $title, $user, $user_email, $key, $meta = array() ) {
    713     if ( !apply_filters('wpmu_signup_blog_notification', $domain, $path, $title, $user, $user_email, $key, $meta) )
     796    /**
     797     * Filter whether to bypass the new site email notification.
     798     *
     799     * @since MU
     800     *
     801     * @param string|bool $domain     Site domain.
     802     * @param string      $path       Site path.
     803     * @param string      $title      Site title.
     804     * @param string      $user       User login name.
     805     * @param string      $user_email User email address.
     806     * @param string      $key        Activation key created in wpmu_signup_blog().
     807     * @param array       $meta       By default, contains the requested privacy setting and lang_id.
     808     */
     809    if ( ! apply_filters( 'wpmu_signup_blog_notification', $domain, $path, $title, $user, $user_email, $key, $meta ) ) {
    714810        return false;
     811    }
    715812
    716813    // Send email with activation link.
    … …  
    727824    $message_headers = "From: \"{$from_name}\" <{$admin_email}>\n" . "Content-Type: text/plain; charset=\"" . get_option('blog_charset') . "\"\n";
    728825    $message = sprintf(
     826        /**
     827         * Filter the message content of the new blog notification email.
     828         *
     829         * Content should be formatted for transmission via wp_mail().
     830         *
     831         * @since MU
     832         *
     833         * @param string $content    Content of the notification email.
     834         * @param string $domain     Site domain.
     835         * @param string $path       Site path.
     836         * @param string $title      Site title.
     837         * @param string $user       User login name.
     838         * @param string $user_email User email address.
     839         * @param string $key        Activation key created in wpmu_signup_blog().
     840         * @param array  $meta       By default, contains the requested privacy setting and lang_id.
     841         */
    729842        apply_filters( 'wpmu_signup_blog_notification_email',
    730843            __( "To activate your blog, please click the following link:\n\n%s\n\nAfter you activate, you will receive *another email* with your login.\n\nAfter you activate, you can visit your site here:\n\n%s" ),
    … …  
    737850    // TODO: Don't hard code activation link.
    738851    $subject = sprintf(
     852        /**
     853         * Filter the subject of the new blog notification email.
     854         *
     855         * @since MU
     856         *
     857         * @param string $subject    Subject of the notification email.
     858         * @param string $domain     Site domain.
     859         * @param string $path       Site path.
     860         * @param string $title      Site title.
     861         * @param string $user       User login name.
     862         * @param string $user_email User email address.
     863         * @param string $key        Activation key created in wpmu_signup_blog().
     864         * @param array  $meta       By default, contains the requested privacy setting and lang_id.
     865         */
    739866        apply_filters( 'wpmu_signup_blog_notification_subject',
    740867            __( '[%1$s] Activate %2$s' ),
    … …  
    770897 */
    771898function wpmu_signup_user_notification( $user, $user_email, $key, $meta = array() ) {
    772     if ( !apply_filters('wpmu_signup_user_notification', $user, $user_email, $key, $meta) )
     899    /**
     900     * Filter whether to bypass the email notification for new user sign-up.
     901     *
     902     * @since MU
     903     *
     904     * @param string $user       User login name.
     905     * @param string $user_email User email address.
     906     * @param string $key        Activation key created in wpmu_signup_user().
     907     * @param array  $meta       Signup meta data.
     908     */
     909    if ( ! apply_filters( 'wpmu_signup_user_notification', $user, $user_email, $key, $meta ) )
    773910        return false;
    774911
    … …  
    780917    $message_headers = "From: \"{$from_name}\" <{$admin_email}>\n" . "Content-Type: text/plain; charset=\"" . get_option('blog_charset') . "\"\n";
    781918    $message = sprintf(
     919        /**
     920         * Filter the content of the notification email for new user sign-up.
     921         *
     922         * Content should be formatted for transmission via wp_mail().
     923         *
     924         * @since MU
     925         *
     926         * @param string $content    Content of the notification email.
     927         * @param string $user       User login name.
     928         * @param string $user_email User email address.
     929         * @param string $key        Activation key created in wpmu_signup_user().
     930         * @param array  $meta       Signup meta data.
     931         */
    782932        apply_filters( 'wpmu_signup_user_notification_email',
    783933            __( "To activate your user, please click the following link:\n\n%s\n\nAfter you activate, you will receive *another email* with your login." ),
    … …  
    788938    // TODO: Don't hard code activation link.
    789939    $subject = sprintf(
     940        /**
     941         * Filter the subject of the notification email of new user signup.
     942         *
     943         * @since MU
     944         *
     945         * @param string $subject    Subject of the notification email.
     946         * @param string $user       User login name.
     947         * @param string $user_email User email address.
     948         * @param string $key        Activation key created in wpmu_signup_user().
     949         * @param array  $meta       Signup meta data.
     950         */
    790951        apply_filters( 'wpmu_signup_user_notification_subject',
    791952            __( '[%1$s] Activate %2$s' ),
    … …  
    8551016
    8561017        wpmu_welcome_user_notification( $user_id, $password, $meta );
     1018        /**
     1019         * Fires immediately after a new user is activated.
     1020         *
     1021         * @since MU
     1022         *
     1023         * @param int   $user_id  User ID.
     1024         * @param int   $password User password.
     1025         * @param array $meta     Signup meta data.
     1026         */
    8571027        do_action( 'wpmu_activate_user', $user_id, $password, $meta );
    8581028        return array( 'user_id' => $user_id, 'password' => $password, 'meta' => $meta );
    … …  
    8741044    $wpdb->update( $wpdb->signups, array('active' => 1, 'activated' => $now), array('activation_key' => $key) );
    8751045    wpmu_welcome_notification($blog_id, $user_id, $password, $signup->title, $meta);
    876     do_action('wpmu_activate_blog', $blog_id, $user_id, $password, $signup->title, $meta);
     1046    /**
     1047     * Fires immediately after a site is activated.
     1048     *
     1049     * @since MU
     1050     *
     1051     * @param int    $blog_id       Blog ID.
     1052     * @param int    $user_id       User ID.
     1053     * @param int    $password      User password.
     1054     * @param string $signup_title  Site title.
     1055     * @param array  $meta          Signup meta data.
     1056     */
     1057    do_action( 'wpmu_activate_blog', $blog_id, $user_id, $password, $signup->title, $meta );
    8771058
    8781059    return array('blog_id' => $blog_id, 'user_id' => $user_id, 'password' => $password, 'title' => $signup->title, 'meta' => $meta);
    … …  
    9061087    delete_user_option( $user_id, 'user_level' );
    9071088
     1089    /**
     1090     * Fires immediately after a new user is created.
     1091     *
     1092     * @since MU
     1093     *
     1094     * @param int $user_id User ID.
     1095     */
    9081096    do_action( 'wpmu_new_user', $user_id );
    9091097
    … …  
    9821170
    9831171    restore_current_blog();
     1172    /**
     1173     * Fires immediately after a new site is created.
     1174     *
     1175     * @since MU
     1176     *
     1177     * @param int    $blog_id Blog ID.
     1178     * @param int    $user_id User ID.
     1179     * @param string $domain  Site domain.
     1180     * @param string $path    Site path.
     1181     * @param int    $site_id Site ID. Only relevant on multi-network installs.
     1182     * @param array  $meta    Meta data. Used to set initial site options.
     1183     */
    9841184    do_action( 'wpmu_new_blog', $blog_id, $user_id, $domain, $path, $site_id, $meta );
    9851185
    … …  
    10181218
    10191219Disable these notifications: %4$s' ), $blogname, $siteurl, wp_unslash( $_SERVER['REMOTE_ADDR'] ), $options_site_url);
     1220    /**
     1221     * Filter the message body of the new site activation email sent
     1222     * to the network administrator.
     1223     *
     1224     * @since MU
     1225     *
     1226     * @param string $msg Email body.
     1227     */
    10201228    $msg = apply_filters( 'newblog_notify_siteadmin', $msg );
    10211229
    … …  
    10531261Disable these notifications: %3$s'), $user->user_login, wp_unslash( $_SERVER['REMOTE_ADDR'] ), $options_site_url);
    10541262
     1263    /**
     1264     * Filter the message body of the new user activation email sent
     1265     * to the network administrator.
     1266     *
     1267     * @since MU
     1268     *
     1269     * @param string  $msg  Email body.
     1270     * @param WP_User $user WP_User instance of the new user.
     1271     */
    10551272    $msg = apply_filters( 'newuser_notify_siteadmin', $msg, $user );
    10561273    wp_mail( $email, sprintf(__('New User Registration: %s'), $user->user_login), $msg );
    … …  
    10741291    global $wpdb;
    10751292    $result = $wpdb->get_var( $wpdb->prepare("SELECT blog_id FROM $wpdb->blogs WHERE domain = %s AND path = %s AND site_id = %d", $domain, $path, $site_id) );
     1293    /**
     1294     * Filter whether a blogname is taken.
     1295     *
     1296     * @since 3.5.0
     1297     *
     1298     * @param int|null $result  The blog_id if the blogname exists, null otherwise.
     1299     * @param string   $domain  Domain to be checked.
     1300     * @param string   $path    Path to be checked.
     1301     * @param int      $site_id Site ID. Relevant only on multi-network installs.
     1302     */
    10761303    return apply_filters( 'domain_exists', $result, $domain, $path, $site_id );
    10771304}
    … …  
    12071434    $current_site = get_current_site();
    12081435
    1209     if ( !apply_filters('wpmu_welcome_notification', $blog_id, $user_id, $password, $title, $meta) )
     1436    /**
     1437     * Filter whether to bypass the welcome email after site activation.
     1438     *
     1439     * Returning false disables the welcome email.
     1440     *
     1441     * @since MU
     1442     *
     1443     * @param int|bool $blog_id  Blog ID.
     1444     * @param int      $user_id  User ID.
     1445     * @param string   $password User password.
     1446     * @param string   $title    Site title.
     1447     * @param array    $meta     Signup meta data.
     1448     */
     1449    if ( ! apply_filters( 'wpmu_welcome_notification', $blog_id, $user_id, $password, $title, $meta ) )
    12101450        return false;
    12111451
    … …  
    12351475    $welcome_email = str_replace( 'PASSWORD', $password, $welcome_email );
    12361476
    1237     $welcome_email = apply_filters( 'update_welcome_email', $welcome_email, $blog_id, $user_id, $password, $title, $meta);
     1477    /**
     1478     * Filter the content of the welcome email after site activation.
     1479     *
     1480     * Content should be formatted for transmission via wp_mail().
     1481     *
     1482     * @since MU
     1483     *
     1484     * @param string $welcome_email Message body of the email.
     1485     * @param int    $blog_id       Blog ID.
     1486     * @param int    $user_id       User ID.
     1487     * @param string $password      User password.
     1488     * @param string $title         Site title.
     1489     * @param array  $meta          Signup meta data.
     1490     */
     1491    $welcome_email = apply_filters( 'update_welcome_email', $welcome_email, $blog_id, $user_id, $password, $title, $meta );
    12381492    $admin_email = get_site_option( 'admin_email' );
    12391493
    … …  
    12481502        $current_site->site_name = 'WordPress';
    12491503
    1250     $subject = apply_filters( 'update_welcome_subject', sprintf(__('New %1$s Site: %2$s'), $current_site->site_name, wp_unslash( $title ) ) );
     1504    /**
     1505     * Filter the subject of the welcome email after site activation.
     1506     *
     1507     * @since MU
     1508     *
     1509     * @param string $subject Subject of the email.
     1510     */
     1511    $subject = apply_filters( 'update_welcome_subject', sprintf( __( 'New %1$s Site: %2$s' ), $current_site->site_name, wp_unslash( $title ) ) );
    12511512    wp_mail($user->user_email, $subject, $message, $message_headers);
    12521513    return true;
    … …  
    12711532    $current_site = get_current_site();
    12721533
    1273     if ( !apply_filters('wpmu_welcome_user_notification', $user_id, $password, $meta) )
     1534    /**
     1535     * Filter whether to bypass the welcome email after user activation.
     1536     *
     1537     * Returning false disables the welcome email.
     1538     *
     1539     * @since MU
     1540     *
     1541     * @param int    $user_id  User ID.
     1542     * @param string $password User password.
     1543     * @param array  $meta     Signup meta data.
     1544     */
     1545    if ( ! apply_filters( 'wpmu_welcome_user_notification', $user_id, $password, $meta ) )
    12741546        return false;
    12751547
    … …  
    12781550    $user = get_userdata( $user_id );
    12791551
    1280     $welcome_email = apply_filters( 'update_welcome_user_email', $welcome_email, $user_id, $password, $meta);
     1552    /**
     1553     * Filter the content of the welcome email after user activation.
     1554     *
     1555     * Content should be formatted for transmission via wp_mail().
     1556     *
     1557     * @since MU
     1558     *
     1559     * @param type   $welcome_email The message body of the account activation success email.
     1560     * @param int    $user_id       User ID.
     1561     * @param string $password      User password.
     1562     * @param array  $meta          Signup meta data.
     1563     */
     1564    $welcome_email = apply_filters( 'update_welcome_user_email', $welcome_email, $user_id, $password, $meta );
    12811565    $welcome_email = str_replace( 'SITE_NAME', $current_site->site_name, $welcome_email );
    12821566    $welcome_email = str_replace( 'USERNAME', $user->user_login, $welcome_email );
    … …  
    12961580        $current_site->site_name = 'WordPress';
    12971581
    1298     $subject = apply_filters( 'update_welcome_user_subject', sprintf(__('New %1$s User: %2$s'), $current_site->site_name, $user->user_login) );
     1582    /**
     1583     * Filter the subject of the welcome email after user activation.
     1584     *
     1585     * @since MU
     1586     *
     1587     * @param string $subject Subject of the email.
     1588     */
     1589    $subject = apply_filters( 'update_welcome_user_subject', sprintf( __( 'New %1$s User: %2$s' ), $current_site->site_name, $user->user_login) );
    12991590    wp_mail($user->user_email, $subject, $message, $message_headers);
    13001591    return true;
    … …  
    16181909 */
    16191910function maybe_redirect_404() {
     1911    /**
     1912     * Filter the redirect URL for 404s on the main site.
     1913     *
     1914     * The filter is only evaluated if the NOBLOGREDIRECT constant is defined.
     1915     *
     1916     * @since 3.0.0
     1917     *
     1918     * @param string $no_blog_redirect The redirect URL defined in NOBLOGREDIRECT.
     1919     */
    16201920    if ( is_main_site() && is_404() && defined( 'NOBLOGREDIRECT' ) && ( $destination = apply_filters( 'blog_redirect_404', NOBLOGREDIRECT ) ) ) {
    16211921        if ( $destination == '%siteurl%' )
    … …  
    16691969    if ( is_array( $details ) ) {
    16701970        $result = add_user_to_blog( $blog_id, $details[ 'user_id' ], $details[ 'role' ] );
    1671         do_action( 'added_existing_user', $details[ 'user_id' ], $result );
     1971        /**
     1972         * Fires immediately after an existing user is added to a site.
     1973         *
     1974         * @since MU
     1975         *
     1976         * @param int   $user_id User ID.
     1977         * @param mixed $result  True on success or a WP_Error object if the user doesn't exist.
     1978         */
     1979        do_action( 'added_existing_user', $details['user_id'], $result );
    16721980    }
    16731981    return $result;
    … …  
    18942202
    18952203    /**
    1896      * Filter the decision to update network user and site counts in real time.
     2204     * Filter whether to update network site or user counts when a new site is created.
    18972205     *
    18982206     * @since 3.7.0
    18992207     *
    1900      * @param bool   $small_network Based on wp_is_large_network( $context ).
     2208     * @see wp_is_large_network()
     2209     *
     2210     * @param bool   $small_network Whether the network is considered small.
    19012211     * @param string $context       Context. Either 'users' or 'sites'.
    19022212     */
    … …  
    19202230    $is_small_network = ! wp_is_large_network( 'users' );
    19212231
    1922     /**
    1923      * Filter the decision to update network user and site counts in real time.
    1924      *
    1925      * @since 3.7.0
    1926      *
    1927      * @param bool   $small_network Based on wp_is_large_network( $context ).
    1928      * @param string $context       Context. Either 'users' or 'sites'.
    1929      */
     2232    /** This filter is documented in wp-includes/ms-functions.php */
    19302233    if ( ! apply_filters( 'enable_live_network_counts', $is_small_network, 'users' ) )
    19312234        return;
    … …  
    19662269 */
    19672270function get_space_used() {
    1968     // Allow for an alternative way of tracking storage space used
     2271    /**
     2272     * Filter the amount of storage space used by the current site.
     2273     *
     2274     * @since 3.5.0
     2275     *
     2276     * @param int|bool $space_used The amount of used space, in megabytes. Default false.
     2277     */
    19692278    $space_used = apply_filters( 'pre_get_space_used', false );
    19702279    if ( false === $space_used ) {
    … …  
    19922301        $space_allowed = 100;
    19932302
     2303    /**
     2304     * Filter the upload quota for the current site.
     2305     *
     2306     * @since 3.7.0
     2307     *
     2308     * @param int $space_allowed Upload quota in megabytes for the current blog.
     2309     */
    19942310    return apply_filters( 'get_space_allowed', $space_allowed );
    19952311}
    … …  
    20542370    if ( 'users' == $using ) {
    20552371        $count = get_user_count();
     2372        /**
     2373         * Filter whether the network is considered large.
     2374         *
     2375         * @since 3.3.0
     2376         *
     2377         * @param bool   $is_large_network Whether the network has more than 10000 users or sites.
     2378         * @param string $component        The component to count. Accepts 'users', or 'sites'.
     2379         * @param int    $count            The count of items for the component.
     2380         */
    20562381        return apply_filters( 'wp_is_large_network', $count > 10000, 'users', $count );
    20572382    }
    20582383
    20592384    $count = get_blog_count();
     2385    /** This filter is documented in wp-includes/ms-functions.php */
    20602386    return apply_filters( 'wp_is_large_network', $count > 10000, 'sites', $count );
    20612387}
Note: See TracChangeset for help on using the changeset viewer.