WordPress/wp-includes/style-engine/class-wp-style-engine-css-d...

182 lines
4.8 KiB
PHP
Raw Normal View History

<?php
/**
* Style Engine: WP_Style_Engine_CSS_Declarations class
*
* @package WordPress
* @subpackage StyleEngine
* @since 6.1.0
*/
/**
* Core class used for style engine CSS declarations.
*
* Holds, sanitizes, processes, and prints CSS declarations for the style engine.
*
* @since 6.1.0
*/
Code Modernization: Add `AllowDynamicProperties` attribute to recently introduced classes. This commit is a follow-up to [54133] for new classes introduced in WordPress 6.1 since the previous commit. Dynamic (non-explicitly declared) properties are deprecated as of PHP 8.2 and are expected to become a fatal error in PHP 9.0. There are a number of ways to mitigate this: * If it is an accidental typo for a declared property: fix the typo. * For known properties: declare them on the class. * For unknown properties: add the magic `__get()`, `__set()`, et al. methods to the class or let the class extend `stdClass` which has highly optimized versions of these magic methods built in. * For unknown ''use'' of dynamic properties, the `#[AllowDynamicProperties]` attribute can be added to the class. The attribute will automatically be inherited by child classes. Trac ticket #56034 is open to investigate and handle the third and fourth type of situations, however it has become clear this will need more time and will not be ready in time for WP 6.1. To reduce “noise” in the meantime, both in the error logs of WP users moving onto PHP 8.2, in the test run logs of WP itself, in test runs of plugins and themes, as well as to prevent duplicate tickets from being opened for the same issue, the `#[AllowDynamicProperties]` attribute has been added to all “parent” classes in WP. Reference: [https://wiki.php.net/rfc/deprecate_dynamic_properties PHP RFC: Deprecate dynamic properties]. Follow-up to [53922], [54133]. Props jrf. See #56513, #56034. Built from https://develop.svn.wordpress.org/trunk@54481 git-svn-id: http://core.svn.wordpress.org/trunk@54040 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2022-10-11 11:00:12 -04:00
#[AllowDynamicProperties]
class WP_Style_Engine_CSS_Declarations {
/**
* An array of CSS declarations (property => value pairs).
*
* @since 6.1.0
*
* @var string[]
*/
protected $declarations = array();
/**
* Constructor for this object.
*
* If a `$declarations` array is passed, it will be used to populate
* the initial $declarations prop of the object by calling add_declarations().
*
* @since 6.1.0
*
* @param string[] $declarations An associative array of CSS definitions, e.g., `array( "$property" => "$value", "$property" => "$value" )`.
*/
public function __construct( $declarations = array() ) {
$this->add_declarations( $declarations );
}
/**
* Adds a single declaration.
*
* @since 6.1.0
*
* @param string $property The CSS property.
* @param string $value The CSS value.
* @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
*/
public function add_declaration( $property, $value ) {
// Sanitizes the property.
$property = $this->sanitize_property( $property );
// Bails early if the property is empty.
if ( empty( $property ) ) {
return $this;
}
// Trims the value. If empty, bail early.
$value = trim( $value );
if ( '' === $value ) {
return $this;
}
// Adds the declaration property/value pair.
$this->declarations[ $property ] = $value;
return $this;
}
/**
* Removes a single declaration.
*
* @since 6.1.0
*
* @param string $property The CSS property.
* @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
*/
public function remove_declaration( $property ) {
unset( $this->declarations[ $property ] );
return $this;
}
/**
* Adds multiple declarations.
*
* @since 6.1.0
*
* @param string[] $declarations An array of declarations.
* @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
*/
public function add_declarations( $declarations ) {
foreach ( $declarations as $property => $value ) {
$this->add_declaration( $property, $value );
}
return $this;
}
/**
* Removes multiple declarations.
*
* @since 6.1.0
*
* @param string[] $properties An array of properties.
* @return WP_Style_Engine_CSS_Declarations Returns the object to allow chaining methods.
*/
public function remove_declarations( $properties = array() ) {
foreach ( $properties as $property ) {
$this->remove_declaration( $property );
}
return $this;
}
/**
* Gets the declarations array.
*
* @since 6.1.0
*
* @return string[] The declarations array.
*/
public function get_declarations() {
return $this->declarations;
}
/**
* Filters a CSS property + value pair.
*
* @since 6.1.0
*
* @param string $property The CSS property.
* @param string $value The value to be filtered.
* @param string $spacer The spacer between the colon and the value. Defaults to an empty string.
* @return string The filtered declaration or an empty string.
*/
protected static function filter_declaration( $property, $value, $spacer = '' ) {
$filtered_value = wp_strip_all_tags( $value, true );
if ( '' !== $filtered_value ) {
return safecss_filter_attr( "{$property}:{$spacer}{$filtered_value}" );
}
return '';
}
/**
* Filters and compiles the CSS declarations.
*
* @since 6.1.0
*
* @param bool $should_prettify Whether to add spacing, new lines and indents.
* @param int $indent_count The number of tab indents to apply to the rule. Applies if `prettify` is `true`.
* @return string The CSS declarations.
*/
public function get_declarations_string( $should_prettify = false, $indent_count = 0 ) {
$declarations_array = $this->get_declarations();
$declarations_output = '';
$indent = $should_prettify ? str_repeat( "\t", $indent_count ) : '';
$suffix = $should_prettify ? ' ' : '';
$suffix = $should_prettify && $indent_count > 0 ? "\n" : $suffix;
$spacer = $should_prettify ? ' ' : '';
foreach ( $declarations_array as $property => $value ) {
$filtered_declaration = static::filter_declaration( $property, $value, $spacer );
if ( $filtered_declaration ) {
$declarations_output .= "{$indent}{$filtered_declaration};$suffix";
}
}
return rtrim( $declarations_output );
}
/**
* Sanitizes property names.
*
* @since 6.1.0
*
* @param string $property The CSS property.
* @return string The sanitized property name.
*/
protected function sanitize_property( $property ) {
return sanitize_key( $property );
}
}