[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Style Engine: WP_Style_Engine_CSS_Declarations class
   4   *
   5   * @package WordPress
   6   * @subpackage StyleEngine
   7   * @since 6.1.0
   8   */
   9  
  10  /**
  11   * Core class used for style engine CSS declarations.
  12   *
  13   * Holds, sanitizes, processes, and prints CSS declarations for the style engine.
  14   *
  15   * @since 6.1.0
  16   */
  17  #[AllowDynamicProperties]
  18  class WP_Style_Engine_CSS_Declarations {
  19  
  20      /**
  21       * An array of CSS declarations (property => value pairs).
  22       *
  23       * @since 6.1.0
  24       *
  25       * @var string[]
  26       */
  27      protected $declarations = array();
  28  
  29      /**
  30       * CSS declaration options keyed by property name.
  31       *
  32       * @since 7.1.0
  33       *
  34       * @var array
  35       */
  36      protected $declaration_options = array();
  37  
  38      /**
  39       * Constructor for this object.
  40       *
  41       * If a `$declarations` array is passed, it will be used to populate
  42       * the initial `$declarations` prop of the object by calling add_declarations().
  43       *
  44       * @since 6.1.0
  45       *
  46       * @param string[] $declarations Optional. An associative array of CSS definitions,
  47       *                               e.g. `array( "$property" => "$value", "$property" => "$value" )`.
  48       *                               Default empty array.
  49       */
  50  	public function __construct( $declarations = array() ) {
  51          $this->add_declarations( $declarations );
  52      }
  53  
  54      /**
  55       * Adds a single declaration.
  56       *
  57       * @since 6.1.0
  58       * @since 7.1.0 Added the `$options` parameter.
  59       *
  60       * @param string $property The CSS property.
  61       * @param string $value    The CSS value.
  62       * @param array  $options  {
  63       *     Optional. An array of options. Default empty array.
  64       *
  65       *     @type bool $important Whether to output the declaration with !important. Default false.
  66       * }
  67       * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
  68       */
  69  	public function add_declaration( $property, $value, $options = array() ) {
  70          // Sanitizes the property.
  71          $property = $this->sanitize_property( $property );
  72          // Bails early if the property is empty.
  73          if ( empty( $property ) ) {
  74              return $this;
  75          }
  76  
  77          // Bail early if value is not a string. Prevents fatal errors from malformed block markup.
  78          if ( ! is_string( $value ) ) {
  79              return $this;
  80          }
  81  
  82          // Trims the value. If empty, bail early.
  83          $value = trim( $value );
  84          if ( '' === $value ) {
  85              return $this;
  86          }
  87  
  88          $options = wp_parse_args(
  89              $options,
  90              array(
  91                  'important' => false,
  92              )
  93          );
  94          $options = array_filter( $options );
  95  
  96          // Adds the declaration property/value pair.
  97          $this->declarations[ $property ] = $value;
  98          if ( $options ) {
  99              $this->declaration_options[ $property ] = $options;
 100          } else {
 101              unset( $this->declaration_options[ $property ] );
 102          }
 103  
 104          return $this;
 105      }
 106  
 107      /**
 108       * Removes a single declaration.
 109       *
 110       * @since 6.1.0
 111       *
 112       * @param string $property The CSS property.
 113       * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
 114       */
 115  	public function remove_declaration( $property ) {
 116          unset( $this->declarations[ $property ] );
 117          unset( $this->declaration_options[ $property ] );
 118          return $this;
 119      }
 120  
 121      /**
 122       * Adds multiple declarations.
 123       *
 124       * @since 6.1.0
 125       *
 126       * @param string[] $declarations An array of declarations.
 127       * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
 128       */
 129  	public function add_declarations( $declarations ) {
 130          foreach ( $declarations as $property => $value ) {
 131              $this->add_declaration( $property, $value );
 132          }
 133          return $this;
 134      }
 135  
 136      /**
 137       * Removes multiple declarations.
 138       *
 139       * @since 6.1.0
 140       *
 141       * @param string[] $properties Optional. An array of properties. Default empty array.
 142       * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
 143       */
 144  	public function remove_declarations( $properties = array() ) {
 145          foreach ( $properties as $property ) {
 146              $this->remove_declaration( $property );
 147          }
 148          return $this;
 149      }
 150  
 151      /**
 152       * Gets the declarations array.
 153       *
 154       * @since 6.1.0
 155       *
 156       * @return string[] The declarations array.
 157       */
 158  	public function get_declarations() {
 159          return $this->declarations;
 160      }
 161  
 162      /**
 163       * Gets declaration options keyed by property name.
 164       *
 165       * @since 7.1.0
 166       *
 167       * @return array Declaration options keyed by property name.
 168       */
 169  	public function get_declaration_options() {
 170          return $this->declaration_options;
 171      }
 172  
 173      /**
 174       * Filters a CSS property + value pair.
 175       *
 176       * @since 6.1.0
 177       * @since 7.1.0 Added the `$options` parameter.
 178       *
 179       * @param string $property The CSS property.
 180       * @param string $value    The value to be filtered.
 181       * @param string $spacer   Optional. The spacer between the colon and the value.
 182       *                         Default empty string.
 183       * @param array  $options  {
 184       *     Optional. An array of options. Default empty array.
 185       *
 186       *     @type bool $important Whether to output the declaration with !important. Default false.
 187       * }
 188       * @return string The filtered declaration or an empty string.
 189       */
 190  	protected static function filter_declaration( $property, $value, $spacer = '', $options = array() ) {
 191          $filtered_value = wp_strip_all_tags( $value, true );
 192          if ( '' !== $filtered_value ) {
 193              $options = wp_parse_args(
 194                  $options,
 195                  array(
 196                      'important' => false,
 197                  )
 198              );
 199  
 200              $filtered_declaration = safecss_filter_attr( "{$property}:{$spacer}{$filtered_value}" );
 201  
 202              // Only append !important in the presence of an option value and when sanitization returns a single declaration.
 203              if ( true === $options['important'] && '' !== $filtered_declaration && ! str_contains( $filtered_declaration, ';' ) ) {
 204                  return "$filtered_declaration !important";
 205              }
 206  
 207              return $filtered_declaration;
 208          }
 209          return '';
 210      }
 211  
 212      /**
 213       * Filters and compiles the CSS declarations.
 214       *
 215       * @since 6.1.0
 216       *
 217       * @param bool $should_prettify Optional. Whether to add spacing, new lines and indents.
 218       *                              Default false.
 219       * @param int  $indent_count    Optional. The number of tab indents to apply to the rule.
 220       *                              Applies if `prettify` is `true`. Default 0.
 221       * @return string The CSS declarations.
 222       */
 223  	public function get_declarations_string( $should_prettify = false, $indent_count = 0 ) {
 224          $declarations_array  = $this->get_declarations();
 225          $declarations_output = '';
 226          $indent              = $should_prettify ? str_repeat( "\t", $indent_count ) : '';
 227          $suffix              = $should_prettify ? ' ' : '';
 228          $suffix              = $should_prettify && $indent_count > 0 ? "\n" : $suffix;
 229          $spacer              = $should_prettify ? ' ' : '';
 230  
 231          foreach ( $declarations_array as $property => $value ) {
 232              $filtered_declaration = static::filter_declaration( $property, $value, $spacer, $this->declaration_options[ $property ] ?? array() );
 233              if ( $filtered_declaration ) {
 234                  $declarations_output .= "{$indent}{$filtered_declaration};$suffix";
 235              }
 236          }
 237  
 238          return rtrim( $declarations_output );
 239      }
 240  
 241      /**
 242       * Sanitizes property names.
 243       *
 244       * @since 6.1.0
 245       *
 246       * @param string $property The CSS property.
 247       * @return string The sanitized property name.
 248       */
 249  	protected function sanitize_property( $property ) {
 250          return sanitize_key( $property );
 251      }
 252  }