[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Abilities API
   4   *
   5   * Defines WP_Ability_Categories_Registry class.
   6   *
   7   * @package WordPress
   8   * @subpackage Abilities API
   9   * @since 6.9.0
  10   */
  11  
  12  declare( strict_types = 1 );
  13  
  14  /**
  15   * Manages the registration and lookup of ability categories.
  16   *
  17   * @since 6.9.0
  18   * @access private
  19   */
  20  final class WP_Ability_Categories_Registry {
  21      /**
  22       * The singleton instance of the registry.
  23       *
  24       * @since 6.9.0
  25       * @var self|null
  26       */
  27      private static $instance = null;
  28  
  29      /**
  30       * Holds the registered ability categories.
  31       *
  32       * @since 6.9.0
  33       * @var WP_Ability_Category[]
  34       */
  35      private $registered_categories = array();
  36  
  37      /**
  38       * Registers a new ability category.
  39       *
  40       * Do not use this method directly. Instead, use the `wp_register_ability_category()` function.
  41       *
  42       * @since 6.9.0
  43       *
  44       * @see wp_register_ability_category()
  45       *
  46       * @param string               $slug The unique slug for the ability category. Must contain only lowercase
  47       *                                   alphanumeric characters and dashes.
  48       * @param array<string, mixed> $args {
  49       *     An associative array of arguments for the ability category.
  50       *
  51       *     @type string               $label       The human-readable label for the ability category.
  52       *     @type string               $description A description of the ability category.
  53       *     @type array<string, mixed> $meta        Optional. Additional metadata for the ability category.
  54       * }
  55       * @return WP_Ability_Category|null The registered ability category instance on success, null on failure.
  56       */
  57  	public function register( string $slug, array $args ): ?WP_Ability_Category {
  58          if ( $this->is_registered( $slug ) ) {
  59              _doing_it_wrong(
  60                  __METHOD__,
  61                  /* translators: %s: Ability category slug. */
  62                  sprintf( __( 'Ability category "%s" is already registered.' ), esc_html( $slug ) ),
  63                  '6.9.0'
  64              );
  65              return null;
  66          }
  67  
  68          if ( ! preg_match( '/^[a-z0-9]+(?:-[a-z0-9]+)*$/', $slug ) ) {
  69              _doing_it_wrong(
  70                  __METHOD__,
  71                  __( 'Ability category slug must contain only lowercase alphanumeric characters and dashes.' ),
  72                  '6.9.0'
  73              );
  74              return null;
  75          }
  76  
  77          /**
  78           * Filters the ability category arguments before they are validated and used to instantiate the ability category.
  79           *
  80           * @since 6.9.0
  81           *
  82           * @param array<string, mixed> $args {
  83           *     The arguments used to instantiate the ability category.
  84           *
  85           *     @type string               $label       The human-readable label for the ability category.
  86           *     @type string               $description A description of the ability category.
  87           *     @type array<string, mixed> $meta        Optional. Additional metadata for the ability category.
  88           * }
  89           * @param string               $slug The slug of the ability category.
  90           */
  91          $args = apply_filters( 'wp_register_ability_category_args', $args, $slug );
  92  
  93          try {
  94              // WP_Ability_Category::prepare_properties() will throw an exception if the properties are invalid.
  95              $category = new WP_Ability_Category( $slug, $args );
  96          } catch ( InvalidArgumentException $e ) {
  97              _doing_it_wrong(
  98                  __METHOD__,
  99                  $e->getMessage(),
 100                  '6.9.0'
 101              );
 102              return null;
 103          }
 104  
 105          $this->registered_categories[ $slug ] = $category;
 106          return $category;
 107      }
 108  
 109      /**
 110       * Unregisters an ability category.
 111       *
 112       * Do not use this method directly. Instead, use the `wp_unregister_ability_category()` function.
 113       *
 114       * @since 6.9.0
 115       *
 116       * @see wp_unregister_ability_category()
 117       *
 118       * @param string $slug The slug of the registered ability category.
 119       * @return WP_Ability_Category|null The unregistered ability category instance on success, null on failure.
 120       */
 121  	public function unregister( string $slug ): ?WP_Ability_Category {
 122          if ( ! $this->is_registered( $slug ) ) {
 123              _doing_it_wrong(
 124                  __METHOD__,
 125                  /* translators: %s: Ability category slug. */
 126                  sprintf( __( 'Ability category "%s" not found.' ), esc_html( $slug ) ),
 127                  '6.9.0'
 128              );
 129              return null;
 130          }
 131  
 132          $unregistered_category = $this->registered_categories[ $slug ];
 133          unset( $this->registered_categories[ $slug ] );
 134  
 135          return $unregistered_category;
 136      }
 137  
 138      /**
 139       * Retrieves the list of all registered ability categories.
 140       *
 141       * Do not use this method directly. Instead, use the `wp_get_ability_categories()` function.
 142       *
 143       * @since 6.9.0
 144       *
 145       * @see wp_get_ability_categories()
 146       *
 147       * @return array<string, WP_Ability_Category> The array of registered ability categories.
 148       */
 149  	public function get_all_registered(): array {
 150          return $this->registered_categories;
 151      }
 152  
 153      /**
 154       * Checks if an ability category is registered.
 155       *
 156       * Do not use this method directly. Instead, use the `wp_has_ability_category()` function.
 157       *
 158       * @since 6.9.0
 159       *
 160       * @see wp_has_ability_category()
 161       *
 162       * @param string $slug The slug of the ability category.
 163       * @return bool True if the ability category is registered, false otherwise.
 164       */
 165  	public function is_registered( string $slug ): bool {
 166          return isset( $this->registered_categories[ $slug ] );
 167      }
 168  
 169      /**
 170       * Retrieves a registered ability category.
 171       *
 172       * Do not use this method directly. Instead, use the `wp_get_ability_category()` function.
 173       *
 174       * @since 6.9.0
 175       *
 176       * @see wp_get_ability_category()
 177       *
 178       * @param string $slug The slug of the registered ability category.
 179       * @return WP_Ability_Category|null The registered ability category instance, or null if it is not registered.
 180       */
 181  	public function get_registered( string $slug ): ?WP_Ability_Category {
 182          if ( ! $this->is_registered( $slug ) ) {
 183              _doing_it_wrong(
 184                  __METHOD__,
 185                  /* translators: %s: Ability category slug. */
 186                  sprintf( __( 'Ability category "%s" not found.' ), esc_html( $slug ) ),
 187                  '6.9.0'
 188              );
 189              return null;
 190          }
 191          return $this->registered_categories[ $slug ];
 192      }
 193  
 194      /**
 195       * Utility method to retrieve the main instance of the registry class.
 196       *
 197       * The instance will be created if it does not exist yet.
 198       *
 199       * @since 6.9.0
 200       *
 201       * @return WP_Ability_Categories_Registry|null The main registry instance, or null when `init` action has not fired.
 202       */
 203  	public static function get_instance(): ?self {
 204          if ( ! did_action( 'init' ) ) {
 205              _doing_it_wrong(
 206                  __METHOD__,
 207                  sprintf(
 208                      __( 'Ability API should not be initialized before the <code>init</code> action has fired' )
 209                  ),
 210                  '6.9.0'
 211              );
 212              return null;
 213          }
 214  
 215          if ( null === self::$instance ) {
 216              self::$instance = new self();
 217  
 218              /**
 219               * Fires when preparing ability categories registry.
 220               *
 221               * Ability categories should be registered on this action to ensure they're available when needed.
 222               *
 223               * @since 6.9.0
 224               *
 225               * @param WP_Ability_Categories_Registry $instance Ability categories registry object.
 226               */
 227              do_action( 'wp_abilities_api_categories_init', self::$instance );
 228          }
 229  
 230          return self::$instance;
 231      }
 232  
 233      /**
 234       * Wakeup magic method.
 235       *
 236       * @since 6.9.0
 237       * @throws LogicException If the registry object is unserialized.
 238       *                        This is a security hardening measure to prevent unserialization of the registry.
 239       */
 240  	public function __wakeup(): void {
 241          throw new LogicException( __CLASS__ . ' should never be unserialized.' );
 242      }
 243  
 244      /**
 245       * Sleep magic method.
 246       *
 247       * @since 6.9.0
 248       * @throws LogicException If the registry object is serialized.
 249       *                        This is a security hardening measure to prevent serialization of the registry.
 250       */
 251  	public function __sleep(): array {
 252          throw new LogicException( __CLASS__ . ' should never be serialized' );
 253      }
 254  }