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