[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       * Constructor for this object.
  31       *
  32       * If a `$declarations` array is passed, it will be used to populate
  33       * the initial `$declarations` prop of the object by calling add_declarations().
  34       *
  35       * @since 6.1.0
  36       *
  37       * @param string[] $declarations Optional. An associative array of CSS definitions,
  38       *                               e.g. `array( "$property" => "$value", "$property" => "$value" )`.
  39       *                               Default empty array.
  40       */
  41  	public function __construct( $declarations = array() ) {
  42          $this->add_declarations( $declarations );
  43      }
  44  
  45      /**
  46       * Adds a single declaration.
  47       *
  48       * @since 6.1.0
  49       *
  50       * @param string $property The CSS property.
  51       * @param string $value    The CSS value.
  52       * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
  53       */
  54  	public function add_declaration( $property, $value ) {
  55          // Sanitizes the property.
  56          $property = $this->sanitize_property( $property );
  57          // Bails early if the property is empty.
  58          if ( empty( $property ) ) {
  59              return $this;
  60          }
  61  
  62          // Bail early if value is not a string. Prevents fatal errors from malformed block markup.
  63          if ( ! is_string( $value ) ) {
  64              return $this;
  65          }
  66  
  67          // Trims the value. If empty, bail early.
  68          $value = trim( $value );
  69          if ( '' === $value ) {
  70              return $this;
  71          }
  72  
  73          // Adds the declaration property/value pair.
  74          $this->declarations[ $property ] = $value;
  75  
  76          return $this;
  77      }
  78  
  79      /**
  80       * Removes a single declaration.
  81       *
  82       * @since 6.1.0
  83       *
  84       * @param string $property The CSS property.
  85       * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
  86       */
  87  	public function remove_declaration( $property ) {
  88          unset( $this->declarations[ $property ] );
  89          return $this;
  90      }
  91  
  92      /**
  93       * Adds multiple declarations.
  94       *
  95       * @since 6.1.0
  96       *
  97       * @param string[] $declarations An array of declarations.
  98       * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
  99       */
 100  	public function add_declarations( $declarations ) {
 101          foreach ( $declarations as $property => $value ) {
 102              $this->add_declaration( $property, $value );
 103          }
 104          return $this;
 105      }
 106  
 107      /**
 108       * Removes multiple declarations.
 109       *
 110       * @since 6.1.0
 111       *
 112       * @param string[] $properties Optional. An array of properties. Default empty array.
 113       * @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
 114       */
 115  	public function remove_declarations( $properties = array() ) {
 116          foreach ( $properties as $property ) {
 117              $this->remove_declaration( $property );
 118          }
 119          return $this;
 120      }
 121  
 122      /**
 123       * Gets the declarations array.
 124       *
 125       * @since 6.1.0
 126       *
 127       * @return string[] The declarations array.
 128       */
 129  	public function get_declarations() {
 130          return $this->declarations;
 131      }
 132  
 133      /**
 134       * Filters a CSS property + value pair.
 135       *
 136       * @since 6.1.0
 137       *
 138       * @param string $property The CSS property.
 139       * @param string $value    The value to be filtered.
 140       * @param string $spacer   Optional. The spacer between the colon and the value.
 141       *                         Default empty string.
 142       * @return string The filtered declaration or an empty string.
 143       */
 144  	protected static function filter_declaration( $property, $value, $spacer = '' ) {
 145          $filtered_value = wp_strip_all_tags( $value, true );
 146          if ( '' !== $filtered_value ) {
 147              return safecss_filter_attr( "{$property}:{$spacer}{$filtered_value}" );
 148          }
 149          return '';
 150      }
 151  
 152      /**
 153       * Filters and compiles the CSS declarations.
 154       *
 155       * @since 6.1.0
 156       *
 157       * @param bool $should_prettify Optional. Whether to add spacing, new lines and indents.
 158       *                              Default false.
 159       * @param int  $indent_count    Optional. The number of tab indents to apply to the rule.
 160       *                              Applies if `prettify` is `true`. Default 0.
 161       * @return string The CSS declarations.
 162       */
 163  	public function get_declarations_string( $should_prettify = false, $indent_count = 0 ) {
 164          $declarations_array  = $this->get_declarations();
 165          $declarations_output = '';
 166          $indent              = $should_prettify ? str_repeat( "\t", $indent_count ) : '';
 167          $suffix              = $should_prettify ? ' ' : '';
 168          $suffix              = $should_prettify && $indent_count > 0 ? "\n" : $suffix;
 169          $spacer              = $should_prettify ? ' ' : '';
 170  
 171          foreach ( $declarations_array as $property => $value ) {
 172              $filtered_declaration = static::filter_declaration( $property, $value, $spacer );
 173              if ( $filtered_declaration ) {
 174                  $declarations_output .= "{$indent}{$filtered_declaration};$suffix";
 175              }
 176          }
 177  
 178          return rtrim( $declarations_output );
 179      }
 180  
 181      /**
 182       * Sanitizes property names.
 183       *
 184       * @since 6.1.0
 185       *
 186       * @param string $property The CSS property.
 187       * @return string The sanitized property name.
 188       */
 189  	protected function sanitize_property( $property ) {
 190          return sanitize_key( $property );
 191      }
 192  }