link_service = $link_service; } /** * Sends the recovery mode email if the rate limit has not been sent. * * @since 5.2.0 * * @param int $rate_limit Number of seconds before another email can be sent. * @param array $error Error details from `error_get_last()`. * @param array $extension { * The extension that caused the error. * * @type string $slug The extension slug. The plugin or theme's directory. * @type string $type The extension type. Either 'plugin' or 'theme'. * } * @return true|WP_Error True if email sent, WP_Error otherwise. */ public function maybe_send_recovery_mode_email( $rate_limit, $error, $extension ) { $last_sent = get_option( self::RATE_LIMIT_OPTION ); if ( ! $last_sent || time() > $last_sent + $rate_limit ) { if ( ! update_option( self::RATE_LIMIT_OPTION, time() ) ) { return new WP_Error( 'storage_error', __( 'Could not update the email last sent time.' ) ); } $sent = $this->send_recovery_mode_email( $rate_limit, $error, $extension ); if ( $sent ) { return true; } return new WP_Error( 'email_failed', sprintf( /* translators: %s: mail() */ __( 'The email could not be sent. Possible reason: your host may have disabled the %s function.' ), 'mail()' ) ); } $err_message = sprintf( /* translators: 1: Last sent as a human time diff, 2: Wait time as a human time diff. */ __( 'A recovery link was already sent %1$s ago. Please wait another %2$s before requesting a new email.' ), human_time_diff( $last_sent ), human_time_diff( $last_sent + $rate_limit ) ); return new WP_Error( 'email_sent_already', $err_message ); } /** * Clears the rate limit, allowing a new recovery mode email to be sent immediately. * * @since 5.2.0 * * @return bool True on success, false on failure. */ public function clear_rate_limit() { return delete_option( self::RATE_LIMIT_OPTION ); } /** * Sends the Recovery Mode email to the site admin email address. * * @since 5.2.0 * * @param int $rate_limit Number of seconds before another email can be sent. * @param array $error Error details from `error_get_last()`. * @param array $extension { * The extension that caused the error. * * @type string $slug The extension slug. The directory of the plugin or theme. * @type string $type The extension type. Either 'plugin' or 'theme'. * } * @return bool Whether the email was sent successfully. */ private function send_recovery_mode_email( $rate_limit, $error, $extension ) { $url = $this->link_service->generate_url(); $blogname = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ); $switched_locale = switch_to_locale( get_locale() ); if ( $extension ) { $cause = $this->get_cause( $extension ); $details = wp_strip_all_tags( wp_get_extension_error_description( $error ) ); if ( $details ) { $header = __( 'Error Details' ); $details = "\n\n" . $header . "\n" . str_pad( '', strlen( $header ), '=' ) . "\n" . $details; } } else { $cause = ''; $details = ''; } /** * Filters the support message sent with the the fatal error protection email. * * @since 5.2.0 * * @param string $message The Message to include in the email. */ $support = apply_filters( 'recovery_email_support_info', __( 'Please contact your host for assistance with investigating this issue further.' ) ); /** * Filters the debug information included in the fatal error protection email. * * @since 5.3.0 * * @param array $message An associative array of debug information. */ $debug = apply_filters( 'recovery_email_debug_info', $this->get_debug( $extension ) ); /* translators: Do not translate LINK, EXPIRES, CAUSE, DETAILS, SITEURL, PAGEURL, SUPPORT. DEBUG: those are placeholders. */ $message = __( 'Howdy! WordPress has a built-in feature that detects when a plugin or theme causes a fatal error on your site, and notifies you with this automated email. ###CAUSE### First, visit your website (###SITEURL###) and check for any visible issues. Next, visit the page where the error was caught (###PAGEURL###) and check for any visible issues. ###SUPPORT### If your site appears broken and you can\'t access your dashboard normally, WordPress now has a special "recovery mode". This lets you safely login to your dashboard and investigate further. ###LINK### To keep your site safe, this link will expire in ###EXPIRES###. Don\'t worry about that, though: a new link will be emailed to you if the error occurs again after it expires. When seeking help with this issue, you may be asked for some of the following information: ###DEBUG### ###DETAILS###' ); $message = str_replace( array( '###LINK###', '###EXPIRES###', '###CAUSE###', '###DETAILS###', '###SITEURL###', '###PAGEURL###', '###SUPPORT###', '###DEBUG###', ), array( $url, human_time_diff( time() + $rate_limit ), $cause ? "\n{$cause}\n" : "\n", $details, home_url( '/' ), home_url( $_SERVER['REQUEST_URI'] ), $support, implode( "\r\n", $debug ), ), $message ); $email = array( 'to' => $this->get_recovery_mode_email_address(), /* translators: %s: Site title. */ 'subject' => __( '[%s] Your Site is Experiencing a Technical Issue' ), 'message' => $message, 'headers' => '', 'attachments' => '', ); /** * Filters the contents of the Recovery Mode email. * * @since 5.2.0 * @since 5.6.0 The `$email` argument includes the `attachments` key. * * @param array $email { * Used to build a call to wp_mail(). * * @type string|array $to Array or comma-separated list of email addresses to send message. * @type string $subject Email subject * @type string $message Message contents * @type string|array $headers Optional. Additional headers. * @type string|array $attachments Optional. Files to attach. * } * @param string $url URL to enter recovery mode. */ $email = apply_filters( 'recovery_mode_email', $email, $url ); $sent = wp_mail( $email['to'], wp_specialchars_decode( sprintf( $email['subject'], $blogname ) ), $email['message'], $email['headers'], $email['attachments'] ); if ( $switched_locale ) { restore_previous_locale(); } return $sent; } /** * Gets the email address to send the recovery mode link to. * * @since 5.2.0 * * @return string Email address to send recovery mode link to. */ private function get_recovery_mode_email_address() { if ( defined( 'RECOVERY_MODE_EMAIL' ) && is_email( RECOVERY_MODE_EMAIL ) ) { return RECOVERY_MODE_EMAIL; } return get_option( 'admin_email' ); } /** * Gets the description indicating the possible cause for the error. * * @since 5.2.0 * * @param array $extension { * The extension that caused the error. * * @type string $slug The extension slug. The directory of the plugin or theme. * @type string $type The extension type. Either 'plugin' or 'theme'. * } * @return string Message about which extension caused the error. */ private function get_cause( $extension ) { if ( 'plugin' === $extension['type'] ) { $plugin = $this->get_plugin( $extension ); if ( false === $plugin ) { $name = $extension['slug']; } else { $name = $plugin['Name']; } /* translators: %s: Plugin name. */ $cause = sprintf( __( 'In this case, WordPress caught an error with one of your plugins, %s.' ), $name ); } else { $theme = wp_get_theme( $extension['slug'] ); $name = $theme->exists() ? $theme->display( 'Name' ) : $extension['slug']; /* translators: %s: Theme name. */ $cause = sprintf( __( 'In this case, WordPress caught an error with your theme, %s.' ), $name ); } return $cause; } /** * Return the details for a single plugin based on the extension data from an error. * * @since 5.3.0 * * @param array $extension { * The extension that caused the error. * * @type string $slug The extension slug. The directory of the plugin or theme. * @type string $type The extension type. Either 'plugin' or 'theme'. * } * @return array|false A plugin array {@see get_plugins()} or `false` if no plugin was found. */ private function get_plugin( $extension ) { if ( ! function_exists( 'get_plugins' ) ) { require_once ABSPATH . 'wp-admin/includes/plugin.php'; } $plugins = get_plugins(); // Assume plugin main file name first since it is a common convention. if ( isset( $plugins[ "{$extension['slug']}/{$extension['slug']}.php" ] ) ) { return $plugins[ "{$extension['slug']}/{$extension['slug']}.php" ]; } else { foreach ( $plugins as $file => $plugin_data ) { if ( str_starts_with( $file, "{$extension['slug']}/" ) || $file === $extension['slug'] ) { return $plugin_data; } } } return false; type_attr = " type='text/css'"; } /** * Fires when the WP_Styles instance is initialized. * * @since 2.6.0 * * @param WP_Styles $wp_styles WP_Styles instance (passed by reference). */ do_action_ref_array( 'wp_default_styles', array( &$this ) ); } /** * Processes a style dependency. * * @since 2.6.0 * @since 5.5.0 Added the `$group` parameter. * * @see WP_Dependencies::do_item() * * @param string $handle The style's registered handle. * @param int|false $group Optional. Group level: level (int), no groups (false). * Default false. * @return bool True on success, false on failure. */ public function do_item( $handle, $group = false ) { if ( ! parent::do_item( $handle ) ) { return false; } $obj = $this->registered[ $handle ]; if ( $obj->extra['conditional'] ?? false ) { return false; } if ( null === $obj->ver ) { $ver = ''; } else { $ver = $obj->ver ? $obj->ver : $this->default_version; } if ( isset( $this->args[ $handle ] ) ) { $ver = $ver ? $ver . '&' . $this->args[ $handle ] : $this->args[ $handle ]; } $src = $obj->src; $inline_style = $this->print_inline_style( $handle, false ); if ( $inline_style ) { $inline_style_tag = sprintf( "\n", esc_attr( $handle ), $this->type_attr, $inline_style ); } else { $inline_style_tag = ''; } if ( $this->do_concat ) { if ( $this->in_default_dir( $src ) && ! isset( $obj->extra['alt'] ) ) { $this->concat .= "$handle,"; $this->concat_version .= "$handle$ver"; $this->print_code .= $inline_style; return true; } } if ( isset( $obj->args ) ) { $media = $obj->args; } else { $media = 'all'; } // A single item may alias a set of items, by having dependencies, but no source. if ( ! $src ) { if ( $inline_style_tag ) { if ( $this->do_concat ) { $this->print_html .= $inline_style_tag; } else { echo $inline_style_tag; } } return true; } $href = $this->_css_href( $src, $ver, $handle ); if ( ! $href ) { return true; } $rel = isset( $obj->extra['alt'] ) && $obj->extra['alt'] ? 'alternate stylesheet' : 'stylesheet'; $title = isset( $obj->extra['title'] ) ? $obj->extra['title'] : ''; $tag = sprintf( "\n", $rel, esc_attr( $handle ), $title ? sprintf( " title='%s'", esc_attr( $title ) ) : '', $href, $this->type_attr, esc_attr( $media ) ); /** * Filters the HTML link tag of an enqueued style. * * @since 2.6.0 * @since 4.3.0 Introduced the `$href` parameter. * @since 4.5.0 Introduced the `$media` parameter. * * @param string $tag The link tag for the enqueued style. * @param string $handle The style's registered handle. * @param string $href The stylesheet's source URL. * @param string $media The stylesheet's media attribute. */ $tag = apply_filters( 'style_loader_tag', $tag, $handle, $href, $media ); if ( 'rtl' === $this->text_direction && isset( $obj->extra['rtl'] ) && $obj->extra['rtl'] ) { if ( is_bool( $obj->extra['rtl'] ) || 'replace' === $obj->extra['rtl'] ) { $suffix = isset( $obj->extra['suffix'] ) ? $obj->extra['suffix'] : ''; $rtl_href = str_replace( "{$suffix}.css", "-rtl{$suffix}.css", $this->_css_href( $src, $ver, "$handle-rtl" ) ); } else { $rtl_href = $this->_css_href( $obj->extra['rtl'], $ver, "$handle-rtl" ); } $rtl_tag = sprintf( "\n", $rel, esc_attr( $handle ), $title ? sprintf( " title='%s'", esc_attr( $title ) ) : '', $rtl_href, $this->type_attr, esc_attr( $media ) ); /** This filter is documented in wp-includes/class-wp-styles.php */ $rtl_tag = apply_filters( 'style_loader_tag', $rtl_tag, $handle, $rtl_href, $media ); if ( 'replace' === $obj->extra['rtl'] ) { $tag = $rtl_tag; } else { $tag .= $rtl_tag; } } if ( $this->do_concat ) { $this->print_html .= $tag; if ( $inline_style_tag ) { $this->print_html .= $inline_style_tag; } } else { echo $tag; $this->print_inline_style( $handle ); } return true; } /** * Adds extra CSS styles to a registered stylesheet. * * @since 3.3.0 * * @param string $handle The style's registered handle. * @param string $code String containing the CSS styles to be added. * @return bool True on success, false on failure. */ public function add_inline_style( $handle, $code ) { if ( ! $code ) { return false; } $after = $this->get_data( $handle, 'after' ); if ( ! $after ) { $after = array(); } $after[] = $code; return $this->add_data( $handle, 'after', $after ); } /** * Prints extra CSS styles of a registered stylesheet. * * @since 3.3.0 * * @param string $handle The style's registered handle. * @param bool $display Optional. Whether to print the inline style * instead of just returning it. Default true. * @return string|bool False if no data exists, inline styles if `$display` is true, * true otherwise. */ public function print_inline_style( $handle, $display = true ) { $output = $this->get_data( $handle, 'after' ); if ( empty( $output ) || ! is_array( $output ) ) { return false; } if ( ! $this->do_concat ) { // Obtain the original `src` for a stylesheet possibly inlined by wp_maybe_inline_styles(). $inlined_src = $this->get_data( $handle, 'inlined_src' ); // If there's only one `after` inline style, and that inline style had been inlined, then use the $inlined_src // as the sourceURL. Otherwise, if there is more than one inline `after` style associated with the handle, // then resort to using the handle to construct the sourceURL since there isn't a single source. if ( count( $output ) === 1 && is_string( $inlined_src ) && strlen( $inlined_src ) > 0 ) { $source_url = esc_url_raw( $inlined_src ); } else { $source_url = rawurlencode( "{$handle}-inline-css" ); } $output[] = sprintf( '/*# sourceURL=%s */', $source_url ); } $output = implode( "\n", $output ); if ( ! $display ) { return $output; } printf( "\n", esc_attr( $handle ), $this->type_attr, $output ); return true; } /** * Overrides the add_data method from WP_Dependencies, to allow unsetting dependencies for conditional styles. * * @since 6.9.0 * * @param string $handle Name of the item. Should be unique. * @param string $key The data key. * @param mixed $value The data value. * @return bool True on success, false on failure. */ public function add_data( $handle, $key, $value ) { if ( ! isset( $this->registered[ $handle ] ) ) { return false; } if ( 'conditional' === $key ) { $this->registered[ $handle ]->deps = array(); } return parent::add_data( $handle, $key, $value ); } /** * Determines style dependencies. * * @since 2.6.0 * * @see WP_Dependencies::all_deps() * * @param string|string[] $handles Item handle (string) or item handles (array of strings). * @param bool $recursion Optional. Internal flag that function is calling itself. * Default false. * @param int|false $group Optional. Group level: level (int), no groups (false). * Default false. * @return bool True on success, false on failure. */ public function all_deps( $handles, $recursion = false, $group = false ) { $result = parent::all_deps( $handles, $recursion, $group ); if ( ! $recursion ) { /** * Filters the array of enqueued styles before processing for output. * * @since 2.6.0 * * @param string[] $to_do The list of enqueued style handles about to be processed. */ $this->to_do = apply_filters( 'print_styles_array', $this->to_do ); } return $result; } /** * Generates an enqueued style's fully-qualified URL. * * @since 2.6.0 * * @param string $src The source of the enqueued style. * @param string $ver The version of the enqueued style. * @param string $handle The style's registered handle. * @return string Style's fully-qualified URL. */ public function _css_href( $src, $ver, $handle ) { if ( ! is_bool( $ __( 'Export Users', 'my-plugin' ), * 'description' => __( 'Exports user data to CSV format.', 'my-plugin' ), * 'category' => 'data-export', * 'execute_callback' => 'my_plugin_export_users', * 'permission_callback' => function(): bool { * return current_user_can( 'export' ); * }, * 'input_schema' => array( * 'type' => 'string', * 'enum' => array( 'subscriber', 'contributor', 'author', 'editor', 'administrator' ), * 'description' => __( 'Limits the export to users with this role.', 'my-plugin' ), * 'required' => false, * ), * 'output_schema' => array( * 'type' => 'string', * 'description' => __( 'User data in CSV format.', 'my-plugin' ), * 'required' => true, * ), * 'meta' => array( * 'show_in_rest' => true, * ), * ) * ); * } * add_action( 'wp_abilities_api_init', 'my_plugin_register_abilities' ); * * Once registered, abilities can be checked, retrieved, and managed: * * // Checks if an ability is registered, and prints its label. * if ( wp_has_ability( 'my-plugin/export-users' ) ) { * $ability = wp_get_ability( 'my-plugin/export-users' ); * * echo $ability->get_label(); * } * * // Gets all registered abilities. * $all_abilities = wp_get_abilities(); * * // Unregisters when no longer needed. * wp_unregister_ability( 'my-plugin/export-users' ); * * ## Best Practices * * - Always register abilities on the `wp_abilities_api_init` hook. * - Use namespaced ability names to prevent conflicts. * - Implement robust permission checks in permission callbacks. * - Provide an `input_schema` to ensure data integrity and document expected inputs. * - Define an `output_schema` to describe return values and validate responses. * - Return `WP_Error` objects for failures rather than throwing exceptions. * - Use internationalization functions for all user-facing strings. * * @package WordPress * @subpackage Abilities_API * @since 6.9.0 */ declare( strict_types = 1 ); /** * Registers a new ability using the Abilities API. It requires three steps: * * 1. Hook into the `wp_abilities_api_init` action. * 2. Call `wp_register_ability()` with a namespaced name and configuration. * 3. Provide execute and permission callbacks. * * Example: * * function my_plugin_register_abilities(): void { * wp_register_ability( * 'my-plugin/analyze-text', * array( * 'label' => __( 'Analyze Text', 'my-plugin' ), * 'description' => __( 'Performs sentiment analysis on provided text.', 'my-plugin' ), * 'category' => 'text-processing', * 'input_schema' => array( * 'type' => 'string', * 'description' => __( 'The text to be analyzed.', 'my-plugin' ), * 'minLength' => 10, * 'required' => true, * ), * 'output_schema' => array( * 'type' => 'string', * 'enum' => array( 'positive', 'negative', 'neutral' ), * 'description' => __( 'The sentiment result: positive, negative, or neutral.', 'my-plugin' ), * 'required' => true, * ), * 'execute_callback' => 'my_plugin_analyze_text', * 'permission_callback' => 'my_plugin_can_analyze_text', * 'meta' => array( * 'annotations' => array( * 'readonly' => true, * ), * 'show_in_rest' => true, * ), * ) * ); * } * add_action( 'wp_abilities_api_init', 'my_plugin_register_abilities' ); * * ### Naming Conventions * * Ability names must follow these rules: * * - Include a namespace prefix (e.g., `my-plugin/my-ability`). * - Use only lowercase alphanumeric characters, dashes, and forward slashes. * - Use descriptive, action-oriented names (e.g., `process-payment`, `generate-report`). * * ### Categories * * Abilities must be organized into categories. Ability categories provide better * discoverability and must be registered before the abilities that reference them: * * function my_plugin_register_categories(): void { * wp_register_ability_category( * 'text-processing', * array( * 'label' => __( 'Text Processing', 'my-plugin' ), * 'description' => __( 'Abilities for analyzing and transforming text.', 'my-plugin' ), * ) * ); * } * add_action( 'wp_abilities_api_categories_init', 'my_plugin_register_categories' ); * * ### Input and Output Schemas * * Schemas define the expected structure, type, and constraints for ability inputs * and outputs using JSON Schema syntax. They serve two critical purposes: automatic * validation of data passed to and returned from abilities, and self-documenting * API contracts for developers. * * WordPress implements a validator based on a subset of the JSON Schema Version 4 * specification (https://json-schema.org/specification-links.html#draft-4). * For details on supported JSON Schema properties and syntax, see the * related WordPress REST API Schema documentation: * https://developer.wordpress.org/rest-api/extending-the-rest-api/schema/#json-schema-basics * * Defining schemas is mandatory when there is a value to pass or return. * They ensure data integrity, improve developer experience, and enable * better documentation: * * 'input_schema' => array( * 'type' => 'string', * 'description' => __( 'The text to be analyzed.', 'my-plugin' ), * 'minLength' => 10, * 'required' => true, * ), * 'output_schema' => array( * 'type' => 'string', * 'enum' => array( 'positive', 'negative', 'neutral' ), * 'description' => __( 'The sentiment result: positive, negative, or neutral.', 'my-plugin' ), * 'required' => true, * ), * * ### Callbacks * * #### Execute Callback * * The execute callback performs the ability's core functionality. It receives * optional input data and returns either a result or `WP_Error` on failure. * * function my_plugin_analyze_text( string $input ): string|WP_Error { * $score = My_Plugin::perform_sentiment_analysis( $input ); * if ( is_wp_error( $score ) ) { * return $score; * } * return My_Plugin::interpret_sentiment_score( $score ); * } * * #### Permission Callback * * The permission callback determines whether the ability can be executed. * It receives the same input as the execute callback and must return a * boolean or `WP_Error`. Common use cases include checking user capabilities, * validating API keys, or verifying system state: * * function my_plugin_can_analyze_text( string $input ): bool|WP_Error { * return current_user_can( 'edit_posts' ); * } * * ### REST API Integration * * Abilities can be exposed through the REST API by setting `show_in_rest` * to `true` in the meta configuration: * * 'meta' => array( * 'show_in_rest' => true, * ), * * This allows abilities to be invoked via HTTP requests to the WordPress REST API. * * @since 6.9.0 * * @see WP_Abilities_Registry::register() * @see wp_register_ability_category() * @see wp_unregister_ability() * * @param string $name The name of the ability. Must be a namespaced string containing * a prefix, e.g., `my-plugin/my-ability`. Can only contain lowercase * alphanumeric characters, dashes, and forward slashes. * @param array $args { * An associative array of arguments for configuring the ability. * * @type string $label Required. The human-readable label for the ability. * @type string $description Required. A detailed description of what the ability does * and when it should be used. * @type string $category Required. The ability category slug this ability belongs to. * The ability category must be registered via `wp_register_ability_category()` * before registering the ability. * @type callable $execute_callback Required. A callback function to execute when the ability is invoked. * Receives optional mixed input data and must return either a result * value (any type) or a `WP_Error` object on failure. * @type callable $permission_callback Required. A callback function to check permissions before execution. * Receives optional mixed input data (same as `execute_callback`) and * must return `true`/`false` for simple checks, or `WP_Error` for * detailed error responses. * @type array $input_schema Optional. JSON Schema definition for validating the ability's input. * Must be a valid JSON Schema object defining the structure and * constraints for input data. Used for automatic validation and * API documentation. * @type array $output_schema Optional. JSON Schema definition for the ability's output. * Describes the structure of successful return values from * `execute_callback`. Used for documentation and validation. * @type array $meta { * Optional. Additional metadata for the ability. * * @type array $annotations { * Optional. Semantic annotations describing the ability's behavioral characteristics. * These annotations are hints for tooling and documentation. * * @type bool|null $readonly Optional. If true, the ability does not modify its environment. * @type bool|null $destructive Optional. If true, the ability may perform destructive updates to its environment. * If false, the ability performs only additive updates. * @type bool|null $idempotent Optional. If true, calling the ability repeatedly with the same arguments * will have no additional effect on its environment. * } * @type bool $show_in_rest Optional. Whether to expose this ability in the REST API. * When true, the ability can be invoked via HTTP requests. * Default false. * } * @type string $ability_class Optional. Fully-qualified custom class name to instantiate * instead of the default `WP_Ability` class. The custom class * must extend `WP_Ability`. Useful for advanced customization * of ability behavior. * } * @return WP_Ability|null The registered ability instance on success, `null` on failure. */ function wp_register_ability( string $name, array $args ): ?WP_Ability { if ( ! doing_action( 'wp_abilities_api_init' ) ) { _doing_it_wrong( __FUNCTION__, sprintf( /* translators: 1: wp_abilities_api_init, 2: string value of the ability name. */ __( 'Abilities must be registered on the %1$s action. The ability %2$s was not registered.' ), 'wp_abilities_api_init', '' . esc_html( $name ) . '' ), '6.9.0' ); return null; } $registry = WP_Abilities_Registry::get_instance(); if ( null === $registry ) { return null; } return $registry->register( $name, $args ); } /** * Unregisters an ability from the Abilities API. * * Removes a previously registered ability from the global registry. Use this to * disable abilities provided by other plugins or when an ability is no longer needed. * * Can be called at any time after the ability has been registered. * * Example: * * if ( wp_has_ability( 'other-plugin/some-ability' ) ) { * wp_unregister_ability( 'other-plugin/some-ability' ); * } * * @since 6.9.0 * * @see WP_Abilities_Registry::unregister() * @see wp_register_ability() * * @param string $name The name of the ability to unregister, including namespace prefix * (e.g., 'my-plugin/my-ability'). * @return WP_Ability|null The unregistered ability instance on success, `null` on failure. */ function wp_unregister_ability( string $name ): ?WP_Ability { $registry = WP_Abilities_Registry::get_instance(); if ( null === $registry ) { return null; } return $registry->unregister( $name ); } /** * Checks if an ability is registered. * * Use this for conditional logic and feature detection before attempting to * retrieve or use an ability. * * Example: * * // Displays different UI based on available abilities. * if ( wp_has_ability( 'premium-plugin/advanced-export' ) ) { * echo 'Export with Premium Features'; * } else { * echo 'Basic Export'; * } * * @since 6.9.0 * * @see WP_Abilities_Registry::is_registered() * @see wp_get_ability() * * @param string $name The name of the ability to check, including namespace prefix * (e.g., 'my-plugin/my-ability'). * @return bool `true` if the ability is registered, `false` otherwise. */ function wp_has_ability( string $name ): bool { $registry = WP_Abilities_Registry::get_instance(); if ( null === $registry ) { return false; } return $registry->is_registered( $name ); } /** * Retrieves a registered ability. * * Returns the ability instance for inspection or use. The instance provides access * to the ability's configuration, metadata, and execution methods. * * Example: * * // Prints information about a registered ability. * $ability = wp_get_ability( 'my-plugin/export-data' ); * if ( $ability ) { * echo $ability->get_label() . ': ' . $ability->get_description(); * } * * @since 6.9.0 * * @see WP_Abilities_Registry::get_registered() * @see wp_has_ability() * * @param string $name The name of the ability, including namespace prefix * (e.g., 'my-plugin/my-ability'). * @return WP_Ability|null The registered ability instance, or `null` if not registered. */ function wp_get_ability( string $name ): ?WP_Ability { $registry = WP_Abilities_Registry::get_instance(); if ( null === $registry ) { return null; } return $registry->get_registered( $name ); } /** * Retrieves all registered abilities. * * Returns an array of all ability instances currently registered in the system. * Use this for discovery, debugging, or building administrative interfaces. * * Example: * * // Prints information about all available abilities. * $abilities = wp_get_abilities(); * foreach ( $abilities as $ability ) { * echo $ability->get_label() . ': ' . $ability->get_description() . "\n"; * } * * @since 6.9.0 * * @see WP_Abilities_Registry::get_all_registered() * * @return WP_Ability[] An array of registered WP_Ability instances. Returns an empty * array if no abilities are registered or if the registry is unavailable. */ function wp_get_abilities(): array { $registry = WP_Abilities_Registry::get_instance(); if ( null === $registry ) { return array(); } return $registry->get_all_registered(); } /** * Registers a new ability category. * * Ability categories provide a way to organize and group related abilities for better * discoverability and management. Ability categories must be registered before abilities * that reference them. * * Ability categories must be registered on the `wp_abilities_api_categories_init` action hook. * * Example: * * function my_plugin_register_categories() { * wp_register_ability_category( * 'content-management', * array( * 'label' => __( 'Content Management', 'my-plugin' ), * 'description' => __( 'Abilities for managing and organizing content.', 'my-plugin' ), * ) * ); * } * add_action( 'wp_abilities_api_categories_init', 'my_plugin_register_categories' ); * * @since 6.9.0 * * @see WP_Ability_Categories_Registry::register() * @see wp_register_ability() * @see wp_unregister_ability_category() * * @param string $slug The unique slug for the ability category. Must contain only lowercase * alphanumeric characters and dashes (e.g., 'data-export'). * @param array $args { * An associative array of arguments for the ability category. * * @type string $label Required. The human-readable label for the ability category. * @type string $description Required. A description of what abilities in this category do. * @type array $meta Optional. Additional metadata for the ability category. * } * @return WP_Ability_Category|null The registered ability category instance on success, `null` on failure. */ function wp_register_ability_category( string $slug, array $args ): ?WP_Ability_Category { if ( ! doing_action( 'wp_abilities_api_categories_init' ) ) { _doing_it_wrong( __FUNCTION__, sprintf( /* translators: 1: wp_abilities_api_categories_init, 2: ability category slug. */ __( 'Ability categories must be registered on the %1$s action. The ability category %2$s was not registered.' ), 'wp_abilities_api_categories_init', '' . esc_html( $slug ) . '' ), '6.9.0' ); return null; } $registry = WP_Ability_Categories_Registry::get_instance(); if ( null === $registry ) { return null; } return $registry->register( $slug, $args ); } /** * Unregisters an ability category. * * Removes a previously reg