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