[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Abilities API
   4   *
   5   * Defines WP_Ability_Category class.
   6   *
   7   * @package WordPress
   8   * @subpackage Abilities API
   9   * @since 6.9.0
  10   */
  11  
  12  declare( strict_types = 1 );
  13  
  14  /**
  15   * Encapsulates the properties and methods related to a specific ability category.
  16   *
  17   * @since 6.9.0
  18   *
  19   * @see WP_Ability_Categories_Registry
  20   */
  21  final class WP_Ability_Category {
  22  
  23      /**
  24       * The unique slug for the ability category.
  25       *
  26       * @since 6.9.0
  27       * @var string
  28       */
  29      protected $slug;
  30  
  31      /**
  32       * The human-readable ability category label.
  33       *
  34       * @since 6.9.0
  35       * @var string
  36       */
  37      protected $label;
  38  
  39      /**
  40       * The detailed ability category description.
  41       *
  42       * @since 6.9.0
  43       * @var string
  44       */
  45      protected $description;
  46  
  47      /**
  48       * The optional ability category metadata.
  49       *
  50       * @since 6.9.0
  51       * @var array<string, mixed>
  52       */
  53      protected $meta = array();
  54  
  55      /**
  56       * Constructor.
  57       *
  58       * Do not use this constructor directly. Instead, use the `wp_register_ability_category()` function.
  59       *
  60       * @access private
  61       *
  62       * @since 6.9.0
  63       *
  64       * @see wp_register_ability_category()
  65       *
  66       * @param string               $slug The unique slug for the ability category.
  67       * @param array<string, mixed> $args {
  68       *     An associative array of arguments for the ability category.
  69       *
  70       *     @type string               $label       The human-readable label for the ability category.
  71       *     @type string               $description A description of the ability category.
  72       *     @type array<string, mixed> $meta        Optional. Additional metadata for the ability category.
  73       * }
  74       * @throws InvalidArgumentException If an argument is invalid.
  75       */
  76  	public function __construct( string $slug, array $args ) {
  77          if ( empty( $slug ) ) {
  78              throw new InvalidArgumentException(
  79                  __( 'The ability category slug cannot be empty.' )
  80              );
  81          }
  82  
  83          $this->slug = $slug;
  84  
  85          $properties = $this->prepare_properties( $args );
  86  
  87          foreach ( $properties as $property_name => $property_value ) {
  88              if ( ! property_exists( $this, $property_name ) ) {
  89                  _doing_it_wrong(
  90                      __METHOD__,
  91                      sprintf(
  92                          /* translators: %s: Property name. */
  93                          __( 'Property "%1$s" is not a valid property for ability category "%2$s". Please check the %3$s class for allowed properties.' ),
  94                          '<code>' . esc_html( $property_name ) . '</code>',
  95                          '<code>' . esc_html( $this->slug ) . '</code>',
  96                          '<code>' . __CLASS__ . '</code>'
  97                      ),
  98                      '6.9.0'
  99                  );
 100                  continue;
 101              }
 102  
 103              $this->$property_name = $property_value;
 104          }
 105      }
 106  
 107      /**
 108       * Prepares and validates the properties used to instantiate the ability category.
 109       *
 110       * @since 6.9.0
 111       *
 112       * @param array<string, mixed> $args {
 113       *     An associative array of arguments used to instantiate the ability category class.
 114       *
 115       *     @type string               $label       The human-readable label for the ability category.
 116       *     @type string               $description A description of the ability category.
 117       *     @type array<string, mixed> $meta        Optional. Additional metadata for the ability category.
 118       * }
 119       * @return array<string, mixed> $args {
 120       *     An associative array with validated and prepared ability category properties.
 121       *
 122       *     @type string               $label       The human-readable label for the ability category.
 123       *     @type string               $description A description of the ability category.
 124       *     @type array<string, mixed> $meta        Optional. Additional metadata for the ability category.
 125       * }
 126       * @throws InvalidArgumentException If an argument is invalid.
 127       */
 128  	protected function prepare_properties( array $args ): array {
 129          // Required args must be present and of the correct type.
 130          if ( empty( $args['label'] ) || ! is_string( $args['label'] ) ) {
 131              throw new InvalidArgumentException(
 132                  __( 'The ability category properties must contain a `label` string.' )
 133              );
 134          }
 135  
 136          if ( empty( $args['description'] ) || ! is_string( $args['description'] ) ) {
 137              throw new InvalidArgumentException(
 138                  __( 'The ability category properties must contain a `description` string.' )
 139              );
 140          }
 141  
 142          // Optional args only need to be of the correct type if they are present.
 143          if ( isset( $args['meta'] ) && ! is_array( $args['meta'] ) ) {
 144              throw new InvalidArgumentException(
 145                  __( 'The ability category properties should provide a valid `meta` array.' )
 146              );
 147          }
 148  
 149          return $args;
 150      }
 151  
 152      /**
 153       * Retrieves the slug of the ability category.
 154       *
 155       * @since 6.9.0
 156       *
 157       * @return string The ability category slug.
 158       */
 159  	public function get_slug(): string {
 160          return $this->slug;
 161      }
 162  
 163      /**
 164       * Retrieves the human-readable label for the ability category.
 165       *
 166       * @since 6.9.0
 167       *
 168       * @return string The human-readable ability category label.
 169       */
 170  	public function get_label(): string {
 171          return $this->label;
 172      }
 173  
 174      /**
 175       * Retrieves the detailed description for the ability category.
 176       *
 177       * @since 6.9.0
 178       *
 179       * @return string The detailed description for the ability category.
 180       */
 181  	public function get_description(): string {
 182          return $this->description;
 183      }
 184  
 185      /**
 186       * Retrieves the metadata for the ability category.
 187       *
 188       * @since 6.9.0
 189       *
 190       * @return array<string,mixed> The metadata for the ability category.
 191       */
 192  	public function get_meta(): array {
 193          return $this->meta;
 194      }
 195  
 196      /**
 197       * Wakeup magic method.
 198       *
 199       * @since 6.9.0
 200       * @throws LogicException If the ability category object is unserialized.
 201       *                        This is a security hardening measure to prevent unserialization of the ability category.
 202       */
 203  	public function __wakeup(): void {
 204          throw new LogicException( __CLASS__ . ' should never be unserialized.' );
 205      }
 206  
 207      /**
 208       * Sleep magic method.
 209       *
 210       * @since 6.9.0
 211       * @throws LogicException If the ability category object is serialized.
 212       *                        This is a security hardening measure to prevent serialization of the ability category.
 213       */
 214  	public function __sleep(): array {
 215          throw new LogicException( __CLASS__ . ' should never be serialized.' );
 216      }
 217  }