/** * Locale API: WP_Locale_Switcher class * * @package WordPress * @subpackage i18n * @since 4.7.0 */ /** * Core class used for switching locales. * * @since 4.7.0 */ #[AllowDynamicProperties] class WP_Locale_Switcher { /** * Locale switching stack. * * @since 6.2.0 * @var array */ private $stack = array(); /** * Original locale. * * @since 4.7.0 * @var string */ private $original_locale; /** * Holds all available languages. * * @since 4.7.0 * @var string[] An array of language codes (file names without the .mo extension). */ private $available_languages; /** * Constructor. * * Stores the original locale as well as a list of all available languages. * * @since 4.7.0 */ public function __construct() { $this->original_locale = determine_locale(); $this->available_languages = array_merge( array( 'en_US' ), get_available_languages() ); } /** * Initializes the locale switcher. * * Hooks into the {@see 'locale'} and {@see 'determine_locale'} filters * to change the locale on the fly. * * @since 4.7.0 */ public function init() { add_filter( 'locale', array( $this, 'filter_locale' ) ); add_filter( 'determine_locale', array( $this, 'filter_locale' ) ); } /** * Switches the translations according to the given locale. * * @since 4.7.0 * * @param string $locale The locale to switch to. * @param int|false $user_id Optional. User ID as context. Default false. * @return bool True on success, false on failure. */ public function switch_to_locale( $locale, $user_id = false ) { $current_locale = determine_locale(); if ( $current_locale === $locale ) { return false; } if ( ! in_array( $locale, $this->available_languages, true ) ) { return false; } $this->stack[] = array( $locale, $user_id ); $this->change_locale( $locale ); /** * Fires when the locale is switched. * * @since 4.7.0 * @since 6.2.0 The `$user_id` parameter was added. * * @param string $locale The new locale. * @param false|int $user_id User ID for context if available. */ do_action( 'switch_locale', $locale, $user_id ); return true; } /** * Switches the translations according to the given user's locale. * * @since 6.2.0 * * @param int $user_id User ID. * @return bool True on success, false on failure. */ public function switch_to_user_locale( $user_id ) { $locale = get_user_locale( $user_id ); return $this->switch_to_locale( $locale, $user_id ); } /** * Restores the translations according to the previous locale. * * @since 4.7.0 * * @return string|false Locale on success, false on failure. */ public function restore_previous_locale() { $previous_locale = array_pop( $this->stack ); if ( null === $previous_locale ) { // The stack is empty, bail. return false; } $entry = end( $this->stack ); $locale = is_array( $entry ) ? $entry[0] : false; if ( ! $locale ) { // There's nothing left in the stack: go back to the original locale. $locale = $this->original_locale; } $this->change_locale( $locale ); /** * Fires when the locale is restored to the previous one. * * @since 4.7.0 * * @param string $locale The new locale. * @param string $previous_locale The previous locale. */ do_action( 'restore_previous_locale', $locale, $previous_locale[0] ); return $locale; } /** * Restores the translations according to the original locale. * * @since 4.7.0 * * @return string|false Locale on success, false on failure. */ public function restore_current_locale() { if ( empty( $this->stack ) ) { return false; } $this->stack = array( array( $this->original_locale, false ) ); return $this->restore_previous_locale(); } /** * Whether switch_to_locale() is in effect. * * @since 4.7.0 * * @return bool True if the locale has been switched, false otherwise. */ public function is_switched() { return ! empty( $this->stack ); } /** * Returns the locale currently switched to. * * @since 6.2.0 * * @return string|false Locale if the locale has been switched, false otherwise. */ public function get_switched_locale() { $entry = end( $this->stack ); if ( $entry ) { return $entry[0]; } return false; } /** * Returns the user ID related to the currently switched locale. * * @since 6.2.0 * * @return int|false User ID if set and if the locale has been switched, false otherwise. */ public function get_switched_user_id() { $entry = end( $this->stack ); if ( $entry ) { return $entry[1]; } return false; } /** * Filters the locale of the WordPress installation. * * @since 4.7.0 * * @param string $locale The locale of the WordPress installation. * @return string The locale currently being switched to. */ public function filter_locale( $locale ) { $switched_locale = $this->get_switched_locale(); if ( $switched_locale ) { return $switched_locale; } return $locale; } /** * Load translations for a given locale. * * When switching to a locale, translations for this locale must be loaded from scratch. * * @since 4.7.0 * * @global Mo[] $l10n An array of all currently loaded text domains. * * @param string $locale The locale to load translations for. */ private function load_translations( $locale ) { global $l10n; $domains = $l10n ? array_keys( $l10n ) : array(); load_default_textdomain( $locale ); foreach ( $domains as $domain ) { // The default text domain is handled by `load_default_textdomain()`. if ( 'default' === $domain ) { continue; } /* * Unload current text domain but allow them to be reloaded * after switching back or to another locale. */ unload_textdomain( $domain, true ); get_translations_for_domain( $domain ); } } /** * Changes the site's locale to the given one. * * Loads the translations, changes the global `$wp_locale` object and updates * all post type labels. * * @since 4.7.0 * * @global WP_Locale $wp_locale WordPress date and time locale object. * * @param string $locale The locale to change to. */ private function change_locale( $locale ) { global $wp_locale; $this->load_translations( $locale ); $wp_locale = new WP_Locale(); WP_Translation_Controller::get_instance()->set_locale( $locale ); /** * Fires when the locale is switched to or restored. * * @since 4.7.0 * * @param string $locale The new locale. */ do_action( 'change_locale', $locale ); } } /** * Core User Role & Capabilities API * * @package WordPress * @subpackage Users */ /** * Maps a capability to the primitive capabilities required of the given user to * satisfy the capability being checked. * * This function also accepts an ID of an object to map against if the capability is a meta capability. Meta * capabilities such as `edit_post` and `edit_user` are capabilities used by this function to map to primitive * capabilities that a user or role requires, such as `edit_posts` and `edit_others_posts`. * * Example usage: * * map_meta_cap( 'edit_posts', $user->ID ); * map_meta_cap( 'edit_post', $user->ID, $post->ID ); * map_meta_cap( 'edit_post_meta', $user->ID, $post->ID, $meta_key ); * * This function does not check whether the user has the required capabilities, * it just returns what the required capabilities are. * * @since 2.0.0 * @since 4.9.6 Added the `export_others_personal_data`, `erase_others_personal_data`, * and `manage_privacy_options` capabilities. * @since 5.1.0 Added the `update_php` capability. * @since 5.2.0 Added the `resume_plugin` and `resume_theme` capabilities. * @since 5.3.0 Formalized the existing and already documented `...$args` parameter * by adding it to the function signature. * @since 5.7.0 Added the `create_app_password`, `list_app_passwords`, `read_app_password`, * `edit_app_password`, `delete_app_passwords`, `delete_app_password`, * and `update_https` capabilities. * @since 6.7.0 Added the `edit_block_binding` capability. * * @global array $post_type_meta_caps Used to get post type meta capabilities. * * @param string $cap Capability being checked. * @param int $user_id User ID. * @param mixed ...$args Optional further parameters, typically starting with an object ID. * @return string[] Primitive capabilities required of the user. */ function map_meta_cap( $cap, $user_id, ...$args ) { $caps = array(); switch ( $cap ) { case 'remove_user': // In multisite the user must be a super admin to remove themselves. if ( isset( $args[0] ) && $user_id === (int) $args[0] && ! is_super_admin( $user_id ) ) { $caps[] = 'do_not_allow'; } else { $caps[] = 'remove_users'; } break; case 'promote_user': case 'add_users': $caps[] = 'promote_users'; break; case 'edit_user': case 'edit_users': // Allow user to edit themselves. if ( 'edit_user' === $cap && isset( $args[0] ) && $user_id === (int) $args[0] ) { break; } // In multisite the user must have manage_network_users caps. If editing a super admin, the user must be a super admin. if ( is_multisite() && ( ( ! is_super_admin( $user_id ) && 'edit_user' === $cap && is_super_admin( $args[0] ) ) || ! user_can( $user_id, 'manage_network_users' ) ) ) { $caps[] = 'do_not_allow'; } else { $caps[] = 'edit_users'; // edit_user maps to edit_users. } break; case 'delete_post': case 'delete_page': if ( ! isset( $args[0] ) ) { if ( 'delete_post' === $cap ) { /* translators: %s: Capability name. */ $message = __( 'When checking for the %s capability, you must always check it against a specific post.' ); } else { /* translators: %s: Capability name. */ $message = __( 'When checking for the %s capability, you must always check it against a specific page.' ); } _doing_it_wrong( __FUNCTION__, sprintf( $message, '' . $cap . '' ), '6.1.0' ); $caps[] = 'do_not_allow'; break; } $post = get_post( $args[0] ); if ( ! $post ) { $caps[] = 'do_not_allow'; break; } if ( 'revision' === $post->post_type ) { $caps[] = 'do_not_allow'; break; } if ( (int) get_option( 'page_for_posts' ) === $post->ID || (int) get_option( 'page_on_front' ) === $post->ID ) { $caps[] = 'manage_options'; break; } $post_type = get_post_type_object( $post->post_type ); if ( ! $post_type ) { /* translators: 1: Post type, 2: Capability name. */ $message = __( 'The post type %1$s is not registered, so it may not be reliable to check the capability %2$s against a post of that type.' ); _doing_it_wrong( __FUNCTION__, sprintf( $message, '' . $post->post_type . '', '' . $cap . '' ), '4.4.0' ); $caps[] = 'edit_others_posts'; break; } if ( ! $post_type->map_meta_cap ) { $caps[] = $post_type->cap->$cap; // Prior to 3.1 we would re-call map_meta_cap here. if ( 'delete_post' === $cap ) { $cap = $post_type->cap->$cap; } break; } // If the post author is set and the user is the author... if ( $post->post_author && $user_id === (int) $post->post_author ) { // If the post is published or scheduled... if ( in_array( $post->post_status, array( 'publish', 'future' ), true ) ) { $caps[] = $post_type->cap->delete_published_posts; } elseif ( 'trash' === $post->post_status ) { $status = get_post_meta( $post->ID, '_wp_trash_meta_status', true ); if ( in_array( $status, array( 'publish', 'future' ), true ) ) { $caps[] = $post_type->cap->delete_published_posts; } else { $caps[] = $post_type->cap->delete_posts; } } else { // If the post is draft... $caps[] = $post_type->cap->delete_posts; } } else { // The user is trying to edit someone else's post. $caps[] = $post_type->cap->delete_others_posts; // The post is published or scheduled, extra cap required. if ( in_array( $post->post_status, array( 'publish', 'future' ), true ) ) { $caps[] = $post_type->cap->delete_published_posts; } elseif ( 'private' === $post->post_status ) { $caps[] = $post_type->cap->delete_private_posts; } } /* * Setting the privacy policy page requires `manage_privacy_options`, * so deleting it should require that too. */ if ( (int) get_option( 'wp_page_for_privacy_policy' ) === $post->ID ) { $caps = array_merge( $caps, map_meta_cap( 'manage_privacy_options', $user_id ) ); } break; /* * edit_post breaks down to edit_posts, edit_published_posts, or * edit_others_posts. */ case 'edit_post': case 'edit_page': if ( ! isset( $args[0] ) ) { if ( 'edit_post' === $cap ) { /* translators: %s: Capability name. */ $message = __( 'When checking for the %s capability, you must always check it against a specific post.' ); } else { /* translators: %s: Capability name. */ $message = __( 'When checking for the %s capability, you must always check it against a specific page.' ); } _doing_it_wrong( __FUNCTION__, sprintf( $message, '' . $cap . '' ), '6.1.0' ); $caps[] = 'do_not_allow'; break; } $post = get_post( $args[0] ); if ( ! $post ) { $caps[] = 'do_not_allow'; break; } if ( 'revision' === $post->post_type ) { $post = get_post( $post->post_parent ); if ( ! $post ) { $caps[] = 'do_not_allow'; break; } } $post_type = get_post_type_object( $post->post_type ); if ( ! $post_type ) { /* translators: 1: Post type, 2: Capability name. */ $message = __( 'The post type %1$s is not registered, so it may not be reliable to check the capability %2$s against a post of that type.' ); _doing_it_wrong( __FUNCTION__, sprintf( $message, '' . $post->post_type . '', '' . $cap . '' ), '4.4.0' ); $caps[] = 'edit_others_posts'; break; } if ( ! $post_type->map_meta_cap ) { $caps[] = $post_type->cap->$cap; // Prior to 3.1 we would re-call map_meta_cap here. if ( 'edit_post' === $cap ) { $cap = $post_type->cap->$cap; } break; } // If the post author is set and the user is the author... if ( $post->post_author && $user_id === (int) $post->post_author ) { // If the post is published or scheduled... if ( in_array( $post->post_status, array( 'publish', 'future' ), true ) ) { $caps[] = $post_type->cap->edit_published_posts; } elseif ( 'trash' === $post->post_status ) { $status = get_post_meta( $post->ID, '_wp_trash_meta_status', true ); if ( in_array( $status, array( 'publish', 'future' ), true ) ) { $caps[] = $post_type->cap->edit_published_posts; } else { $caps[] = $post_type->cap->edit_posts; } } else { // If the post is draft... $caps[] = $post_type->cap->edit_posts; } } else { // The user is trying to edit someone else's post. $caps[] = $post_type->cap->edit_others_posts; // The post is published or scheduled, extra cap required. if ( in_array( $post->post_status, array( 'publish', 'future' ), true ) ) { $caps[] = $post_type->cap->edit_published_posts; } elseif ( 'private' === $post->post_status ) { $caps[] = $post_type->cap->edit_private_posts; } } /* * Setting the privacy policy page requires `manage_privacy_options`, * so editing it should require that too. */ if ( (int) get_option( 'wp_page_for_privacy_policy' ) === $post->ID ) { $caps = array_merge( $caps, map_meta_cap( 'manage_privacy_options', $user_id ) ); } break; case 'read_post': case 'read_page': if ( ! isset( $args[0] ) ) { if ( 'read_post' === $cap ) { /* translators: %s: Capability name. */ $message = __( 'When checking for the %s capability, you must always check it against a specific post.' ); } else { /* translators: %s: Capability name. */ $message = __( 'When checking for the %s capability, you must always check it against a specific page.' ); } _doing_it_wrong( __FUNCTION__, sprintf( $message, '' . $cap . '' ), '6.1.0' ); $caps[] = 'do_not_allow'; break; } $post = get_post( $args[0] ); if ( ! $post ) { $caps[] = 'do_not_allow'; break; } if ( 'revision' === $post->post_type ) { $post = get_post( $post->post_parent ); if ( ! $post ) { $caps[] = 'do_not_allow'; break; } } $post_type = get_post_type_object( $post->post_type ); if ( ! $post_type ) { /* translators: 1: Post type, 2: Capability name. */ $message = __( 'The post type %1$s is not registered, so it may not be reliable to check the capability %2$s against a post of that type.' ); _doing_it_wrong( __FUNCTION__, sprintf( $message, '' . $post->post_type . '', '' . $cap . '' ), '4.4.0' ); $caps[] = 'edit_others_posts'; break; } if ( ! $post_type->map_meta_cap ) { $caps[] = $post_type->cap->$cap; // Prior to 3.1 we would re-call map_meta_cap here. if ( 'read_post' === $cap ) { $cap = $post_type->cap->$cap; } break; } $status_obj = get_post_status_object( get_post_status( $post ) ); if ( ! $status_obj ) { /* translators: 1: Post status, 2: Capability name. */ $message = __( 'The post status %1$s is not registered, so it may not be reliable to check the capability %2$s against a post with that status.' ); _doing_it_wrong( __FUNCTION__, sprintf( $message, '' . get_post_status( $post ) . '', '' . $cap . '' ), '5.4.0' ); $caps[] = 'edit_others_posts'; break; } if ( $status_obj->public ) { $caps[] = $post_type->cap->read; break; } if ( $post->post_author && $user_id === (int) $post->post_author ) { $caps[] = $post_type->cap->read; } elseif ( $status_obj->private ) { $caps[] = $post_type->cap->read_private_posts; } else { $caps = map_meta_cap( 'edit_post', $user_id, $post->ID ); } break; case 'publish_post': if ( ! isset( $args[0] ) ) { /* translators: %s: Capability name. */ $message = __( 'When checking for the %s capability, you must always check it against a specific post.' ); _doing_it_wrong( __FUNCTION__, sprintf( $message, '' . $cap . '' ), '6.1.0' ); $caps[] = 'do_not_allow'; break; } $post = get_post( $args[0] ); if ( ! $post ) { $caps[] = 'do_not_allow'; break; } $post_type = get_post_type_object( $post->post_type ); if ( ! $post_type ) { /* translators: 1: Post type, 2: Capability name. */ $message = __( 'The post type %1$s is not registered, so it may not be reliable to check the capability %2$s against a post of that type.' ); _doing_it_wrong( __FUNCTION__, sprintf( $message, '' . $post->post_type . '', '' . $cap . '' ), '4.4.0' ); $caps[] = 'edit_others_posts'; break; } $caps[] = $post_type->cap->publish_posts; break; case 'edit_post_meta': case 'delete_post_meta': case 'add_post_meta': case 'edit_comment_meta': case 'delete_comment_meta': case 'add_comment_meta': case 'edit_term_meta': case 'delete_term_meta': case 'add_term_meta': case 'edit_user_meta': case 'delete_user_meta': case 'add_user_meta': $object_type = explode( '_', $cap )[1]; if ( ! isset( $args[0] ) ) { if ( 'post' === $object_type ) { /* translators: %s: Capability name. */ $message = __( 'When checking for the %s capability, you must always check it against a specific post.' ); } elseif ( 'comment' === $object_type ) { /* translators: %s: Capability name. */ $message = __( 'When checking for the %s capability, you must always check it against a specific comment.' ); } elseif ( 'term' === $object_type ) { /* translators: %s: Capability name. */ $message = __( 'When checking for the %s capability, you must always check it against a specific term.' ); } else { /* translators: %s: Capability name. */ $message = __( 'When checking for the %s capability, you must always check it against a specific user.' ); } _doing_it_wrong( __FUNCTION__, sprintf( $message, '' . $cap . '' ), '6.1.0' ); $caps[] = 'do_not_allow'; break; } $object_id = (int) $args[0]; $object_subtype = get_object_subtype( $object_type, $object_id ); if ( empty( $object_subtype ) ) { $caps[] = 'do_not_allow'; break; } $caps = map_meta_cap( "edit_{$object_type}", $user_id, $object_id ); $meta_key = isset( $args[1] ) ? $args[1] : false; if ( $meta_key ) { $allowed = ! is_protected_meta( $meta_key, $object_type ); if ( ! empty( $object_subtype ) && has_filter( "auth_{$object_type}_meta_{$meta_key}_for_{$object_subtype}" ) ) { /** * Filters whether the user is allowed to edit a specific meta key of a specific object type and subtype. * * The dynamic portions of the hook name, `$object_type`, `$meta_key`, * and `$object_subtype`, refer to the metadata object type (comment, post, term or user), * the meta key value, and the object subtype respectively. * * @since 4.9.8 * * @param bool $allowed Whether the user can add the object meta. Default false. * @param string $meta_key The meta key. * @param int $object_id Object ID. * @param int $user_id User ID. * @param string $cap Capability name. * @param string[] $caps Array of the user's capabilities. */ $allowed = apply_filters( "auth_{$object_type}_meta_{$meta_key}_for_{$object_subtype}", $allowed, $meta_key, $object_id, $user_id, $cap, $caps ); } else { /** * Filters whether the user is allowed to edit a specific meta key of a specific object type. * * Return true to have the mapped meta caps from `edit_{$object_type}` apply. * * The dynamic portion of the hook name, `$object_type` refers to the object type being filtered. * The dynamic portion of the hook name, `$meta_key`, refers to the meta key passed to map_meta_cap(). * * @since 3.3.0 As `auth_post_meta_{$meta_key}`. * @since 4.6.0 * * @param bool $allowed Whether the user can add the object meta. Default false. * @param string $meta_key The meta key. * @param int $object_id Object ID. * @param int $user_id User ID. * @param string $cap Capability name. * @param string[] $caps Array of the user's capabilities. */ $allowed = apply_filters( "auth_{$object_type}_meta_{$meta_key}", $allowed, $meta_key, $object_id, $user_id, $cap, $caps ); } if ( ! empty( $object_subtype ) ) { /** * Filters whether the user is allowed to edit meta for specific object types/subtypes. * * Return true to have the mapped meta caps from `edit_{$object_type}` apply. * * The dynamic portion of the hook name, `$object_type` refers to the object type being filtered. * The dynamic portion of the hook name, `$object_subtype` refers to the object subtype being filtered. * The dynamic portion of the hook name, `$meta_key`, refers to the meta key passed to map_meta_cap(). * * @since 4.6.0 As `auth_post_{$post_type}_meta_{$meta_key}`. * @since 4.7.0 Renamed from `auth_post_{$post_type}_meta_{$meta_key}` to * `auth_{$object_type}_{$object_subtype}_meta_{$meta_key}`. * @deprecated 4.9.8 Use {@see 'auth_{$object_type}_meta_{$meta_key}_for_{$object_subtype}'} instead. * * @param bool $allowed Whether the user can add the object meta. Default false. * @param string $meta_key The meta key. * @param int $object_id Object ID. * @param int $user_id User ID. * @param string $cap Capability name. * @param string[] $caps Array of the user's capabilities. */ $allowed = apply_filters_deprecated( "auth_{$object_type}_{$object_subtype}_meta_{$meta_key}", array( $allowed, $meta_key, $object_id, $user_id, $cap, $caps ), '4.9.8', "auth_{$object_type}_meta_{$meta_key}_for_{$object_subtype}" ); } if ( ! $allowed ) { $caps[] = $cap; } } break; case 'edit_comment': if ( ! isset( $args[0] ) ) { /* translators: %s: Capability name. */ $message = __( 'When checking for the %s capability, you must always check it against a specific comment.' ); _doing_it_wrong( __FUNCTION__, sprintf( $message, '' . $cap . '' ), '6.1.0' ); $caps[] = 'do_not_allow'; break; } $comment = get_comment( $args[0] ); if ( ! $comment ) { $caps[] = 'do_not_allow'; break; } $post = get_post( $comment->comment_post_ID ); /* * If the post doesn't exist, we have an orphaned comment. * Fall back to the edit_posts capability, instead. */ if ( $post ) { $caps = map_meta_cap( 'edit_post', $user_id, $post->ID ); } else { $caps = map_meta_cap( 'edit_posts', $user_id ); } break; case 'unfiltered_upload': if ( defined( 'ALLOW_UNFILTERED_UPLOADS' ) && ALLOW_UNFILTERED_UPLOADS && ( ! is_multisite() || is_super_admin( $user_id ) ) ) { $caps[] = $cap; } else { $caps[] = 'do_not_allow'; } break; case 'edit_css': case 'unfiltered_html': // Disallow unfiltered_html for all users, even admins and super admins. if ( defined( 'DISALLOW_UNFILTERED_HTML' ) && DISALLOW_UNFILTERED_HTML ) { $caps[] = 'do_not_allow'; } elseif ( is_multisite() && ! is_super_admin( $user_id ) ) { $caps[] = 'do_not_allow'; } else { $caps[] = 'unfiltered_html'; } break; case 'edit_files': case 'edit_plugins': case 'edit_themes': // Disallow the file editors. if ( defined( 'DISALLOW_FILE_EDIT' ) && DISALLOW_FILE_EDIT ) { $caps[] = 'do_not_allow'; } elseif ( ! wp_is_file_mod_allowed( 'capability_edit_themes' ) ) { $caps[] = 'do_not_allow'; } elseif ( is_multisite() && ! is_super_admin( $user_id ) ) { $caps[] = 'do_not_allow'; } else { $caps[] = $cap; } break; case 'update_plugins': case 'delete_plugins': case 'install_plugins': case 'upload_plugins': case 'update_themes': case 'delete_themes': case 'install_themes': case 'upload_themes': case 'update_core': /* * Disallow anything that creates, deletes, or updates core, plugin, or theme files. * Files in uploads are excepted. */ if ( ! wp_is_file_mod_allowed( 'capability_update_core' ) ) { $caps[] = 'do_not_allow'; } elseif ( is_multisite() && ! is_super_admin( $user_id ) ) { $caps[] = 'do_not_allow'; } elseif ( 'upload_themes' === $cap ) { $caps[] = 'install_themes'; } elseif ( 'upload_plugins' === $cap ) { $caps[] = 'install_plugins'; } else { $caps[] = $cap; } break; case 'install_languages': case 'update_languages': if ( ! wp_is_file_mod_allowed( 'can_install_language_pack' ) ) { $caps[] = 'do_not_allow'; } elseif ( is_multisite() && ! is_super_admin( $user_id ) ) { $caps[] = 'do_not_allow'; } else { $caps[] = 'install_languages'; } break; case 'activate_plugins': case 'deactivate_plugins': case 'activate_plugin': case 'deactivate_plugin': $caps[] = 'activate_plugins'; if ( is_multisite() ) { // update_, install_, and delete_ are handled above with is_super_admin(). $menu_perms = get_site_option( 'menu_items', array() ); if ( empty( $menu_perms['plugins'] ) ) { $caps[] = 'manage_network_plugins'; } } break; case 'resume_plugin': $caps[] = 'resume_plugins'; break; case 'resume_theme': $caps[] = 'resume_themes'; break; case 'delete_user': case 'delete_users': // If multisite only super admins can delete users. if ( is_multisite() && ! is_super_admin( $user_id ) ) { $caps[] = 'do_not_allow'; } else { $caps[] = 'delete_users'; // delete_user maps to delete_users. } break; case 'create_users': if ( ! is_multisite() ) { $caps[] = $cap; } elseif ( is_super_admin( $user_id ) || get_site_option( 'add_new_users' ) ) { $caps[] = $cap; } else { $caps[] = 'do_not_allow'; } break; case 'manage_links': if ( get_option( 'link_manager_enabled' ) ) { $caps[] = $cap; } else { $caps[] = 'do_not_allow'; } break; case 'customize': $caps[] = 'edit_theme_options'; break; case 'delete_site': if ( is_multisite() ) { $caps[] = 'manage_options'; } else { $caps[] = 'do_not_allow'; } break; case 'edit_term': case 'delete_term': case 'assign_term': if ( ! isset( $args[0] ) ) { /* translators: %s: Capability name. */ $message = __( 'When checking for the %s capability, you must always check it against a specific term.' ); _doing_it_wrong( __FUNCTION__, sprintf( $message, '' . $cap . '' ), '6.1.0' ); $caps[] = 'do_not_allow'; break; } $term_id = (int) $args[0]; $term = get_term( $term_id ); if ( ! $term || is_wp_error( $term ) ) { $caps[] = 'do_not_allow'; break; } $tax = get_taxonomy( $term->taxonomy ); if ( ! $tax ) { $caps[] = 'do_not_allow'; break; } if ( 'delete_term' === $cap && ( (int) get_option( 'default_' . $term->taxonomy ) === $term->term_id || (int) get_option( 'default_term_' . $term->taxonomy ) === $term->term_id ) ) { $caps[] = 'do_not_allow'; break; } $taxo_cap = $cap . 's'; $caps = map_meta_cap( $tax->cap->$taxo_cap, $user_id, $term_id ); break; case 'manage_post_tags': case 'edit_categories': case 'edit_post_tags': case 'delete_categories': case 'delete_post_tags': $caps[] = 'manage_categories'; break; case 'assign_categories': case 'assign_post_tags': $caps[] = 'edit_posts'; break; case 'create_sites': case 'delete_sites': case 'manage_network': case 'manage_sites': case 'manage_network_users': case 'manage_network_plugins': case 'manage_network_themes': case 'manage_network_options': case 'upgrade_network': $caps[] = $cap; break; case 'setup_network': if ( is_multisite() ) { $caps[] = 'manage_network_options'; } else { $caps[] = 'manage_options'; } break; case 'update_php': if ( is_multisite() && ! is_super_admin( $user_id ) ) { $caps[] = 'do_not_allow'; } else { $caps[] = 'update_core'; } break; case 'update_https': if ( is_multisite() && ! is_super_admin( $user_id ) ) { $caps[] = 'do_not_allow'; } else { $caps[] = 'manage_options'; $caps[] = 'update_core'; } break; case 'export_others_personal_data': case 'erase_others_personal_data': case 'manage_privacy_options': $caps[] = is_multisite() ? 'manage_network' : 'manage_options'; break; case 'create_app_password': case 'list_app_passwords': case 'read_app_password': case 'edit_app_password': case 'delete_app_passwords': case 'delete_app_password': $caps = map_meta_cap( 'edit_user', $user_id, $args[0] ); break; case 'edit_block_binding': $block_editor_context = $args[0]; if ( isset( $block_editor_context->post ) ) { $object_id = $block_editor_context->post->ID; } /* * If the post ID is null, check if the context is the site editor. * Fall back to the edit_theme_options in that case. */ if ( ! isset( $object_id ) ) { if ( ! isset( $block_editor_context->name ) || 'core/edit-site' !== $block_editor_context->name ) { $caps[] = 'do_not_allow'; break; } $caps = map_meta_cap( 'edit_theme_options', $user_id ); break; } $object_subtype = get_object_subtype( 'post', (int) $object_id ); if ( empty( $object_subtype ) ) { $caps[] = 'do_not_allow'; break; } $post_type_object = get_post_type_object( $object_subtype ); // Initialize empty array if it doesn't exist. if ( ! isset( $post_type_object->capabilities ) ) { $post_type_object->capabilities = array(); } $post_type_capabilities = get_post_type_capabilities( $post_type_object ); $caps = map_meta_cap( $post_type_capabilities->edit_post, $user_id, $object_id ); break; default: // Handle meta capabilities for custom post types. global $post_type_meta_caps; if ( isset( $post_type_meta_caps[ $cap ] ) ) { return map_meta_cap( $post_type_meta_caps[ $cap ], $user_id, ...$args ); } // Block capabilities map to their post equivalent. $block_caps = array( 'edit_blocks', 'edit_others_blocks', 'publish_blocks', 'read_private_blocks', 'delete_blocks', 'delete_private_blocks', 'delete_published_blocks', 'delete_others_blocks', 'edit_private_blocks', 'edit_published_blocks', ); if ( in_array( $cap, $block_caps, true ) ) { $cap = str_replace( '_blocks', '_posts', $cap ); } // If no meta caps match, return the original cap. $caps[] = $cap; } /** * Filters the primitive capabilities required of the given user to satisfy the * capability being checked. * * @since 2.8.0 * * @param string[] $caps Primitive capabilities required of the user. * @param string $cap Capability being checked. * @param int $user_id The user ID. * @param array $args Adds context to the capability check, typically * starting with an object ID. */ return apply_filters( 'map_meta_cap', $caps, $cap, $user_id, $args ); } /** * Returns whether the current user has the specified capability. * * This function also accepts an ID of an object to check against if the capability is a meta capability. Meta * capabilities such as `edit_post` and `edit_user` are capabilities used by the `map_meta_cap()` function to * map to primitive capabilities that a user or role has, such as `edit_posts` and `edit_others_posts`. * * Example usage: * * current_user_can( 'edit_posts' ); * current_user_can( 'edit_post', $post->ID ); * current_user_can( 'edit_post_meta', $post->ID, $meta_key ); * * While checking against particular roles in place of a capability is supported * in part, this practice is discouraged as it may produce unreliable results. * * Note: Will always return true if the current user is a super admin, unless specifically denied. * * @since 2.0.0 * @since 5.3.0 Formalized the existing and already documented `...$args` parameter * by adding it to the function signature. * @since 5.8.0 Converted to wrapper for the user_can() function. * * @see WP_User::has_cap() * @see map_meta_cap() * * @param string $capability Capability name. * @param mixed ...$args Optional further parameters, typically starting with an object ID. * @return bool Whether the current user has the given capability. If `$capability` is a meta cap and `$object_id` is * passed, whether the current user has the given meta capability for the given object. */ function current_user_can( $capability, ...$args ) { return user_can( wp_get_current_user(), $capability, ...$args ); } /** * Returns whether the current user has the specified capability for a given site. * * This function also accepts an ID of an object to check against if the capability is a meta capability. Meta * capabilities such as `edit_post` and `edit_user` are capabilities used by the `map_meta_cap()` function to * map to primitive capabilities that a user or role has, such as `edit_posts` and `edit_others_posts`. * * This function replaces the current_user_can_for_blog() function. * * Example usage: * * current_user_can_for_site( $site_id, 'edit_posts' ); * current_user_can_for_site( $site_id, 'edit_post', $post->ID ); * current_user_can_for_site( $site_id, 'edit_post_meta', $post->ID, $meta_key ); * * @since 6.7.0 * * @param int $site_id Site ID. * @param string $capability Capability name. * @param mixed ...$args Optional further parameters, typically starting with an object ID. * @return bool Whether the user has the given capability. */ function current_user_can_for_site( $site_id, $capability, ...$args ) { $switched = is_multisite() ? switch_to_blog( $site_id ) : false; $can = current_user_can( $capability, ...$args ); if ( $switched ) { restore_current_blog(); } return $can; } /** * Returns whether the author of the supplied post has the specified capability. * * This function also accepts an ID of an object to check against if the capability is a meta capability. Meta * capabilities such as `edit_post` and `edit_user` are capabilities used by the `map_meta_cap()` function to * map to primitive capabilities that a user or role has, such as `edit_posts` and `edit_others_posts`. * * Example usage: * * author_can( $post, 'edit_posts' ); * author_can( $post, 'edit_post', $post->ID ); * author_can( $post, 'edit_post_meta', $post->ID, $meta_key ); * * @since 2.9.0 * @since 5.3.0 Formalized the existing and already documented `...$args` parameter * by adding it to the function signature. * * @param int|WP_Post $post Post ID or post object. * @param string $capability Capability name. * @param mixed ...$args Optional further parameters, typically starting with an object ID. * @return bool Whether the post author has the given capability. */ function author_can( $post, $capability, ...$args ) { $post = get_post( $post ); if ( ! $post ) { return false; } $author = get_userdata( $post->post_author ); if ( ! $author ) { return false; } return $author->has_cap( $capability, ...$args ); } /** * Returns whether a particular user has the specified capability. * * This function also accepts an ID of an object to check against if the capability is a meta capability. Meta * capabilities such as `edit_post` and `edit_user` are capabilities used by the `map_meta_cap()` function to * map to primitive capabilities that a user or role has, such as `edit_posts` and `edit_others_posts`. * * Example usage: * * user_can( $user->ID, 'edit_posts' ); * user_can( $user->ID, 'edit_post', $post->ID ); * user_can( $user->ID, 'edit_post_meta', $post->ID, $meta_key ); * * @since 3.1.0 * @since 5.3.0 Formalized the existing and already documented `...$args` parameter * by adding it to the function signature. * * @param int|WP_User $user User ID or object. * @param string $capability Capability name. * @param mixed ...$args Optional further parameters, typically starting with an object ID. * @return bool Whether the user has the given capability. */ function user_can( $user, $capability, ...$args ) { if ( ! is_object( $user ) ) { $user = get_userdata( $user ); } if ( empty( $user ) ) { // User is logged out, create anonymous user object. $user = new WP_User( 0 ); $user->init( new stdClass() ); } return $user->has_cap( $capability, ...$args ); } /** * Returns whether a particular user has the specified capability for a given site. * * This function also accepts an ID of an object to check against if the capability is a meta capability. Meta * capabilities such as `edit_post` and `edit_user` are capabilities used by the `map_meta_cap()` function to * map to primitive capabilities that a user or role has, such as `edit_posts` and `edit_others_posts`. * * Example usage: * * user_can_for_site( $user->ID, $site_id, 'edit_posts' ); * user_can_for_site( $user->ID, $site_id, 'edit_post', $post->ID ); * user_can_for_site( $user->ID, $site_id, 'edit_post_meta', $post->ID, $meta_key ); * * @since 6.7.0 * * @param int|WP_User $user User ID or object. * @param int $site_id Site ID. * @param string $capability Capability name. * @param mixed ...$args Optional further parameters, typically starting with an object ID. * @return bool Whether the user has the given capability. */ function user_can_for_site( $user, $site_id, $capability, ...$args ) { if ( ! is_object( $user ) ) { $user = get_userdata( $user ); } if ( empty( $user ) ) { // User is logged out, create anonymous user object. $user = new WP_User( 0 ); $user->init( new stdClass() ); } // Check if the blog ID is valid. if ( ! is_numeric( $site_id ) || $site_id <= 0 ) { return false; } $switched = is_multisite() ? switch_to_blog( $site_id ) : false; $can = user_can( $user->ID, $capability, ...$args ); if ( $switched ) { restore_current_blog(); } return $can; } /** * Retrieves the global WP_Roles instance and instantiates it if necessary. * * @since 4.3.0 * * @global WP_Roles $wp_roles WordPress role management object. * * @return WP_Roles WP_Roles global instance if not already instantiated. */ function wp_roles() { global $wp_roles; if ( ! isset( $wp_roles ) ) { $wp_roles = new WP_Roles(); } return $wp_roles; } /** * Retrieves role object. * * @since 2.0.0 * * @param string $role Role name. * @return WP_Role|null WP_Role object if found, null if the role does not exist. */ function get_role( $role ) { return wp_roles()->get_role( $role ); } /** * Adds a role, if it does not exist. * * @since 2.0.0 * * @param string $role Role name. * @param string $display_name Display name for role. * @param bool[] $capabilities List of capabilities keyed by the capability name, * e.g. array( 'edit_posts' => true, 'delete_posts' => false ). * @return WP_Role|void WP_Role object, if the role is added. */ function add_role( $role, $display_name, $capabilities = array() ) { if ( empty( $role ) ) { return; } return wp_roles()->add_role( $role, $display_name, $capabilities ); } /** * Removes a role, if it exists. * * @since 2.0.0 * * @param string $role Role name. */ function remove_role( $role ) { wp_roles()->remove_role( $role ); } /** * Retrieves a list of super admins. * * @since 3.0.0 * * @global array $super_admins * * @return string[] List of super admin logins. */ function get_super_admins() { global $super_admins; if ( isset( $super_admins ) ) { return $super_admins; } else { return get_site_option( 'site_admins', array( 'admin' ) ); } } /** * Determines whether user is a site admin. * * @since 3.0.0 * * @param int|false $user_id Optional. The ID of a user. Defaults to false, to check the current user. * @return bool Whether the user is a site admin. */ function is_super_admin( $user_id = false ) { if ( ! $user_id ) { $user = wp_get_current_user(); } else { $user = get_userdata( $user_id ); } if ( ! $user || ! $user->exists() ) { return false; } if ( is_multisite() ) { $super_admins = get_super_admins(); if ( is_array( $super_admins ) && in_array( $user->user_login, $super_admins, true ) ) { return true; } } elseif ( $user->has_cap( 'delete_users' ) ) { return true; } return false; } /** * Grants Super Admin privileges. * * @since 3.0.0 * * @global array $super_admins * * @param int $user_id ID of the user to be granted Super Admin privileges. * @return bool True on success, false on failure. This can fail when the user is * already a super admin or when the `$super_admins` global is defined. */ function grant_super_admin( $user_id ) { // If global super_admins override is defined, there is nothing to do here. if ( isset( $GLOBALS['super_admins'] ) || ! is_multisite() ) { return false; } /** * Fires before the user is granted Super Admin privileges. * * @since 3.0.0 * * @param int $user_id ID of the user that is about to be granted Super Admin privileges. */ do_action( 'grant_super_admin', $user_id ); // Directly fetch site_admins instead of using get_super_admins(). $super_admins = get_site_option( 'site_admins', array( 'admin' ) ); $user = get_userdata( $user_id ); if ( $user && ! in_array( $user->user_login, $super_admins, true ) ) { $super_admins[] = $user->user_login; update_site_option( 'site_admins', $super_admins ); /** * Fires after the user is granted Super Admin privileges. * * @since 3.0.0 * * @param int $user_id ID of the user that was granted Super Admin privileges. */ do_action( 'granted_super_admin', $user_id ); return true; } return false; } /** * Revokes Super Admin privileges. * * @since 3.0.0 * * @global array $super_admins * * @param int $user_id ID of the user Super Admin privileges to be revoked from. * @return bool True on success, false on failure. This can fail when the user's email * is the network admin email or when the `$super_admins` global is defined. */ function revoke_super_admin( $user_id ) { // If global super_admins override is defined, there is nothing to do here. if ( isset( $GLOBALS['super_admins'] ) || ! is_multisite() ) { return false; } /** * Fires before the user's Super Admin privileges are revoked. * * @since 3.0.0 * * @param int $user_id ID of the user Super Admin privileges are being revoked from. */ do_action( 'revoke_super_admin', $user_id ); // Directly fetch site_admins instead of using get_super_admins(). $super_admins = get_site_option( 'site_admins', array( 'admin' ) ); $user = get_userdata( $user_id ); if ( $user && 0 !== strcasecmp( $user->user_email, get_site_option( 'admin_email' ) ) ) { $key = array_search( $user->user_login, $super_admins, true ); if ( false !== $key ) { unset( $super_admins[ $key ] ); update_site_option( 'site_admins', $super_admins ); /** * Fires after the user's Super Admin privileges are revoked. * * @since 3.0.0 * * @param int $user_id ID of the user Super Admin privileges were revoked from. */ do_action( 'revoked_super_admin', $user_id ); return true; } } return false; } /** * Filters the user capabilities to grant the 'install_languages' capability as necessary. * * A user must have at least one out of the 'update_core', 'install_plugins', and * 'install_themes' capabilities to qualify for 'install_languages'. * * @since 4.9.0 * * @param bool[] $allcaps An array of all the user's capabilities. * @return bool[] Filtered array of the user's capabilities. */ function wp_maybe_grant_install_languages_cap( $allcaps ) { if ( ! empty( $allcaps['update_core'] ) || ! empty( $allcaps['install_plugins'] ) || ! empty( $allcaps['install_themes'] ) ) { $allcaps['install_languages'] = true; } return $allcaps; } /** * Filters the user capabilities to grant the 'resume_plugins' and 'resume_themes' capabilities as necessary. * * @since 5.2.0 * * @param bool[] $allcaps An array of all the user's capabilities. * @return bool[] Filtered array of the user's capabilities. */ function wp_maybe_grant_resume_extensions_caps( $allcaps ) { // Even in a multisite, regular administrators should be able to resume plugins. if ( ! empty( $allcaps['activate_plugins'] ) ) { $allcaps['resume_plugins'] = true; } // Even in a multisite, regular administrators should be able to resume themes. if ( ! empty( $allcaps['switch_themes'] ) ) { $allcaps['resume_themes'] = true; } return $allcaps; } /** * Filters the user capabilities to grant the 'view_site_health_checks' capabilities as necessary. * * @since 5.2.2 * * @param bool[] $allcaps An array of all the user's capabilities. * @param string[] $caps Required primitive capabilities for the requested capability. * @param array $args { * Arguments that accompany the requested capability check. * * @type string $0 Requested capability. * @type int $1 Concerned user ID. * @type mixed ...$2 Optional second and further parameters, typically object ID. * } * @param WP_User $user The user object. * @return bool[] Filtered array of the user's capabilities. */ function wp_maybe_grant_site_health_caps( $allcaps, $caps, $args, $user ) { if ( ! empty( $allcaps['install_plugins'] ) && ( ! is_multisite() || is_super_admin( $user->ID ) ) ) { $allcaps['view_site_health_checks'] = true; } return $allcaps; } return; // Dummy gettext calls to get strings in the catalog. /* translators: User role for administrators. */ _x( 'Administrator', 'User role' ); /* translators: User role for editors. */ _x( 'Editor', 'User role' ); /* translators: User role for authors. */ _x( 'Author', 'User role' ); /* translators: User role for contributors. */ _x( 'Contributor', 'User role' ); /* translators: User role for subscribers. */ _x( 'Subscriber', 'User role' ); /** * User API: WP_Roles class * * @package WordPress * @subpackage Users * @since 4.4.0 */ /** * Core class used to implement a user roles API. * * The role option is simple, the structure is organized by role name that store * the name in value of the 'name' key. The capabilities are stored as an array * in the value of the 'capability' key. * * array ( * 'rolename' => array ( * 'name' => 'rolename', * 'capabilities' => array() * ) * ) * * @since 2.0.0 */ #[AllowDynamicProperties] class WP_Roles { /** * List of roles and capabilities. * * @since 2.0.0 * @var array[] */ public $roles; /** * List of the role objects. * * @since 2.0.0 * @var WP_Role[] */ public $role_objects = array(); /** * List of role names. * * @since 2.0.0 * @var string[] */ public $role_names = array(); /** * Option name for storing role list. * * @since 2.0.0 * @var string */ public $role_key; /** * Whether to use the database for retrieval and storage. * * @since 2.1.0 * @var bool */ public $use_db = true; /** * The site ID the roles are initialized for. * * @since 4.9.0 * @var int */ protected $site_id = 0; /** * Constructor. * * @since 2.0.0 * @since 4.9.0 The `$site_id` argument was added. * * @global array $wp_user_roles Used to set the 'roles' property value. * * @param int $site_id Site ID to initialize roles for. Default is the current site. */ public function __construct( $site_id = null ) { global $wp_user_roles; $this->use_db = empty( $wp_user_roles ); $this->for_site( $site_id ); } /** * Makes private/protected methods readable for backward compatibility. * * @since 4.0.0 * * @param string $name Method to call. * @param array $arguments Arguments to pass when calling. * @return mixed|false Return value of the callback, false otherwise. */ public function __call( $name, $arguments ) { if ( '_init' === $name ) { return $this->_init( ...$arguments ); } return false; } /** * Sets up the object properties. * * The role key is set to the current prefix for the $wpdb object with * 'user_roles' appended. If the $wp_user_roles global is set, then it will * be used and the role option will not be updated or used. * * @since 2.1.0 * @deprecated 4.9.0 Use WP_Roles::for_site() */ protected function _init() { _deprecated_function( __METHOD__, '4.9.0', 'WP_Roles::for_site()' ); $this->for_site(); } /** * Reinitializes the object. * * Recreates the role objects. This is typically called only by switch_to_blog() * after switching wpdb to a new site ID. * * @since 3.5.0 * @deprecated 4.7.0 Use WP_Roles::for_site() */ public function reinit() { _deprecated_function( __METHOD__, '4.7.0', 'WP_Roles::for_site()' ); $this->for_site(); } /** * Adds a role name with capabilities to the list. * * Updates the list of roles, if the role doesn't already exist. * * The capabilities are defined in the following format: `array( 'read' => true )`. * To explicitly deny the role a capability, set the value for that capability to false. * * @since 2.0.0 * * @param string $role Role name. * @param string $display_name Role display name. * @param bool[] $capabilities Optional. List of capabilities keyed by the capability name, * e.g. `array( 'edit_posts' => true, 'delete_posts' => false )`. * Default empty array. * @return WP_Role|void WP_Role object, if the role is added. */ public function add_role( $role, $display_name, $capabilities = array() ) { if ( empty( $role ) || isset( $this->roles[ $role ] ) ) { return; } $this->roles[ $role ] = array( 'name' => $display_name, 'capabilities' => $capabilities, ); if ( $this->use_db ) { update_option( $this->role_key, $this->roles, true ); } $this->role_objects[ $role ] = new WP_Role( $role, $capabilities ); $this->role_names[ $role ] = $display_name; return $this->role_objects[ $role ]; } /** * Removes a role by name. * * @since 2.0.0 * * @param string $role Role name. */ public function remove_role( $role ) { if ( ! isset( $this->role_objects[ $role ] ) ) { return; } unset( $this->role_objects[ $role ] ); unset( $this->role_names[ $role ] ); unset( $this->roles[ $role ] ); if ( $this->use_db ) { update_option( $this->role_key, $this->roles ); } if ( get_option( 'default_role' ) === $role ) { update_option( 'default_role', 'subscriber' ); } } /** * Adds a capability to role. * * @since 2.0.0 * * @param string $role Role name. * @param string $cap Capability name. * @param bool $grant Optional. Whether role is capable of performing capability. * Default true. */ public function add_cap( $role, $cap, $grant = true ) { if ( ! isset( $this->roles[ $role ] ) ) { return; } $this->roles[ $role ]['capabilities'][ $cap ] = $grant; if ( $this->use_db ) { update_option( $this->role_key, $this->roles ); } } /** * Removes a capability from role. * * @since 2.0.0 * * @param string $role Role name. * @param string $cap Capability name. */ public function remove_cap( $role, $cap ) { if ( ! isset( $this->roles[ $role ] ) ) { return; } unset( $this->roles[ $role ]['capabilities'][ $cap ] ); if ( $this->use_db ) { update_option( $this->role_key, $this->roles ); } } /** * Retrieves a role object by name. * * @since 2.0.0 * * @param string $role Role name. * @return WP_Role|null WP_Role object if found, null if the role does not exist. */ public function get_role( $role ) { if ( isset( $this->role_objects[ $role ] ) ) { return $this->role_objects[ $role ]; } else { return null; } } /** * Retrieves a list of role names. * * @since 2.0.0 * * @return string[] List of role names. */ public function get_names() { return $this->role_names; } /** * Determines whether a role name is currently in the list of available roles. * * @since 2.0.0 * * @param string $role Role name to look up. * @return bool */ public function is_role( $role ) { return isset( $this->role_names[ $role ] ); } /** * Initializes all of the available roles. * * @since 4.9.0 */ public function init_roles() { if ( empty( $this->roles ) ) { return; } $this->role_objects = array(); $this->role_names = array(); foreach ( array_keys( $this->roles ) as $role ) { $this->role_objects[ $role ] = new WP_Role( $role, $this->roles[ $role ]['capabilities'] ); $this->role_names[ $role ] = $this->roles[ $role ]['name']; } /** * Fires after the roles have been initialized, allowing plugins to add their own roles. * * @since 4.7.0 * * @param WP_Roles $wp_roles A reference to the WP_Roles object. */ do_action( 'wp_roles_init', $this ); } /** * Sets the site to operate on. Defaults to the current site. * * @since 4.9.0 * * @global wpdb $wpdb WordPress database abstraction object. * * @param int $site_id Site ID to initialize roles for. Default is the current site. */ public function for_site( $site_id = null ) { global $wpdb; if ( ! empty( $site_id ) ) { $this->site_id = absint( $site_id ); } else { $this->site_id = get_current_blog_id(); } $this->role_key = $wpdb->get_blog_prefix( $this->site_id ) . 'user_roles'; if ( ! empty( $this->roles ) && ! $this->use_db ) { return; } $this->roles = $this->get_roles_data(); $this->init_roles(); } /** * Gets the ID of the site for which roles are currently initialized. * * @since 4.9.0 * * @return int Site ID. */ public function get_site_id() { return $this->site_id; } /** * Gets the available roles data. * * @since 4.9.0 * * @global array $wp_user_roles Used to set the 'roles' property value. * * @return array Roles array. */ protected function get_roles_data() { global $wp_user_roles; if ( ! empty( $wp_user_roles ) ) { return $wp_user_roles; } if ( is_multisite() && get_current_blog_id() !== $this->site_id ) { remove_action( 'switch_blog', 'wp_switch_roles_and_user', 1 ); $roles = get_blog_option( $this->site_id, $this->role_key, array() ); add_action( 'switch_blog', 'wp_switch_roles_and_user', 1, 2 ); return $roles; } return get_option( $this->role_key, array() ); } } /** * User API: WP_User class * * @package WordPress * @subpackage Users * @since 4.4.0 */ /** * Core class used to implement the WP_User object. * * @since 2.0.0 * * @property string $nickname * @property string $description * @property string $user_description * @property string $first_name * @property string $user_firstname * @property string $last_name * @property string $user_lastname * @property string $user_login * @property string $user_pass * @property string $user_nicename * @property string $user_email * @property string $user_url * @property string $user_registered * @property string $user_activation_key * @property string $user_status * @property int $user_level * @property string $display_name * @property string $spam * @property string $deleted * @property string $locale * @property string $rich_editing * @property string $syntax_highlighting * @property string $use_ssl */ #[AllowDynamicProperties] class WP_User { /** * User data container. * * @since 2.0.0 * @var stdClass */ public $data; /** * The user's ID. * * @since 2.1.0 * @var int */ public $ID = 0; /** * Capabilities that the individual user has been granted outside of those inherited from their role. * * @since 2.0.0 * @var bool[] Array of key/value pairs where keys represent a capability name * and boolean values represent whether the user has that capability. */ public $caps = array(); /** * User metadata option name. * * @since 2.0.0 * @var string */ public $cap_key; /** * The roles the user is part of. * * @since 2.0.0 * @var string[] */ public $roles = array(); /** * All capabilities the user has, including individual and role based. * * @since 2.0.0 * @var bool[] Array of key/value pairs where keys represent a capability name * and boolean values represent whether the user has that capability. */ public $allcaps = array(); /** * The filter context applied to user data fields. * * @since 2.9.0 * @var string */ public $filter = null; /** * The site ID the capabilities of this user are initialized for. * * @since 4.9.0 * @var int */ private $site_id = 0; /** * @since 3.3.0 * @var array */ private static $back_compat_keys; /** * Constructor. * * Retrieves the userdata and passes it to WP_User::init(). * * @since 2.0.0 * * @global wpdb $wpdb WordPress database abstraction object. * * @param int|string|stdClass|WP_User $id User's ID, a WP_User object, or a user object from the DB. * @param string $name Optional. User's username * @param int $site_id Optional Site ID, defaults to current site. */ public function __construct( $id = 0, $name = '', $site_id = '' ) { global $wpdb; if ( ! isset( self::$back_compat_keys ) ) { $prefix = $wpdb->prefix; self::$back_compat_keys = array( 'user_firstname' => 'first_name', 'user_lastname' => 'last_name', 'user_description' => 'description', 'user_level' => $prefix . 'user_level', $prefix . 'usersettings' => $prefix . 'user-settings', $prefix . 'usersettingstime' => $prefix . 'user-settings-time', ); } if ( $id instanceof WP_User ) { $this->init( $id->data, $site_id ); return; } elseif ( is_object( $id ) ) { $this->init( $id, $site_id ); return; } if ( ! empty( $id ) && ! is_numeric( $id ) ) { $name = $id; $id = 0; } if ( $id ) { $data = self::get_data_by( 'id', $id ); } else { $data = self::get_data_by( 'login', $name ); } if ( $data ) { $this->init( $data, $site_id ); } else { $this->data = new stdClass(); } } /** * Sets up object properties, including capabilities. * * @since 3.3.0 * * @param object $data User DB row object. * @param int $site_id Optional. The site ID to initialize for. */ public function init( $data, $site_id = '' ) { if ( ! isset( $data->ID ) ) { $data->ID = 0; } $this->data = $data; $this->ID = (int) $data->ID; $this->for_site( $site_id ); } /** * Returns only the main user fields. * * @since 3.3.0 * @since 4.4.0 Added 'ID' as an alias of 'id' for the `$field` parameter. * * @global wpdb $wpdb WordPress database abstraction object. * * @param string $field The field to query against: Accepts 'id', 'ID', 'slug', 'email' or 'login'. * @param string|int $value The field value. * @return object|false Raw user object. */ public static function get_data_by( $field, $value ) { global $wpdb; // 'ID' is an alias of 'id'. if ( 'ID' === $field ) { $field = 'id'; } if ( 'id' === $field ) { // Make sure the value is numeric to avoid casting objects, for example, to int 1. if ( ! is_numeric( $value ) ) { return false; } $value = (int) $value; if ( $value < 1 ) { return false; } } else { $value = trim( $value ); } if ( ! $value ) { return false; } switch ( $field ) { case 'id': $user_id = $value; $db_field = 'ID'; break; case 'slug': $user_id = wp_cache_get( $value, 'userslugs' ); $db_field = 'user_nicename'; break; case 'email': $user_id = wp_cache_get( $value, 'useremail' ); $db_field = 'user_email'; break; case 'login': $value = sanitize_user( $value ); $user_id = wp_cache_get( $value, 'userlogins' ); $db_field = 'user_login'; break; default: return false; } if ( false !== $user_id ) { $user = wp_cache_get( $user_id, 'users' ); if ( $user ) { return $user; } } $user = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->users WHERE $db_field = %s LIMIT 1", $value ) ); if ( ! $user ) { return false; } update_user_caches( $user ); return $user; } /** * Magic method for checking the existence of a certain custom field. * * @since 3.3.0 * * @param string $key User meta key to check if set. * @return bool Whether the given user meta key is set. */ public function __isset( $key ) { if ( 'id' === $key ) { _deprecated_argument( 'WP_User->id', '2.1.0', sprintf( /* translators: %s: WP_User->ID */ __( 'Use %s instead.' ), 'WP_User->ID' ) ); $key = 'ID'; } if ( isset( $this->data->$key ) ) { return true; } if ( isset( self::$back_compat_keys[ $key ] ) ) { $key = self::$back_compat_keys[ $key ]; } return metadata_exists( 'user', $this->ID, $key ); } /** * Magic method for accessing custom fields. * * @since 3.3.0 * * @param string $key User meta key to retrieve. * @return mixed Value of the given user meta key (if set). If `$key` is 'id', the user ID. */ public function __get( $key ) { if ( 'id' === $key ) { _deprecated_argument( 'WP_User->id', '2.1.0', sprintf( /* translators: %s: WP_User->ID */ __( 'Use %s instead.' ), 'WP_User->ID' ) ); return $this->ID; } if ( isset( $this->data->$key ) ) { $value = $this->data->$key; } else { if ( isset( self::$back_compat_keys[ $key ] ) ) { $key = self::$back_compat_keys[ $key ]; } $value = get_user_meta( $this->ID, $key, true ); } if ( $this->filter ) { $value = sanitize_user_field( $key, $value, $this->ID, $this->filter ); } return $value; } /** * Magic method for setting custom user fields. * * This method does not update custom fields in the database. It only stores * the value on the WP_User instance. * * @since 3.3.0 * * @param string $key User meta key. * @param mixed $value User meta value. */ public function __set( $key, $value ) { if ( 'id' === $key ) { _deprecated_argument( 'WP_User->id', '2.1.0', sprintf( /* translators: %s: WP_User->ID */ __( 'Use %s instead.' ), 'WP_User->ID' ) ); $this->ID = $value; return; } $this->data->$key = $value; } /** * Magic method for unsetting a certain custom field. * * @since 4.4.0 * * @param string $key User meta key to unset. */ public function __unset( $key ) { if ( 'id' === $key ) { _deprecated_argument( 'WP_User->id', '2.1.0', sprintf( /* translators: %s: WP_User->ID */ __( 'Use %s instead.' ), 'WP_User->ID' ) ); } if ( isset( $this->data->$key ) ) { unset( $this->data->$key ); } if ( isset( self::$back_compat_keys[ $key ] ) ) { unset( self::$back_compat_keys[ $key ] ); } } /** * Determines whether the user exists in the database. * * @since 3.4.0 * * @return bool True if user exists in the database, false if not. */ public function exists() { return ! empty( $this->ID ); } /** * Retrieves the value of a property or meta key. * * Retrieves from the users and usermeta table. * * @since 3.3.0 * * @param string $key Property * @return mixed */ public function get( $key ) { return $this->__get( $key ); } /** * Determines whether a property or meta key is set. * * Consults the users and usermeta tables. * * @since 3.3.0 * * @param string $key Property. * @return bool */ public function has_prop( $key ) { return $this->__isset( $key ); } /** * Returns an array representation. * * @since 3.5.0 * * @return array Array representation. */ public function to_array() { return get_object_vars( $this->data ); } /** * Makes private/protected methods readable for backward compatibility. * * @since 4.3.0 * * @param string $name Method to call. * @param array $arguments Arguments to pass when calling. * @return mixed|false Return value of the callback, false otherwise. */ public function __call( $name, $arguments ) { if ( '_init_caps' === $name ) { return $this->_init_caps( ...$arguments ); } return false; } /** * Sets up capability object properties. * * Will set the value for the 'cap_key' property to current database table * prefix, followed by 'capabilities'. Will then check to see if the * property matching the 'cap_key' exists and is an array. If so, it will be * used. * * @since 2.1.0 * @deprecated 4.9.0 Use WP_User::for_site() * * @global wpdb $wpdb WordPress database abstraction object. * * @param string $cap_key Optional capability key */ protected function _init_caps( $cap_key = '' ) { global $wpdb; _deprecated_function( __METHOD__, '4.9.0', 'WP_User::for_site()' ); if ( empty( $cap_key ) ) { $this->cap_key = $wpdb->get_blog_prefix( $this->site_id ) . 'capabilities'; } else { $this->cap_key = $cap_key; } $this->caps = $this->get_caps_data(); $this->get_role_caps(); } /** * Retrieves all of the capabilities of the user's roles, and merges them with * individual user capabilities. * * All of the capabilities of the user's roles are merged with the user's individual * capabilities. This means that the user can be denied specific capabilities that * their role might have, but the user is specifically denied. * * @since 2.0.0 * * @return bool[] Array of key/value pairs where keys represent a capability name * and boolean values represent whether the user has that capability. */ public function get_role_caps() { $switch_site = false; if ( is_multisite() && get_current_blog_id() !== $this->site_id ) { $switch_site = true; switch_to_blog( $this->site_id ); } $wp_roles = wp_roles(); // Filter out caps that are not role names and assign to $this->roles. if ( is_array( $this->caps ) ) { $this->roles = array_filter( array_keys( $this->caps ), array( $wp_roles, 'is_role' ) ); } // Build $allcaps from role caps, overlay user's $caps. $this->allcaps = array(); foreach ( (array) $this->roles as $role ) { $the_role = $wp_roles->get_role( $role ); $this->allcaps = array_merge( (array) $this->allcaps, (array) $the_role->capabilities ); } $this->allcaps = array_merge( (array) $this->allcaps, (array) $this->caps ); if ( $switch_site ) { restore_current_blog(); } return $this->allcaps; } /** * Adds role to user. * * Updates the user's meta data option with capabilities and roles. * * @since 2.0.0 * * @param string $role Role name. */ public function add_role( $role ) { if ( empty( $role ) ) { return; } if ( in_array( $role, $this->roles, true ) ) { return; } $this->caps[ $role ] = true; update_user_meta( $this->ID, $this->cap_key, $this->caps ); $this->get_role_caps(); $this->update_user_level_from_caps(); /** * Fires immediately after the user has been given a new role. * * @since 4.3.0 * * @param int $user_id The user ID. * @param string $role The new role. */ do_action( 'add_user_role', $this->ID, $role ); } /** * Removes role from user. * * @since 2.0.0 * * @param string $role Role name. */ public function remove_role( $role ) { if ( ! in_array( $role, $this->roles, true ) ) { return; } unset( $this->caps[ $role ] ); update_user_meta( $this->ID, $this->cap_key, $this->caps ); $this->get_role_caps(); $this->update_user_level_from_caps(); /** * Fires immediately after a role as been removed from a user. * * @since 4.3.0 * * @param int $user_id The user ID. * @param string $role The removed role. */ do_action( 'remove_user_role', $this->ID, $role ); } /** * Sets the role of the user. * * This will remove the previous roles of the user and assign the user the * new one. You can set the role to an empty string and it will remove all * of the roles from the user. * * @since 2.0.0 * * @param string $role Role name. */ public function set_role( $role ) { if ( 1 === count( $this->roles ) && current( $this->roles ) === $role ) { return; } foreach ( (array) $this->roles as $oldrole ) { unset( $this->caps[ $oldrole ] ); } $old_roles = $this->roles; if ( ! empty( $role ) ) { $this->caps[ $role ] = true; $this->roles = array( $role => true ); } else { $this->roles = array(); } update_user_meta( $this->ID, $this->cap_key, $this->caps ); $this->get_role_caps(); $this->update_user_level_from_caps(); foreach ( $old_roles as $old_role ) { if ( ! $old_role || $old_role === $role ) { continue; } /** This action is documented in wp-includes/class-wp-user.php */ do_action( 'remove_user_role', $this->ID, $old_role ); } if ( $role && ! in_array( $role, $old_roles, true ) ) { /** This action is documented in wp-includes/class-wp-user.php */ do_action( 'add_user_role', $this->ID, $role ); } /** * Fires after the user's role has changed. * * @since 2.9.0 * @since 3.6.0 Added $old_roles to include an array of the user's previous roles. * * @param int $user_id The user ID. * @param string $role The new role. * @param string[] $old_roles An array of the user's previous roles. */ do_action( 'set_user_role', $this->ID, $role, $old_roles ); } /** * Chooses the maximum level the user has. * * Will compare the level from the $item parameter against the $max * parameter. If the item is incorrect, then just the $max parameter value * will be returned. * * Used to get the max level based on the capabilities the user has. This * is also based on roles, so if the user is assigned the Administrator role * then the capability 'level_10' will exist and the user will get that * value. * * @since 2.0.0 * * @param int $max Max level of user. * @param string $item Level capability name. * @return int Max Level. */ public function level_reduction( $max, $item ) { if ( preg_match( '/^level_(10|[0-9])$/i', $item, $matches ) ) { $level = (int) $matches[1]; return max( $max, $level ); } else { return $max; } } /** * Updates the maximum user level for the user. * * Updates the 'user_level' user metadata (includes prefix that is the * database table prefix) with the maximum user level. Gets the value from * the all of the capabilities that the user has. * * @since 2.0.0 * * @global wpdb $wpdb WordPress database abstraction object. */ public function update_user_level_from_caps() { global $wpdb; $this->user_level = array_reduce( array_keys( $this->allcaps ), array( $this, 'level_reduction' ), 0 ); update_user_meta( $this->ID, $wpdb->get_blog_prefix() . 'user_level', $this->user_level ); } /** * Adds capability and grant or deny access to capability. * * @since 2.0.0 * * @param string $cap Capability name. * @param bool $grant Whether to grant capability to user. */ public function add_cap( $cap, $grant = true ) { $this->caps[ $cap ] = $grant; update_user_meta( $this->ID, $this->cap_key, $this->caps ); $this->get_role_caps(); $this->update_user_level_from_caps(); } /** * Removes capability from user. * * @since 2.0.0 * * @param string $cap Capability name. */ public function remove_cap( $cap ) { if ( ! isset( $this->caps[ $cap ] ) ) { return; } unset( $this->caps[ $cap ] ); update_user_meta( $this->ID, $this->cap_key, $this->caps ); $this->get_role_caps(); $this->update_user_level_from_caps(); } /** * Removes all of the capabilities of the user. * * @since 2.1.0 * * @global wpdb $wpdb WordPress database abstraction object. */ public function remove_all_caps() { global $wpdb; $this->caps = array(); delete_user_meta( $this->ID, $this->cap_key ); delete_user_meta( $this->ID, $wpdb->get_blog_prefix() . 'user_level' ); $this->get_role_caps(); } /** * Returns whether the user has the specified capability. * * This function also accepts an ID of an object to check against if the capability is a meta capability. Meta * capabilities such as `edit_post` and `edit_user` are capabilities used by the `map_meta_cap()` function to * map to primitive capabilities that a user or role has, such as `edit_posts` and `edit_others_posts`. * * Example usage: * * $user->has_cap( 'edit_posts' ); * $user->has_cap( 'edit_post', $post->ID ); * $user->has_cap( 'edit_post_meta', $post->ID, $meta_key ); * * While checking against a role in place of a capability is supported in part, this practice is discouraged as it * may produce unreliable results. * * @since 2.0.0 * @since 5.3.0 Formalized the existing and already documented `...$args` parameter * by adding it to the function signature. * * @see map_meta_cap() * * @param string $cap Capability name. * @param mixed ...$args Optional further parameters, typically starting with an object ID. * @return bool Whether the user has the given capability, or, if an object ID is passed, whether the user has * the given capability for that object. */ public function has_cap( $cap, ...$args ) { if ( is_numeric( $cap ) ) { _deprecated_argument( __FUNCTION__, '2.0.0', __( 'Usage of user levels is deprecated. Use capabilities instead.' ) ); $cap = $this->translate_level_to_cap( $cap ); } $caps = map_meta_cap( $cap, $this->ID, ...$args ); // Multisite super admin has all caps by definition, Unless specifically denied. if ( is_multisite() && is_super_admin( $this->ID ) ) { if ( in_array( 'do_not_allow', $caps, true ) ) { return false; } return true; } // Maintain BC for the argument passed to the "user_has_cap" filter. $args = array_merge( array( $cap, $this->ID ), $args ); /** * Dynamically filter a user's capabilities. * * @since 2.0.0 * @since 3.7.0 Added the `$user` parameter. * * @param bool[] $allcaps Array of key/value pairs where keys represent a capability name * and boolean values represent whether the user has that capability. * @param string[] $caps Required primitive capabilities for the requested capability. * @param array $args { * Arguments that accompany the requested capability check. * * @type string $0 Requested capability. * @type int $1 Concerned user ID. * @type mixed ...$2 Optional second and further parameters, typically object ID. * } * @param WP_User $user The user object. */ $capabilities = apply_filters( 'user_has_cap', $this->allcaps, $caps, $args, $this ); // Everyone is allowed to exist. $capabilities['exist'] = true; // Nobody is allowed to do things they are not allowed to do. unset( $capabilities['do_not_allow'] ); // Must have ALL requested caps. foreach ( (array) $caps as $cap ) { if ( empty( $capabilities[ $cap ] ) ) { return false; } } return true; } /** * Converts numeric level to level capability name. * * Prepends 'level_' to level number. * * @since 2.0.0 * * @param int $level Level number, 1 to 10. * @return string */ public function translate_level_to_cap( $level ) { return 'level_' . $level; } /** * Sets the site to operate on. Defaults to the current site. * * @since 3.0.0 * @deprecated 4.9.0 Use WP_User::for_site() * * @param int $blog_id Optional. Site ID, defaults to current site. */ public function for_blog( $blog_id = '' ) { _deprecated_function( __METHOD__, '4.9.0', 'WP_User::for_site()' ); $this->for_site( $blog_id ); } /** * Sets the site to operate on. Defaults to the current site. * * @since 4.9.0 * * @global wpdb $wpdb WordPress database abstraction object. * * @param int $site_id Site ID to initialize user capabilities for. Default is the current site. */ public function for_site( $site_id = '' ) { global $wpdb; if ( ! empty( $site_id ) ) { $this->site_id = absint( $site_id ); } else { $this->site_id = get_current_blog_id(); } $this->cap_key = $wpdb->get_blog_prefix( $this->site_id ) . 'capabilities'; $this->caps = $this->get_caps_data(); $this->get_role_caps(); } /** * Gets the ID of the site for which the user's capabilities are currently initialized. * * @since 4.9.0 * * @return int Site ID. */ public function get_site_id() { return $this->site_id; } /** * Gets the available user capabilities data. * * @since 4.9.0 * * @return bool[] List of capabilities keyed by the capability name, * e.g. `array( 'edit_posts' => true, 'delete_posts' => false )`. */ private function get_caps_data() { $caps = get_user_meta( $this->ID, $this->cap_key, true ); if ( ! is_array( $caps ) ) { return array(); } return $caps; } } /** * Dependencies API: Styles functions * * @since 2.6.0 * * @package WordPress * @subpackage Dependencies */ /** * Initializes $wp_styles if it has not been set. * * @since 4.2.0 * * @global WP_Styles $wp_styles * * @return WP_Styles WP_Styles instance. */ function wp_styles() { global $wp_styles; if ( ! ( $wp_styles instanceof WP_Styles ) ) { $wp_styles = new WP_Styles(); } return $wp_styles; } /** * Displays styles that are in the $handles queue. * * Passing an empty array to $handles prints the queue, * passing an array with one string prints that style, * and passing an array of strings prints those styles. * * @since 2.6.0 * * @global WP_Styles $wp_styles The WP_Styles object for printing styles. * * @param string|bool|array $handles Styles to be printed. Default 'false'. * @return string[] On success, an array of handles of processed WP_Dependencies items; otherwise, an empty array. */ function wp_print_styles( $handles = false ) { global $wp_styles; if ( '' === $handles ) { // For 'wp_head'. $handles = false; } if ( ! $handles ) { /** * Fires before styles in the $handles queue are printed. * * @since 2.6.0 */ do_action( 'wp_print_styles' ); } _wp_scripts_maybe_doing_it_wrong( __FUNCTION__ ); if ( ! ( $wp_styles instanceof WP_Styles ) ) { if ( ! $handles ) { return array(); // No need to instantiate if nothing is there. } } return wp_styles()->do_items( $handles ); } /** * Adds extra CSS styles to a registered stylesheet. * * Styles will only be added if the stylesheet is already in the queue. * Accepts a string $data containing the CSS. If two or more CSS code blocks * are added to the same stylesheet $handle, they will be printed in the order * they were added, i.e. the latter added styles can redeclare the previous. * * @see WP_Styles::add_inline_style() * * @since 3.3.0 * * @param string $handle Name of the stylesheet to add the extra styles to. * @param string $data String containing the CSS styles to be added. * @return bool True on success, false on failure. */ function wp_add_inline_style( $handle, $data ) { _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); if ( false !== stripos( $data, '' ) ) { _doing_it_wrong( __FUNCTION__, sprintf( /* translators: 1: #is', '$1', $data ) ); } return wp_styles()->add_inline_style( $handle, $data ); } /** * Registers a CSS stylesheet. * * @see WP_Dependencies::add() * @link https://www.w3.org/TR/CSS2/media.html#media-types List of CSS media types. * * @since 2.6.0 * @since 4.3.0 A return value was added. * * @param string $handle Name of the stylesheet. Should be unique. * @param string|false $src Full URL of the stylesheet, or path of the stylesheet relative to the WordPress root directory. * If source is set to false, stylesheet is an alias of other stylesheets it depends on. * @param string[] $deps Optional. An array of registered stylesheet handles this stylesheet depends on. Default empty array. * @param string|bool|null $ver Optional. String specifying stylesheet version number, if it has one, which is added to the URL * as a query string for cache busting purposes. If version is set to false, a version * number is automatically added equal to current installed WordPress version. * If set to null, no version is added. * @param string $media Optional. The media for which this stylesheet has been defined. * Default 'all'. Accepts media types like 'all', 'print' and 'screen', or media queries like * '(orientation: portrait)' and '(max-width: 640px)'. * @return bool Whether the style has been registered. True on success, false on failure. */ function wp_register_style( $handle, $src, $deps = array(), $ver = false, $media = 'all' ) { _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); return wp_styles()->add( $handle, $src, $deps, $ver, $media ); } /** * Removes a registered stylesheet. * * @see WP_Dependencies::remove() * * @since 2.1.0 * * @param string $handle Name of the stylesheet to be removed. */ function wp_deregister_style( $handle ) { _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); wp_styles()->remove( $handle ); } /** * Enqueues a CSS stylesheet. * * Registers the style if source provided (does NOT overwrite) and enqueues. * * @see WP_Dependencies::add() * @see WP_Dependencies::enqueue() * @link https://www.w3.org/TR/CSS2/media.html#media-types List of CSS media types. * * @since 2.6.0 * * @param string $handle Name of the stylesheet. Should be unique. * @param string $src Full URL of the stylesheet, or path of the stylesheet relative to the WordPress root directory. * Default empty. * @param string[] $deps Optional. An array of registered stylesheet handles this stylesheet depends on. Default empty array. * @param string|bool|null $ver Optional. String specifying stylesheet version number, if it has one, which is added to the URL * as a query string for cache busting purposes. If version is set to false, a version * number is automatically added equal to current installed WordPress version. * If set to null, no version is added. * @param string $media Optional. The media for which this stylesheet has been defined. * Default 'all'. Accepts media types like 'all', 'print' and 'screen', or media queries like * '(orientation: portrait)' and '(max-width: 640px)'. */ function wp_enqueue_style( $handle, $src = '', $deps = array(), $ver = false, $media = 'all' ) { _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); $wp_styles = wp_styles(); if ( $src ) { $_handle = explode( '?', $handle ); $wp_styles->add( $_handle[0], $src, $deps, $ver, $media ); } $wp_styles->enqueue( $handle ); } /** * Removes a previously enqueued CSS stylesheet. * * @see WP_Dependencies::dequeue() * * @since 3.1.0 * * @param string $handle Name of the stylesheet to be removed. */ function wp_dequeue_style( $handle ) { _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); wp_styles()->dequeue( $handle ); } /** * Checks whether a CSS stylesheet has been added to the queue. * * @since 2.8.0 * * @param string $handle Name of the stylesheet. * @param string $status Optional. Status of the stylesheet to check. Default 'enqueued'. * Accepts 'enqueued', 'registered', 'queue', 'to_do', and 'done'. * @return bool Whether style is queued. */ function wp_style_is( $handle, $status = 'enqueued' ) { _wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle ); return (bool) wp_styles()->query( $handle, $status ); } /** * Adds metadata to a CSS stylesheet. * * Works only if the stylesheet has already been registered. * * Possible values for $key and $value: * 'conditional' string Comments for IE 6, lte IE 7 etc. * 'rtl' bool|string To declare an RTL stylesheet. * 'suffix' string Optional suffix, used in combination with RTL. * 'alt' bool For rel="alternate stylesheet". * 'title' string For preferred/alternate stylesheets. * 'path' string The absolute path to a stylesheet. Stylesheet will * load inline when 'path' is set. * * @see WP_Dependencies::add_data() * * @since 3.6.0 * @since 5.8.0 Added 'path' as an official value for $key. * See {@see wp_maybe_inline_styles()}. * * @param string $handle Name of the stylesheet. * @param string $key Name of data point for which we're storing a value. * Accepts 'conditional', 'rtl' and 'suffix', 'alt', 'title' and 'path'. * @param mixed $value String containing the CSS data to be added. * @return bool True on success, false on failure. */ function wp_style_add_data( $handle, $key, $value ) { return wp_styles()->add_data( $handle, $key, $value ); } /** * REST API: WP_REST_Attachments_Controller class * * @package WordPress * @subpackage REST_API * @since 4.7.0 */ /** * Core controller used to access attachments via the REST API. * * @since 4.7.0 * * @see WP_REST_Posts_Controller */ class WP_REST_Attachments_Controller extends WP_REST_Posts_Controller { /** * Whether the controller supports batching. * * @since 5.9.0 * @var false */ protected $allow_batch = false; /** * Registers the routes for attachments. * * @since 5.3.0 * * @see register_rest_route() */ public function register_routes() { parent::register_routes(); register_rest_route( $this->namespace, '/' . $this->rest_base . '/(?P[\d]+)/post-process', array( 'methods' => WP_REST_Server::CREATABLE, 'callback' => array( $this, 'post_process_item' ), 'permission_callback' => array( $this, 'post_process_item_permissions_check' ), 'args' => array( 'id' => array( 'description' => __( 'Unique identifier for the attachment.' ), 'type' => 'integer', ), 'action' => array( 'type' => 'string', 'enum' => array( 'create-image-subsizes' ), 'required' => true, ), ), ) ); register_rest_route( $this->namespace, '/' . $this->rest_base . '/(?P[\d]+)/edit', array( 'methods' => WP_REST_Server::CREATABLE, 'callback' => array( $this, 'edit_media_item' ), 'permission_callback' => array( $this, 'edit_media_item_permissions_check' ), 'args' => $this->get_edit_media_item_args(), ) ); } /** * Determines the allowed query_vars for a get_items() response and * prepares for WP_Query. * * @since 4.7.0 * * @param array $prepared_args Optional. Array of prepared arguments. Default empty array. * @param WP_REST_Request $request Optional. Request to prepare items for. * @return array Array of query arguments. */ protected function prepare_items_query( $prepared_args = array(), $request = null ) { $query_args = parent::prepare_items_query( $prepared_args, $request ); if ( empty( $query_args['post_status'] ) ) { $query_args['post_status'] = 'inherit'; } $media_types = $this->get_media_types(); if ( ! empty( $request['media_type'] ) && isset( $media_types[ $request['media_type'] ] ) ) { $query_args['post_mime_type'] = $media_types[ $request['media_type'] ]; } if ( ! empty( $request['mime_type'] ) ) { $parts = explode( '/', $request['mime_type'] ); if ( isset( $media_types[ $parts[0] ] ) && in_array( $request['mime_type'], $media_types[ $parts[0] ], true ) ) { $query_args['post_mime_type'] = $request['mime_type']; } } // Filter query clauses to include filenames. if ( isset( $query_args['s'] ) ) { add_filter( 'wp_allow_query_attachment_by_filename', '__return_true' ); } return $query_args; } /** * Checks if a given request has access to create an attachment. * * @since 4.7.0 * * @param WP_REST_Request $request Full details about the request. * @return true|WP_Error Boolean true if the attachment may be created, or a WP_Error if not. */ public function create_item_permissions_check( $request ) { $ret = parent::create_item_permissions_check( $request ); if ( ! $ret || is_wp_error( $ret ) ) { return $ret; } if ( ! current_user_can( 'upload_files' ) ) { return new WP_Error( 'rest_cannot_create', __( 'Sorry, you are not allowed to upload media on this site.' ), array( 'status' => 400 ) ); } // Attaching media to a post requires ability to edit said post. if ( ! empty( $request['post'] ) && ! current_user_can( 'edit_post', (int) $request['post'] ) ) { return new WP_Error( 'rest_cannot_edit', __( 'Sorry, you are not allowed to upload media to this post.' ), array( 'status' => rest_authorization_required_code() ) ); } return true; } /** * Creates a single attachment. * * @since 4.7.0 * * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response|WP_Error Response object on success, WP_Error object on failure. */ public function create_item( $request ) { if ( ! empty( $request['post'] ) && in_array( get_post_type( $request['post'] ), array( 'revision', 'attachment' ), true ) ) { return new WP_Error( 'rest_invalid_param', __( 'Invalid parent type.' ), array( 'status' => 400 ) ); } $insert = $this->insert_attachment( $request ); if ( is_wp_error( $insert ) ) { return $insert; } $schema = $this->get_item_schema(); // Extract by name. $attachment_id = $insert['attachment_id']; $file = $insert['file']; if ( isset( $request['alt_text'] ) ) { update_post_meta( $attachment_id, '_wp_attachment_image_alt', sanitize_text_field( $request['alt_text'] ) ); } if ( ! empty( $schema['properties']['featured_media'] ) && isset( $request['featured_media'] ) ) { $thumbnail_update = $this->handle_featured_media( $request['featured_media'], $attachment_id ); if ( is_wp_error( $thumbnail_update ) ) { return $thumbnail_update; } } if ( ! empty( $schema['properties']['meta'] ) && isset( $request['meta'] ) ) { $meta_update = $this->meta->update_value( $request['meta'], $attachment_id ); if ( is_wp_error( $meta_update ) ) { return $meta_update; } } $attachment = get_post( $attachment_id ); $fields_update = $this->update_additional_fields_for_object( $attachment, $request ); if ( is_wp_error( $fields_update ) ) { return $fields_update; } $terms_update = $this->handle_terms( $attachment_id, $request ); if ( is_wp_error( $terms_update ) ) { return $terms_update; } $request->set_param( 'context', 'edit' ); /** * Fires after a single attachment is completely created or updated via the REST API. * * @since 5.0.0 * * @param WP_Post $attachment Inserted or updated attachment object. * @param WP_REST_Request $request Request object. * @param bool $creating True when creating an attachment, false when updating. */ do_action( 'rest_after_insert_attachment', $attachment, $request, true ); wp_after_insert_post( $attachment, false, null ); if ( wp_is_serving_rest_request() ) { /* * Set a custom header with the attachment_id. * Used by the browser/client to resume creating image sub-sizes after a PHP fatal error. */ header( 'X-WP-Upload-Attachment-ID: ' . $attachment_id ); } // Include media and image functions to get access to wp_generate_attachment_metadata(). require_once ABSPATH . 'wp-admin/includes/media.php'; require_once ABSPATH . 'wp-admin/includes/image.php'; /* * Post-process the upload (create image sub-sizes, make PDF thumbnails, etc.) and insert attachment meta. * At this point the server may run out of resources and post-processing of uploaded images may fail. */ wp_update_attachment_metadata( $attachment_id, wp_generate_attachment_metadata( $attachment_id, $file ) ); $response = $this->prepare_item_for_response( $attachment, $request ); $response = rest_ensure_response( $response ); $response->set_status( 201 ); $response->header( 'Location', rest_url( sprintf( '%s/%s/%d', $this->namespace, $this->rest_base, $attachment_id ) ) ); return $response; } /** * Inserts the attachment post in the database. Does not update the attachment meta. * * @since 5.3.0 * * @param WP_REST_Request $request * @return array|WP_Error */ protected function insert_attachment( $request ) { // Get the file via $_FILES or raw data. $files = $request->get_file_params(); $headers = $request->get_headers(); $time = null; // Matches logic in media_handle_upload(). if ( ! empty( $request['post'] ) ) { $post = get_post( $request['post'] ); // The post date doesn't usually matter for pages, so don't backdate this upload. if ( $post && 'page' !== $post->post_type && substr( $post->post_date, 0, 4 ) > 0 ) { $time = $post->post_date; } } if ( ! empty( $files ) ) { $file = $this->upload_from_file( $files, $headers, $time ); } else { $file = $this->upload_from_data( $request->get_body(), $headers, $time ); } if ( is_wp_error( $file ) ) { return $file; } $name = wp_basename( $file['file'] ); $name_parts = pathinfo( $name ); $name = trim( substr( $name, 0, -( 1 + strlen( $name_parts['extension'] ) ) ) ); $url = $file['url']; $type = $file['type']; $file = $file['file']; // Include image functions to get access to wp_read_image_metadata(). require_once ABSPATH . 'wp-admin/includes/image.php'; // Use image exif/iptc data for title and caption defaults if possible. $image_meta = wp_read_image_metadata( $file ); if ( ! empty( $image_meta ) ) { if ( empty( $request['title'] ) && trim( $image_meta['title'] ) && ! is_numeric( sanitize_title( $image_meta['title'] ) ) ) { $request['title'] = $image_meta['title']; } if ( empty( $request['caption'] ) && trim( $image_meta['caption'] ) ) { $request['caption'] = $image_meta['caption']; } } $attachment = $this->prepare_item_for_database( $request ); $attachment->post_mime_type = $type; $attachment->guid = $url; // If the title was not set, use the original filename. if ( empty( $attachment->post_title ) && ! empty( $files['file']['name'] ) ) { // Remove the file extension (after the last `.`) $tmp_title = substr( $files['file']['name'], 0, strrpos( $files['file']['name'], '.' ) ); if ( ! empty( $tmp_title ) ) { $attachment->post_title = $tmp_title; } } // Fall back to the original approach. if ( empty( $attachment->post_title ) ) { $attachment->post_title = preg_replace( '/\.[^.]+$/', '', wp_basename( $file ) ); } // $post_parent is inherited from $attachment['post_parent']. $id = wp_insert_attachment( wp_slash( (array) $attachment ), $file, 0, true, false ); if ( is_wp_error( $id ) ) { if ( 'db_update_error' === $id->get_error_code() ) { $id->add_data( array( 'status' => 500 ) ); } else { $id->add_data( array( 'status' => 400 ) ); } return $id; } $attachment = get_post( $id ); /** * Fires after a single attachment is created or updated via the REST API. * * @since 4.7.0 * * @param WP_Post $attachment Inserted or updated attachment object. * @param WP_REST_Request $request The request sent to the API. * @param bool $creating True when creating an attachment, false when updating. */ do_action( 'rest_insert_attachment', $attachment, $request, true ); return array( 'attachment_id' => $id, 'file' => $file, ); } /** * Determines the featured media based on a request param. * * @since 6.5.0 * * @param int $featured_media Featured Media ID. * @param int $post_id Post ID. * @return bool|WP_Error Whether the post thumbnail was successfully deleted, otherwise WP_Error. */ protected function handle_featured_media( $featured_media, $post_id ) { $post_type = get_post_type( $post_id ); $thumbnail_support = current_theme_supports( 'post-thumbnails', $post_type ) && post_type_supports( $post_type, 'thumbnail' ); // Similar check as in wp_insert_post(). if ( ! $thumbnail_support && get_post_mime_type( $post_id ) ) { if ( wp_attachment_is( 'audio', $post_id ) ) { $thumbnail_support = post_type_supports( 'attachment:audio', 'thumbnail' ) || current_theme_supports( 'post-thumbnails', 'attachment:audio' ); } elseif ( wp_attachment_is( 'video', $post_id ) ) { $thumbnail_support = post_type_supports( 'attachment:video', 'thumbnail' ) || current_theme_supports( 'post-thumbnails', 'attachment:video' ); } } if ( $thumbnail_support ) { return parent::handle_featured_media( $featured_media, $post_id ); } return new WP_Error( 'rest_no_featured_media', sprintf( /* translators: %s: attachment mime type */ __( 'This site does not support post thumbnails on attachments with MIME type %s.' ), get_post_mime_type( $post_id ) ), array( 'status' => 400 ) ); } /** * Updates a single attachment. * * @since 4.7.0 * * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response|WP_Error Response object on success, WP_Error object on failure. */ public function update_item( $request ) { if ( ! empty( $request['post'] ) && in_array( get_post_type( $request['post'] ), array( 'revision', 'attachment' ), true ) ) { return new WP_Error( 'rest_invalid_param', __( 'Invalid parent type.' ), array( 'status' => 400 ) ); } $attachment_before = get_post( $request['id'] ); $response = parent::update_item( $request ); if ( is_wp_error( $response ) ) { return $response; } $response = rest_ensure_response( $response ); $data = $response->get_data(); if ( isset( $request['alt_text'] ) ) { update_post_meta( $data['id'], '_wp_attachment_image_alt', $request['alt_text'] ); } $attachment = get_post( $request['id'] ); if ( ! empty( $schema['properties']['featured_media'] ) && isset( $request['featured_media'] ) ) { $thumbnail_update = $this->handle_featured_media( $request['featured_media'], $attachment->ID ); if ( is_wp_error( $thumbnail_update ) ) { return $thumbnail_update; } } $fields_update = $this->update_additional_fields_for_object( $attachment, $request ); if ( is_wp_error( $fields_update ) ) { return $fields_update; } $request->set_param( 'context', 'edit' ); /** This action is documented in wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php */ do_action( 'rest_after_insert_attachment', $attachment, $request, false ); wp_after_insert_post( $attachment, true, $attachment_before ); $response = $this->prepare_item_for_response( $attachment, $request ); $response = rest_ensure_response( $response ); return $response; } /** * Performs post-processing on an attachment. * * @since 5.3.0 * * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response|WP_Error Response object on success, WP_Error object on failure. */ public function post_process_item( $request ) { switch ( $request['action'] ) { case 'create-image-subsizes': require_once ABSPATH . 'wp-admin/includes/image.php'; wp_update_image_subsizes( $request['id'] ); break; } $request['context'] = 'edit'; return $this->prepare_item_for_response( get_post( $request['id'] ), $request ); } /** * Checks if a given request can perform post-processing on an attachment. * * @since 5.3.0 * * @param WP_REST_Request $request Full details about the request. * @return true|WP_Error True if the request has access to update the item, WP_Error object otherwise. */ public function post_process_item_permissions_check( $request ) { return $this->update_item_permissions_check( $request ); } /** * Checks if a given request has access to editing media. * * @since 5.5.0 * * @param WP_REST_Request $request Full details about the request. * @return true|WP_Error True if the request has read access, WP_Error object otherwise. */ public function edit_media_item_permissions_check( $request ) { if ( ! current_user_can( 'upload_files' ) ) { return new WP_Error( 'rest_cannot_edit_image', __( 'Sorry, you are not allowed to upload media on this site.' ), array( 'status' => rest_authorization_required_code() ) ); } return $this->update_item_permissions_check( $request ); } /** * Applies edits to a media item and creates a new attachment record. * * @since 5.5.0 * * @param WP_REST_Request $request Full details about the request. * @return WP_REST_Response|WP_Error Response object on success, WP_Error object on failure. */ public function edit_media_item( $request ) { require_once ABSPATH . 'wp-admin/includes/image.php'; $attachment_id = $request['id']; // This also confirms the attachment is an image. $image_file = wp_get_original_image_path( $attachment_id ); $image_meta = wp_get_attachment_metadata( $attachment_id ); if ( ! $image_meta || ! $image_file || ! wp_image_file_matches_image_meta( $request['src'], $image_meta, $attachment_id ) ) { return new WP_Error( 'rest_unknown_attachment', __( 'Unable to get meta information for file.' ), array( 'status' => 404 ) ); } $supported_types = array( 'image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/avif', 'image/heic' ); $mime_type = get_post_mime_type( $attachment_id ); if ( ! in_array( $mime_type, $supported_types, true ) ) { return new WP_Error( 'rest_cannot_edit_file_type', __( 'This type of file cannot be edited.' ), array( 'status' => 400 ) ); } // The `modifiers` param takes precedence over the older format. if ( isset( $request['modifiers'] ) ) { $modifiers = $request['modifiers']; } else { $modifiers = array(); if ( ! empty( $request['rotation'] ) ) { $modifiers[] = array( 'type' => 'rotate', 'args' => array( 'angle' => $request['rotation'], ), ); } if ( isset( $request['x'], $request['y'], $request['width'], $request['height'] ) ) { $modifiers[] = array( 'type' => 'crop', 'args' => array( 'left' => $request['x'], 'top' => $request['y'], 'width' => $request['width'], 'height' => $request['height'], ), ); } if ( 0 === count( $modifiers ) ) { return new WP_Error( 'rest_image_not_edited', __( 'The image was not edited. Edit the image before applying the changes.' ), array( 'status' => 400 ) ); } } /* * If the file doesn't exist, attempt a URL fopen on the src link. * This can occur with certain file replication plugins. * Keep the original file path to get a modified name later. */ $image_file_to_edit = $image_file; if ( ! file_exists( $image_file_to_edit ) ) { $image_file_to_edit = _load_image_to_edit_path( $attachment_id ); } $image_editor = wp_get_image_editor( $image_file_to_edit ); if ( is_wp_error( $image_editor ) ) { return new WP_Error( 'rest_unknown_image_file_type', __( 'Unable to edit this image.' ), array( 'status' => 500 ) ); } foreach ( $modifiers as $modifier ) { $args = $modifier['args']; switch ( $modifier['type'] ) { case 'rotate': // Rotation direction: clockwise vs. counterclockwise. $rotate = 0 - $args['angle']; if ( 0 !== $rotate ) { $result = $image_editor->rotate( $rotate ); if ( is_wp_error( $result ) ) { return new WP_Error( 'rest_image_rotation_failed', __( 'Unable to rotate this image.' ), array( 'status' => 500 ) ); } } break; case 'crop': $size = $image_editor->get_size(); $crop_x = (int) round( ( $size['width'] * $args['left'] ) / 100.0 ); $crop_y = (int) round( ( $size['height'] * $args['top'] ) / 100.0 ); $width = (int) round( ( $size['width'] * $args['width'] ) / 100.0 ); $height = (int) round( ( $size['height'] * $args['height'] ) / 100.0 ); if ( $size['width'] !== $width || $size['height'] !== $height ) { $result = $image_editor->crop( $crop_x, $crop_y, $width, $height ); if ( is_wp_error( $result ) ) { return new WP_Error( 'rest_image_crop_failed', __( 'Unable to crop this image.' ), array( 'status' => 500 ) ); } } break; } } // Calculate the file name. $image_ext = pathinfo( $image_file, PATHINFO_EXTENSION ); $image_name = wp_basename( $image_file, ".{$image_ext}" ); /* * Do not append multiple `-edited` to the file name. * The user may be editing a previously edited image. */ if ( preg_match( '/-edited(-\d+)?$/', $image_name ) ) { // Remove any `-1`, `-2`, etc. `wp_unique_filename()` will add the proper number. $image_name = preg_replace( '/-edited(-\d+)?$/', '-edited', $image_name ); } else { // Append `-edited` before the extension. $image_name .= '-edited'; } $filename = "{$image_name}.{$image_ext}"; // Create the uploads subdirectory if needed. $uploads = wp_upload_dir(); // Make the file name unique in the (new) upload directory. $filename = wp_unique_filename( $uploads['path'], $filename ); // Save to disk. $saved = $image_editor->save( $uploads['path'] . "/$filename" ); if ( is_wp_error( $saved ) ) { return $saved; } // Create new attachment post. $new_attachment_post = array( 'post_mime_type' => $saved['mime-type'], 'guid' => $uploads['url'] . "/$filename", 'post_title' => $image_name, 'post_content' => '', ); // Copy post_content, post_excerpt, and post_title from the edited image's attachment post. $attachment_post = get_post( $attachment_id ); if ( $attachment_post ) { $new_attachment_post['post_content'] = $attachment_post->post_content; $new_attachment_post['post_excerpt'] = $attachment_post->post_excerpt; $new_attachment_post['post_title'] = $attachment_post->post_title; } $new_attachment_id = wp_insert_attachment( wp_slash( $new_attachment_post ), $saved['path'], 0, true ); if ( is_wp_error( $new_attachment_id ) ) { if ( 'db_update_error' === $new_attachment_id->get_error_code() ) { $new_attachment_id->add_data( array( 'status' => 500 ) ); } else { $new_attachment_id->add_data( array( 'status' => 400 ) ); } return $new_attachment_id; } // Copy the image alt text from the edited image. $image_alt = get_post_meta( $attachment_id, '_wp_attachment_image_alt', true ); if ( ! empty( $image_alt ) ) { // update_post_meta() expects slashed. update_post_meta( $new_attachment_id, '_wp_attachment_image_alt', wp_slash( $image_alt ) ); } if ( wp_is_serving_rest_request() ) { /* * Set a custom header with the attachment_id. * Used by the browser/client to resume creating image sub-sizes after a PHP fatal error. */ header( 'X-WP-Upload-Attachment-ID: ' . $new_attachment_id ); } // Generate image sub-sizes and meta. $new_image_meta = wp_generate_attachment_metadata( $new_attachment_id, $saved['path'] ); // Copy the EXIF metadata from the original attachment if not generated for the edited image. if ( isset( $image_meta['image_meta'] ) && isset( $new_image_meta['image_meta'] ) && is_array( $new_image_meta['image_meta'] ) ) { // Merge but skip empty values. foreach ( (array) $image_meta['image_meta'] as $key => $value ) { if ( empty( $new_image_meta['image_meta'][ $key ] ) && ! empty( $value ) ) { $new_image_meta['image_meta'][ $key ] = $value; } } } // Reset orientation. At this point the image is edited and orientation is correct. if ( ! empty( $new_image_meta['image_meta']['orientation'] ) ) { $new_image_meta['image_meta']['orientation'] = 1; } // The attachment_id may change if the site is exported and imported. $new_image_meta['parent_image'] = array( 'attachment_id' => $attachment_id, // Path to the originally uploaded image file relative to the uploads directory. 'file' => _wp_relative_upload_path( $image_file ), ); /** * Filters the meta data for the new image created by editing an existing image. * * @since 5.5.0 * * @param array $new_image_meta Meta data for the new image. * @param int $new_attachment_id Attachment post ID for the new image. * @param int $attachment_id Attachment post ID for the edited (parent) image. */ $new_image_meta = apply_filters( 'wp_edited_image_metadata', $new_image_meta, $new_attachment_id, $attachment_id ); wp_update_attachment_metadata( $new_attachment_id, $new_image_meta ); $response = $this->prepare_item_for_response( get_post( $new_attachment_id ), $request ); $response->set_status( 201 ); $response->header( 'Location', rest_url( sprintf( '%s/%s/%s', $this->namespace, $this->rest_base, $new_attachment_id ) ) ); return $response; } /** * Prepares a single attachment for create or update. * * @since 4.7.0 * * @param WP_REST_Request $request Request object. * @return stdClass|WP_Error Post object. */ protected function prepare_item_for_database( $request ) { $prepared_attachment = parent::prepare_item_for_database( $request ); // Attachment caption (post_excerpt internally). if ( isset( $request['caption'] ) ) { if ( is_string( $request['caption'] ) ) { $prepared_attachment->post_excerpt = $request['caption']; } elseif ( isset( $request['caption']['raw'] ) ) { $prepared_attachment->post_excerpt = $request['caption']['raw']; } } // Attachment description (post_content internally). if ( isset( $request['description'] ) ) { if ( is_string( $request['description'] ) ) { $prepared_attachment->post_content = $request['description']; } elseif ( isset( $request['description']['raw'] ) ) { $prepared_attachment->post_content = $request['description']['raw']; } } if ( isset( $request['post'] ) ) { $prepared_attachment->post_parent = (int) $request['post']; } return $prepared_attachment; } /** * Prepares a single attachment output for response. * * @since 4.7.0 * @since 5.9.0 Renamed `$post` to `$item` to match parent class for PHP 8 named parameter support. * * @param WP_Post $item Attachment object. * @param WP_REST_Request $request Request object. * @return WP_REST_Response Response object. */ public function prepare_item_for_response( $item, $request ) { // Restores the more descriptive, specific name for use within this method. $post = $item; $response = parent::prepare_item_for_response( $post, $request ); $fields = $this->get_fields_for_response( $request ); $data = $response->get_data(); if ( in_array( 'description', $fields, true ) ) { $data['description'] = array( 'raw' => $post->post_content, /** This filter is documented in wp-includes/post-template.php */ 'rendered' => apply_filters( 'the_content', $post->post_content ), ); } if ( in_array( 'caption', $fields, true ) ) { /** This filter is documented in wp-includes/post-template.php */ $caption = apply_filters( 'get_the_excerpt', $post->post_excerpt, $post ); /** This filter is documented in wp-includes/post-template.php */ $caption = apply_filters( 'the_excerpt', $caption ); $data['caption'] = array( 'raw' => $post->post_excerpt, 'rendered' => $caption, ); } if ( in_array( 'alt_text', $fields, true ) ) { $data['alt_text'] = get_post_meta( $post->ID, '_wp_attachment_image_alt', true ); } if ( in_array( 'media_type', $fields, true ) ) { $data['media_type'] = wp_attachment_is_image( $post->ID ) ? 'image' : 'file'; } if ( in_array( 'mime_type', $fields, true ) ) { $data['mime_type'] = $post->post_mime_type; } if ( in_array( 'media_details', $fields, true ) ) { $data['media_details'] = wp_get_attachment_metadata( $post->ID ); // Ensure empty details is an empty object. if ( empty( $data['media_details'] ) ) { $data['media_details'] = new stdClass(); } elseif ( ! empty( $data['media_details']['sizes'] ) ) { foreach ( $data['media_details']['sizes'] as $size => &$size_data ) { if ( isset( $size_data['mime-type'] ) ) { $size_data['mime_type'] = $size_data['mime-type']; unset( $size_data['mime-type'] ); } // Use the same method image_downsize() does. $image_src = wp_get_attachment_image_src( $post->ID, $size ); if ( ! $image_src ) { continue; } $size_data['source_url'] = $image_src[0]; } $full_src = wp_get_attachment_image_src( $post->ID, 'full' ); if ( ! empty( $full_src ) ) { $data['media_details']['sizes']['full'] = array( 'file' => wp_basename( $full_src[0] ), 'width' => $full_src[1], 'height' => $full_src[2], 'mime_type' => $post->post_mime_type, 'source_url' => $full_src[0], ); } } else { $data['media_details']['sizes'] = new stdClass(); } } if ( in_array( 'post', $fields, true ) ) { $data['post'] = ! empty( $post->post_parent ) ? (int) $post->post_parent : null; } if ( in_array( 'source_url', $fields, true ) ) { $data['source_url'] = wp_get_attachment_url( $post->ID ); } if ( in_array( 'missing_image_sizes', $fields, true ) ) { require_once ABSPATH . 'wp-admin/includes/image.php'; $data['missing_image_sizes'] = array_keys( wp_get_missing_image_subsizes( $post->ID ) ); } $context = ! empty( $request['context'] ) ? $request['context'] : 'view'; $data = $this->filter_response_by_context( $data, $context ); $links = $response->get_links(); // Wrap the data in a response object. $response = rest_ensure_response( $data ); foreach ( $links as $rel => $rel_links ) { foreach ( $rel_links as $link ) { $response->add_link( $rel, $link['href'], $link['attributes'] ); } } /** * Filters an attachment returned from the REST API. * * Allows modification of the attachment right before it is returned. * * @since 4.7.0 * * @param WP_REST_Response $response The response object. * @param WP_Post $post The original attachment post. * @param WP_REST_Request $request Request used to generate the response. */ return apply_filters( 'rest_prepare_attachment', $response, $post, $request ); } /** * Retrieves the attachment's schema, conforming to JSON Schema. * * @since 4.7.0 * * @return array Item schema as an array. */ public function get_item_schema() { if ( $this->schema ) { return $this->add_additional_fields_schema( $this->schema ); } $schema = parent::get_item_schema(); $schema['properties']['alt_text'] = array( 'description' => __( 'Alternative text to display when attachment is not displayed.' ), 'type' => 'string', 'context' => array( 'view', 'edit', 'embed' ), 'arg_options' => array( 'sanitize_callback' => 'sanitize_text_field', ), ); $schema['properties']['caption'] = array( 'description' => __( 'The attachment caption.' ), 'type' => 'object', 'context' => array( 'view', 'edit', 'embed' ), 'arg_options' => array( 'sanitize_callback' => null, // Note: sanitization implemented in self::prepare_item_for_database(). 'validate_callback' => null, // Note: validation implemented in self::prepare_item_for_database(). ), 'properties' => array( 'raw' => array( 'description' => __( 'Caption for the attachment, as it exists in the database.' ), 'type' => 'string', 'context' => array( 'edit' ), ), 'rendered' => array( 'description' => __( 'HTML caption for the attachment, transformed for display.' ), 'type' => 'string', 'context' => array( 'view', 'edit', 'embed' ), 'readonly' => true, ), ), ); $schema['properties']['description'] = array( 'description' => __( 'The attachment description.' ), 'type' => 'object', 'context' => array( 'view', 'edit' ), 'arg_options' => array( 'sanitize_callback' => null, // Note: sanitization implemented in self::prepare_item_for_database(). 'validate_callback' => null, // Note: validation implemented in self::prepare_item_for_database(). ), 'properties' => array( 'raw' => array( 'description' => __( 'Description for the attachment, as it exists in the database.' ), 'type' => 'string', 'context' => array( 'edit' ), ), 'rendered' => array( 'description' => __( 'HTML description for the attachment, transformed for display.' ), 'type' => 'string', 'context' => array( 'view', 'edit' ), 'readonly' => true, ), ), ); $schema['properties']['media_type'] = array( 'description' => __( 'Attachment type.' ), 'type' => 'string', 'enum' => array( 'image', 'file' ), 'context' => array( 'view', 'edit', 'embed' ), 'readonly' => true, ); $schema['properties']['mime_type'] = array( 'description' => __( 'The attachment MIME type.' ), 'type' => 'string', 'context' => array( 'view', 'edit', 'embed' ), 'readonly' => true, ); $schema['properties']['media_details'] = array( 'description' => __( 'Details about the media file, specific to its type.' ), 'type' => 'object', 'context' => array( 'view', 'edit', 'embed' ), 'readonly' => true, ); $schema['properties']['post'] = array( 'description' => __( 'The ID for the associated post of the attachment.' ), 'type' => 'integer', 'context' => array( 'view', 'edit' ), ); $schema['properties']['source_url'] = array( 'description' => __( 'URL to the original attachment file.' ), 'type' => 'string', 'format' => 'uri', 'context' => array( 'view', 'edit', 'embed' ), 'readonly' => true, ); $schema['properties']['missing_image_sizes'] = array( 'description' => __( 'List of the missing image sizes of the attachment.' ), 'type' => 'array', 'items' => array( 'type' => 'string' ), 'context' => array( 'edit' ), 'readonly' => true, ); unset( $schema['properties']['password'] ); $this->schema = $schema; return $this->add_additional_fields_schema( $this->schema ); } /** * Handles an upload via raw POST data. * * @since 4.7.0 * @since 6.6.0 Added the `$time` parameter. * * @param string $data Supplied file data. * @param array $headers HTTP headers from the request. * @param string|null $time Optional. Time formatted in 'yyyy/mm'. Default null. * @return array|WP_Error Data from wp_handle_sideload(). */ protected function upload_from_data( $data, $headers, $time = null ) { if ( empty( $data ) ) { return new WP_Error( 'rest_upload_no_data', __( 'No data supplied.' ), array( 'status' => 400 ) ); } if ( empty( $headers['content_type'] ) ) { return new WP_Error( 'rest_upload_no_content_type', __( 'No Content-Type supplied.' ), array( 'status' => 400 ) ); } if ( empty( $headers['content_disposition'] ) ) { return new WP_Error( 'rest_upload_no_content_disposition', __( 'No Content-Disposition supplied.' ), array( 'status' => 400 ) ); } $filename = self::get_filename_from_disposition( $headers['content_disposition'] ); if ( empty( $filename ) ) { return new WP_Error( 'rest_upload_invalid_disposition', __( 'Invalid Content-Disposition supplied. Content-Disposition needs to be formatted as `attachment; filename="image.png"` or similar.' ), array( 'status' => 400 ) ); } if ( ! empty( $headers['content_md5'] ) ) { $content_md5 = array_shift( $headers['content_md5'] ); $expected = trim( $content_md5 ); $actual = md5( $data ); if ( $expected !== $actual ) { return new WP_Error( 'rest_upload_hash_mismatch', __( 'Content hash did not match expected.' ), array( 'status' => 412 ) ); } } // Get the content-type. $type = array_shift( $headers['content_type'] ); // Include filesystem functions to get access to wp_tempnam() and wp_handle_sideload(). require_once ABSPATH . 'wp-admin/includes/file.php'; // Save the file. $tmpfname = wp_tempnam( $filename ); $fp = fopen( $tmpfname, 'w+' ); if ( ! $fp ) { return new WP_Error( 'rest_upload_file_error', __( 'Could not open file handle.' ), array( 'status' => 500 ) ); } fwrite( $fp, $data ); fclose( $fp ); // Now, sideload it in. $file_data = array( 'error' => null, 'tmp_name' => $tmpfname, 'name' => $filename, 'type' => $type, ); $size_check = self::check_upload_size( $file_data ); if ( is_wp_error( $size_check ) ) { return $size_check; } $overrides = array( 'test_form' => false, ); $sideloaded = wp_handle_sideload( $file_data, $overrides, $time ); if ( isset( $sideloaded['error'] ) ) { @unlink( $tmpfname ); return new WP_Error( 'rest_upload_sideload_error', $sideloaded['error'], array( 'status' => 500 ) ); } return $sideloaded; } /** * Parses filename from a Content-Disposition header value. * * As per RFC6266: * * content-disposition = "Content-Disposition" ":" * disposition-type *( ";" disposition-parm ) * * disposition-type = "inline" | "attachment" | disp-ext-type * ; case-insensitive * disp-ext-type = token * * disposition-parm = filename-parm | disp-ext-parm * * filename-parm = "filename" "=" value * | "filename*" "=" ext-value * * disp-ext-parm = token "=" value * | ext-token "=" ext-value * ext-token = * * @since 4.7.0 * * @link https://tools.ietf.org/html/rfc2388 * @link https://tools.ietf.org/html/rfc6266 * * @param string[] $disposition_header List of Content-Disposition header values. * @return string|null Filename if available, or null if not found. */ public static function get_filename_from_disposition( $disposition_header ) { // Get the filename. $filename = null; foreach ( $disposition_header as $value ) { $value = trim( $value ); if ( ! str_contains( $value, ';' ) ) { continue; } list( , $attr_parts ) = explode( ';', $value, 2 ); $attr_parts = explode( ';', $attr_parts ); $attributes = array(); foreach ( $attr_parts as $part ) { if ( ! str_contains( $part, '=' ) ) { continue; } list( $key, $value ) = explode( '=', $part, 2 ); $attributes[ trim( $key ) ] = trim( $value ); } if ( empty( $attributes['filename'] ) ) { continue; } $filename = trim( $attributes['filename'] ); // Unquote quoted filename, but after trimming. if ( str_starts_with( $filename, '"' ) && str_ends_with( $filename, '"' ) ) { $filename = substr( $filename, 1, -1 ); } } return $filename; } /** * Retrieves the query params for collections of attachments. * * @since 4.7.0 * * @return array Query parameters for the attachment collection as an array. */ public function get_collection_params() { $params = parent::get_collection_params(); $params['status']['default'] = 'inherit'; $params['status']['items']['enum'] = array( 'inherit', 'private', 'trash' ); $media_types = $this->get_media_types(); $params['media_type'] = array( 'default' => null, 'description' => __( 'Limit result set to attachments of a particular media type.' ), 'type' => 'string', 'enum' => array_keys( $media_types ), ); $params['mime_type'] = array( 'default' => null, 'description' => __( 'Limit result set to attachments of a particular MIME type.' ), 'type' => 'string', ); return $params; } /** * Handles an upload via multipart/form-data ($_FILES). * * @since 4.7.0 * @since 6.6.0 Added the `$time` parameter. * * @param array $files Data from the `$_FILES` superglobal. * @param array $headers HTTP headers from the request. * @param string|null $time Optional. Time formatted in 'yyyy/mm'. Default null. * @return array|WP_Error Data from wp_handle_upload(). */ protected function upload_from_file( $files, $headers, $time = null ) { if ( empty( $files ) ) { return new WP_Error( 'rest_upload_no_data', __( 'No data supplied.' ), array( 'status' => 400 ) ); } // Verify hash, if given. if ( ! empty( $headers['content_md5'] ) ) { $content_md5 = array_shift( $headers['content_md5'] ); $expected = trim( $content_md5 ); $actual = md5_file( $files['file']['tmp_name'] ); if ( $expected !== $actual ) { return new WP_Error( 'rest_upload_hash_mismatch', __( 'Content hash did not match expected.' ), array( 'status' => 412 ) ); } } // Pass off to WP to handle the actual upload. $overrides = array( 'test_form' => false, ); // Bypasses is_uploaded_file() when running unit tests. if ( defined( 'DIR_TESTDATA' ) && DIR_TESTDATA ) { $overrides['action'] = 'wp_handle_mock_upload'; } $size_check = self::check_upload_size( $files['file'] ); if ( is_wp_error( $size_check ) ) { return $size_check; } // Include filesystem functions to get access to wp_handle_upload(). require_once ABSPATH . 'wp-admin/includes/file.php'; $file = wp_handle_upload( $files['file'], $overrides, $time ); if ( isset( $file['error'] ) ) { return new WP_Error( 'rest_upload_unknown_error', $file['error'], array( 'status' => 500 ) ); } return $file; } /** * Retrieves the supported media types. * * Media types are considered the MIME type category. * * @since 4.7.0 * * @return array Array of supported media types. */ protected function get_media_types() { $media_types = array(); foreach ( get_allowed_mime_types() as $mime_type ) { $parts = explode( '/', $mime_type ); if ( ! isset( $media_types[ $parts[0] ] ) ) { $media_types[ $parts[0] ] = array(); } $media_types[ $parts[0] ][] = $mime_type; } return $media_types; } /** * Determine if uploaded file exceeds space quota on multisite. * * Replicates check_upload_size(). * * @since 4.9.8 * * @param array $file $_FILES array for a given file. * @return true|WP_Error True if can upload, error for errors. */ protected function check_upload_size( $file ) { if ( ! is_multisite() ) { return true; } if ( get_site_option( 'upload_space_check_disabled' ) ) { return true; } $space_left = get_upload_space_available(); $file_size = filesize( $file['tmp_name'] ); if ( $space_left < $file_size ) { return new WP_Error( 'rest_upload_limited_space', /* translators: %s: Required disk space in kilobytes. */ sprintf( __( 'Not enough space to upload. %s KB needed.' ), number_format( ( $file_size - $space_left ) / KB_IN_BYTES ) ), array( 'status' => 400 ) ); } if ( $file_size > ( KB_IN_BYTES * get_site_option( 'fileupload_maxk', 1500 ) ) ) { return new WP_Error( 'rest_upload_file_too_big', /* translators: %s: Maximum allowed file size in kilobytes. */ sprintf( __( 'This file is too big. Files must be less than %s KB in size.' ), get_site_option( 'fileupload_maxk', 1500 ) ), array( 'status' => 400 ) ); } // Include multisite admin functions to get access to upload_is_user_over_quota(). require_once ABSPATH . 'wp-admin/includes/ms.php'; if ( upload_is_user_over_quota( false ) ) { return new WP_Error( 'rest_upload_user_quota_exceeded', __( 'You have used your space quota. Please delete files before uploading.' ), array( 'status' => 400 ) ); } return true; } /** * Gets the request args for the edit item route. * * @since 5.5.0 * * @return array */ protected function get_edit_media_item_args() { return array( 'src' => array( 'description' => __( 'URL to the edited image file.' ), 'type' => 'string', 'format' => 'uri', 'required' => true, ), 'modifiers' => array( 'description' => __( 'Array of image edits.' ), 'type' => 'array', 'minItems' => 1, 'items' => array( 'description' => __( 'Image edit.' ), 'type' => 'object', 'required' => array( 'type', 'args', ), 'oneOf' => array( array( 'title' => __( 'Rotation' ), 'properties' => array( 'type' => array( 'description' => __( 'Rotation type.' ), 'type' => 'string', 'enum' => array( 'rotate' ), ), 'args' => array( 'description' => __( 'Rotation arguments.' ), 'type' => 'object', 'required' => array( 'angle', ), 'properties' => array( 'angle' => array( 'description' => __( 'Angle to rotate clockwise in degrees.' ), 'type' => 'number', ), ), ), ), ), array( 'title' => __( 'Crop' ), 'properties' => array( 'type' => array( 'description' => __( 'Crop type.' ), 'type' => 'string', 'enum' => array( 'crop' ), ), 'args' => array( 'description' => __( 'Crop arguments.' ), 'type' => 'object', 'required' => array( 'left', 'top', 'width', 'height', ), 'properties' => array( 'left' => array( 'description' => __( 'Horizontal position from the left to begin the crop as a percentage of the image width.' ), 'type' => 'number', ), 'top' => array( 'description' => __( 'Vertical position from the top to begin the crop as a percentage of the image height.' ), 'type' => 'number', ), 'width' => array( 'description' => __( 'Width of the crop as a percentage of the image width.' ), 'type' => 'number', ), 'height' => array( 'description' => __( 'Height of the crop as a percentage of the image height.' ), 'type' => 'number', ), ), ), ), ), ), ), ), 'rotation' => array( 'description' => __( 'The amount to rotate the image clockwise in degrees. DEPRECATED: Use `modifiers` instead.' ), 'type' => 'integer', 'minimum' => 0, 'exclusiveMinimum' => true, 'maximum' => 360, 'exclusiveMaximum' => true, ), 'x' => array( 'description' => __( 'As a percentage of the image, the x position to start the crop from. DEPRECATED: Use `modifiers` instead.' ), 'type' => 'number', 'minimum' => 0, 'maximum' => 100, ), 'y' => array( 'description' => __( 'As a percentage of the image, the y position to start the crop from. DEPRECATED: Use `modifiers` instead.' ), 'type' => 'number', 'minimum' => 0, 'maximum' => 100, ), 'width' => array( 'description' => __( 'As a percentage of the image, the width to crop the image to. DEPRECATED: Use `modifiers` instead.' ), 'type' => 'number', 'minimum' => 0, 'maximum' => 100, ), 'height' => array( 'description' => __( 'As a percentage of the image, the height to crop the image to. DEPRECATED: Use `modifiers` instead.' ), 'type' => 'number', 'minimum' => 0, 'maximum' => 100, ), ); } }