[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       */
  75  	public function __construct( string $slug, array $args ) {
  76          if ( empty( $slug ) ) {
  77              throw new InvalidArgumentException(
  78                  esc_html__( 'The ability category slug cannot be empty.' )
  79              );
  80          }
  81  
  82          $this->slug = $slug;
  83  
  84          $properties = $this->prepare_properties( $args );
  85  
  86          foreach ( $properties as $property_name => $property_value ) {
  87              if ( ! property_exists( $this, $property_name ) ) {
  88                  _doing_it_wrong(
  89                      __METHOD__,
  90                      sprintf(
  91                          /* translators: %s: Property name. */
  92                          __( 'Property "%1$s" is not a valid property for ability category "%2$s". Please check the %3$s class for allowed properties.' ),
  93                          '<code>' . esc_html( $property_name ) . '</code>',
  94                          '<code>' . esc_html( $this->slug ) . '</code>',
  95                          '<code>' . __CLASS__ . '</code>'
  96                      ),
  97                      '6.9.0'
  98                  );
  99                  continue;
 100              }
 101  
 102              $this->$property_name = $property_value;
 103          }
 104      }
 105  
 106      /**
 107       * Prepares and validates the properties used to instantiate the ability category.
 108       *
 109       * @since 6.9.0
 110       *
 111       * @param array<string, mixed> $args $args {
 112       *     An associative array of arguments used to instantiate the ability category class.
 113       *
 114       *     @type string               $label       The human-readable label for the ability category.
 115       *     @type string               $description A description of the ability category.
 116       *     @type array<string, mixed> $meta        Optional. Additional metadata for the ability category.
 117       * }
 118       * @return array<string, mixed> $args {
 119       *     An associative array with validated and prepared ability category properties.
 120       *
 121       *     @type string               $label       The human-readable label for the ability category.
 122       *     @type string               $description A description of the ability category.
 123       *     @type array<string, mixed> $meta        Optional. Additional metadata for the ability category.
 124       * }
 125       * @throws InvalidArgumentException if an argument is invalid.
 126       */
 127  	protected function prepare_properties( array $args ): array {
 128          // Required args must be present and of the correct type.
 129          if ( empty( $args['label'] ) || ! is_string( $args['label'] ) ) {
 130              throw new InvalidArgumentException(
 131                  __( 'The ability category properties must contain a `label` string.' )
 132              );
 133          }
 134  
 135          if ( empty( $args['description'] ) || ! is_string( $args['description'] ) ) {
 136              throw new InvalidArgumentException(
 137                  __( 'The ability category properties must contain a `description` string.' )
 138              );
 139          }
 140  
 141          // Optional args only need to be of the correct type if they are present.
 142          if ( isset( $args['meta'] ) && ! is_array( $args['meta'] ) ) {
 143              throw new InvalidArgumentException(
 144                  __( 'The ability category properties should provide a valid `meta` array.' )
 145              );
 146          }
 147  
 148          return $args;
 149      }
 150  
 151      /**
 152       * Retrieves the slug of the ability category.
 153       *
 154       * @since 6.9.0
 155       *
 156       * @return string The ability category slug.
 157       */
 158  	public function get_slug(): string {
 159          return $this->slug;
 160      }
 161  
 162      /**
 163       * Retrieves the human-readable label for the ability category.
 164       *
 165       * @since 6.9.0
 166       *
 167       * @return string The human-readable ability category label.
 168       */
 169  	public function get_label(): string {
 170          return $this->label;
 171      }
 172  
 173      /**
 174       * Retrieves the detailed description for the ability category.
 175       *
 176       * @since 6.9.0
 177       *
 178       * @return string The detailed description for the ability category.
 179       */
 180  	public function get_description(): string {
 181          return $this->description;
 182      }
 183  
 184      /**
 185       * Retrieves the metadata for the ability category.
 186       *
 187       * @since 6.9.0
 188       *
 189       * @return array<string,mixed> The metadata for the ability category.
 190       */
 191  	public function get_meta(): array {
 192          return $this->meta;
 193      }
 194  
 195      /**
 196       * Wakeup magic method.
 197       *
 198       * @since 6.9.0
 199       * @throws LogicException If the ability category object is unserialized.
 200       *                        This is a security hardening measure to prevent unserialization of the ability category.
 201       */
 202  	public function __wakeup(): void {
 203          throw new LogicException( __CLASS__ . ' should never be unserialized.' );
 204      }
 205  
 206      /**
 207       * Sleep magic method.
 208       *
 209       * @since 6.9.0
 210       * @throws LogicException If the ability category object is serialized.
 211       *                        This is a security hardening measure to prevent serialization of the ability category.
 212       */
 213  	public function __sleep(): array {
 214          throw new LogicException( __CLASS__ . ' should never be serialized' );
 215      }
 216  }