[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Abilities API
   4   *
   5   * Defines functions for managing abilities in WordPress.
   6   *
   7   * @package WordPress
   8   * @subpackage Abilities_API
   9   * @since 6.9.0
  10   */
  11  
  12  declare( strict_types = 1 );
  13  
  14  /**
  15   * Registers a new ability using Abilities API.
  16   *
  17   * Note: Should only be used on the {@see 'wp_abilities_api_init'} hook.
  18   *
  19   * @since 6.9.0
  20   *
  21   * @see WP_Abilities_Registry::register()
  22   *
  23   * @param string               $name The name of the ability. The name must be a string containing a namespace
  24   *                                   prefix, i.e. `my-plugin/my-ability`. It can only contain lowercase
  25   *                                   alphanumeric characters, dashes and the forward slash.
  26   * @param array<string, mixed> $args {
  27   *     An associative array of arguments for the ability.
  28   *
  29   *     @type string               $label               The human-readable label for the ability.
  30   *     @type string               $description         A detailed description of what the ability does.
  31   *     @type string               $category            The ability category slug this ability belongs to.
  32   *     @type callable             $execute_callback    A callback function to execute when the ability is invoked.
  33   *                                                     Receives optional mixed input and returns mixed result or WP_Error.
  34   *     @type callable             $permission_callback A callback function to check permissions before execution.
  35   *                                                     Receives optional mixed input and returns bool or WP_Error.
  36   *     @type array<string, mixed> $input_schema        Optional. JSON Schema definition for the ability's input.
  37   *     @type array<string, mixed> $output_schema       Optional. JSON Schema definition for the ability's output.
  38   *     @type array<string, mixed> $meta                  {
  39   *         Optional. Additional metadata for the ability.
  40   *
  41   *         @type array<string, null|bool> $annotations  Optional. Annotation metadata for the ability.
  42   *         @type bool                     $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
  43   *     }
  44   *     @type string               $ability_class       Optional. Custom class to instantiate instead of WP_Ability.
  45   * }
  46   * @return WP_Ability|null An instance of registered ability on success, null on failure.
  47   */
  48  function wp_register_ability( string $name, array $args ): ?WP_Ability {
  49      if ( ! did_action( 'wp_abilities_api_init' ) ) {
  50          _doing_it_wrong(
  51              __FUNCTION__,
  52              sprintf(
  53                  /* translators: 1: abilities_api_init, 2: string value of the ability name. */
  54                  esc_html__( 'Abilities must be registered on the %1$s action. The ability %2$s was not registered.' ),
  55                  '<code>abilities_api_init</code>',
  56                  '<code>' . esc_html( $name ) . '</code>'
  57              ),
  58              '6.9.0'
  59          );
  60          return null;
  61      }
  62  
  63      $registry = WP_Abilities_Registry::get_instance();
  64      if ( null === $registry ) {
  65          return null;
  66      }
  67  
  68      return $registry->register( $name, $args );
  69  }
  70  
  71  /**
  72   * Unregisters an ability from the Abilities API.
  73   *
  74   * @since 6.9.0
  75   *
  76   * @see WP_Abilities_Registry::unregister()
  77   *
  78   * @param string $name The name of the registered ability, with its namespace.
  79   * @return WP_Ability|null The unregistered ability instance on success, null on failure.
  80   */
  81  function wp_unregister_ability( string $name ): ?WP_Ability {
  82      $registry = WP_Abilities_Registry::get_instance();
  83      if ( null === $registry ) {
  84          return null;
  85      }
  86  
  87      return $registry->unregister( $name );
  88  }
  89  
  90  /**
  91   * Checks if an ability is registered.
  92   *
  93   * @since 6.9.0
  94   *
  95   * @see WP_Abilities_Registry::is_registered()
  96   *
  97   * @param string $name The name of the registered ability, with its namespace.
  98   * @return bool True if the ability is registered, false otherwise.
  99   */
 100  function wp_has_ability( string $name ): bool {
 101      $registry = WP_Abilities_Registry::get_instance();
 102      if ( null === $registry ) {
 103          return false;
 104      }
 105  
 106      return $registry->is_registered( $name );
 107  }
 108  
 109  /**
 110   * Retrieves a registered ability using Abilities API.
 111   *
 112   * @since 6.9.0
 113   *
 114   * @see WP_Abilities_Registry::get_registered()
 115   *
 116   * @param string $name The name of the registered ability, with its namespace.
 117   * @return WP_Ability|null The registered ability instance, or null if it is not registered.
 118   */
 119  function wp_get_ability( string $name ): ?WP_Ability {
 120      $registry = WP_Abilities_Registry::get_instance();
 121      if ( null === $registry ) {
 122          return null;
 123      }
 124  
 125      return $registry->get_registered( $name );
 126  }
 127  
 128  /**
 129   * Retrieves all registered abilities using Abilities API.
 130   *
 131   * @since 6.9.0
 132   *
 133   * @see WP_Abilities_Registry::get_all_registered()
 134   *
 135   * @return WP_Ability[] The array of registered abilities.
 136   */
 137  function wp_get_abilities(): array {
 138      $registry = WP_Abilities_Registry::get_instance();
 139      if ( null === $registry ) {
 140          return array();
 141      }
 142  
 143      return $registry->get_all_registered();
 144  }
 145  
 146  /**
 147   * Registers a new ability category.
 148   *
 149   * @since 6.9.0
 150   *
 151   * @see WP_Ability_Categories_Registry::register()
 152   *
 153   * @param string               $slug The unique slug for the ability category. Must contain only lowercase
 154   *                                   alphanumeric characters and dashes.
 155   * @param array<string, mixed> $args {
 156   *     An associative array of arguments for the ability category.
 157   *
 158   *     @type string               $label       The human-readable label for the ability category.
 159   *     @type string               $description A description of the ability category.
 160   *     @type array<string, mixed> $meta        Optional. Additional metadata for the ability category.
 161   * }
 162   * @return WP_Ability_Category|null The registered ability category instance on success, null on failure.
 163   */
 164  function wp_register_ability_category( string $slug, array $args ): ?WP_Ability_Category {
 165      if ( ! did_action( 'wp_abilities_api_categories_init' ) ) {
 166          _doing_it_wrong(
 167              __METHOD__,
 168              sprintf(
 169                  /* translators: 1: abilities_api_categories_init, 2: ability category slug. */
 170                  __( 'Ability categories must be registered on the %1$s action. The ability category %2$s was not registered.' ),
 171                  '<code>wp_abilities_api_categories_init</code>',
 172                  '<code>' . esc_html( $slug ) . '</code>'
 173              ),
 174              '6.9.0'
 175          );
 176          return null;
 177      }
 178  
 179      $registry = WP_Ability_Categories_Registry::get_instance();
 180      if ( null === $registry ) {
 181          return null;
 182      }
 183  
 184      return $registry->register( $slug, $args );
 185  }
 186  
 187  /**
 188   * Unregisters an ability category.
 189   *
 190   * @since 6.9.0
 191   *
 192   * @see WP_Ability_Categories_Registry::unregister()
 193   *
 194   * @param string $slug The slug of the registered ability category.
 195   * @return WP_Ability_Category|null The unregistered ability category instance on success, null on failure.
 196   */
 197  function wp_unregister_ability_category( string $slug ): ?WP_Ability_Category {
 198      $registry = WP_Ability_Categories_Registry::get_instance();
 199      if ( null === $registry ) {
 200          return null;
 201      }
 202  
 203      return $registry->unregister( $slug );
 204  }
 205  
 206  /**
 207   * Checks if an ability category is registered.
 208   *
 209   * @since 6.9.0
 210   *
 211   * @see WP_Ability_Categories_Registry::is_registered()
 212   *
 213   * @param string $slug The slug of the ability category.
 214   * @return bool True if the ability category is registered, false otherwise.
 215   */
 216  function wp_has_ability_category( string $slug ): bool {
 217      $registry = WP_Ability_Categories_Registry::get_instance();
 218      if ( null === $registry ) {
 219          return false;
 220      }
 221  
 222      return $registry->is_registered( $slug );
 223  }
 224  
 225  /**
 226   * Retrieves a registered ability category.
 227   *
 228   * @since 6.9.0
 229   *
 230   * @see WP_Ability_Categories_Registry::get_registered()
 231   *
 232   * @param string $slug The slug of the registered ability category.
 233   * @return WP_Ability_Category|null The registered ability category instance, or null if it is not registered.
 234   */
 235  function wp_get_ability_category( string $slug ): ?WP_Ability_Category {
 236      $registry = WP_Ability_Categories_Registry::get_instance();
 237      if ( null === $registry ) {
 238          return null;
 239      }
 240  
 241      return $registry->get_registered( $slug );
 242  }
 243  
 244  /**
 245   * Retrieves all registered ability categories.
 246   *
 247   * @since 6.9.0
 248   *
 249   * @see WP_Ability_Categories_Registry::get_all_registered()
 250   *
 251   * @return WP_Ability_Category[] The array of registered ability categories.
 252   */
 253  function wp_get_ability_categories(): array {
 254      $registry = WP_Ability_Categories_Registry::get_instance();
 255      if ( null === $registry ) {
 256          return array();
 257      }
 258  
 259      return $registry->get_all_registered();
 260  }