From a4151359d749f3a0e594caa85f891e1f0ec5542f Mon Sep 17 00:00:00 2001 From: Oliver Klee Date: Sun, 9 Feb 2025 14:20:55 +0100 Subject: [PATCH] [TASK] Make all non-private properties `@internal` This communicates clearly that the properties may be removed, renamed or made `private` at any point, and that they should not be accessed directly, but using the accessors instead. Also add a type annotation that was missing. Fixes #881 This is the V8.x backport of #886. --- CHANGELOG.md | 2 ++ src/CSSList/CSSList.php | 6 ++++ src/Comment/Comment.php | 4 +++ src/OutputFormat.php | 52 +++++++++++++++++++++++++++++++++++ src/Property/CSSNamespace.php | 2 ++ src/Property/Charset.php | 4 +++ src/Property/Import.php | 4 +++ src/Rule/Rule.php | 4 +++ src/RuleSet/RuleSet.php | 4 +++ src/Settings.php | 6 ++++ src/Value/CSSFunction.php | 2 ++ src/Value/Value.php | 2 ++ src/Value/ValueList.php | 4 +++ 13 files changed, 96 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6a32053c2..9eda84e0c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,8 @@ This project adheres to [Semantic Versioning](https://semver.org/). ### Changed +- Make all non-private properties `@internal` (#886) + ### Deprecated - `OutputFormat` properties for space around list separators as an array (#880) diff --git a/src/CSSList/CSSList.php b/src/CSSList/CSSList.php index 4bb375891..d0a8bbbce 100644 --- a/src/CSSList/CSSList.php +++ b/src/CSSList/CSSList.php @@ -33,16 +33,22 @@ abstract class CSSList implements Renderable, Commentable { /** * @var array + * + * @internal since 8.8.0 */ protected $aComments; /** * @var array + * + * @internal since 8.8.0 */ protected $aContents; /** * @var int + * + * @internal since 8.8.0 */ protected $iLineNo; diff --git a/src/Comment/Comment.php b/src/Comment/Comment.php index e6ffaaf73..8c02f3de1 100644 --- a/src/Comment/Comment.php +++ b/src/Comment/Comment.php @@ -9,11 +9,15 @@ class Comment implements Renderable { /** * @var int + * + * @internal since 8.8.0 */ protected $iLineNo; /** * @var string + * + * @internal since 8.8.0 */ protected $sComment; diff --git a/src/OutputFormat.php b/src/OutputFormat.php index 366fca3ff..2101c31f1 100644 --- a/src/OutputFormat.php +++ b/src/OutputFormat.php @@ -14,6 +14,8 @@ class OutputFormat * Value format: `"` means double-quote, `'` means single-quote * * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sStringQuotingType = '"'; @@ -21,6 +23,8 @@ class OutputFormat * Output RGB colors in hash notation if possible * * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $bRGBHashNotation = true; @@ -30,6 +34,8 @@ class OutputFormat * Semicolon after the last rule of a declaration block can be omitted. To do that, set this false. * * @var bool + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $bSemicolonAfterLastRule = true; @@ -38,36 +44,52 @@ class OutputFormat * Note that these strings are not sanity-checked: the value should only consist of whitespace * Any newline character will be indented according to the current level. * The triples (After, Before, Between) can be set using a wildcard (e.g. `$oFormat->set('Space*Rules', "\n");`) + * + * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sSpaceAfterRuleName = ' '; /** * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sSpaceBeforeRules = ''; /** * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sSpaceAfterRules = ''; /** * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sSpaceBetweenRules = ''; /** * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sSpaceBeforeBlocks = ''; /** * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sSpaceAfterBlocks = ''; /** * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sSpaceBetweenBlocks = "\n"; @@ -75,11 +97,15 @@ class OutputFormat * Content injected in and around at-rule blocks. * * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sBeforeAtRuleBlock = ''; /** * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sAfterAtRuleBlock = ''; @@ -87,11 +113,15 @@ class OutputFormat * This is what’s printed before and after the comma if a declaration block contains multiple selectors. * * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sSpaceBeforeSelectorSeparator = ''; /** * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sSpaceAfterSelectorSeparator = ' '; @@ -102,6 +132,8 @@ class OutputFormat * To set the spacing for specific separators, use {@see $aSpaceBeforeListArgumentSeparators} instead. * * @var string|array + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sSpaceBeforeListArgumentSeparator = ''; @@ -109,6 +141,8 @@ class OutputFormat * Keys are separators (e.g. `,`). Values are the space sequence to insert, or an empty string. * * @var array + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $aSpaceBeforeListArgumentSeparators = []; @@ -119,6 +153,8 @@ class OutputFormat * To set the spacing for specific separators, use {@see $aSpaceAfterListArgumentSeparators} instead. * * @var string|array + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sSpaceAfterListArgumentSeparator = ''; @@ -126,11 +162,15 @@ class OutputFormat * Keys are separators (e.g. `,`). Values are the space sequence to insert, or an empty string. * * @var array + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $aSpaceAfterListArgumentSeparators = []; /** * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sSpaceBeforeOpeningBrace = ' '; @@ -138,16 +178,22 @@ class OutputFormat * Content injected in and around declaration blocks. * * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sBeforeDeclarationBlock = ''; /** * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sAfterDeclarationBlockSelectors = ''; /** * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sAfterDeclarationBlock = ''; @@ -155,6 +201,8 @@ class OutputFormat * Indentation character(s) per level. Only applicable if newlines are used in any of the spacing settings. * * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sIndentation = "\t"; @@ -162,6 +210,8 @@ class OutputFormat * Output exceptions. * * @var bool + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $bIgnoreExceptions = false; @@ -169,6 +219,8 @@ class OutputFormat * Render comments for lists and RuleSets * * @var bool + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $bRenderComments = false; diff --git a/src/Property/CSSNamespace.php b/src/Property/CSSNamespace.php index d1bac4f71..f39c28778 100644 --- a/src/Property/CSSNamespace.php +++ b/src/Property/CSSNamespace.php @@ -27,6 +27,8 @@ class CSSNamespace implements AtRule /** * @var array + * + * @internal since 8.8.0 */ protected $aComments; diff --git a/src/Property/Charset.php b/src/Property/Charset.php index 870380e34..5e25bd4ea 100644 --- a/src/Property/Charset.php +++ b/src/Property/Charset.php @@ -23,11 +23,15 @@ class Charset implements AtRule /** * @var int + * + * @internal since 8.8.0 */ protected $iLineNo; /** * @var array + * + * @internal since 8.8.0 */ protected $aComments; diff --git a/src/Property/Import.php b/src/Property/Import.php index 2a7cad54c..9b40e3043 100644 --- a/src/Property/Import.php +++ b/src/Property/Import.php @@ -23,11 +23,15 @@ class Import implements AtRule /** * @var int + * + * @internal since 8.8.0 */ protected $iLineNo; /** * @var array + * + * @internal since 8.8.0 */ protected $aComments; diff --git a/src/Rule/Rule.php b/src/Rule/Rule.php index f10dbe660..ae3c595fa 100644 --- a/src/Rule/Rule.php +++ b/src/Rule/Rule.php @@ -46,11 +46,15 @@ class Rule implements Renderable, Commentable /** * @var int + * + * @internal since 8.8.0 */ protected $iColNo; /** * @var array + * + * @internal since 8.8.0 */ protected $aComments; diff --git a/src/RuleSet/RuleSet.php b/src/RuleSet/RuleSet.php index 8cbbd34f8..e90694aed 100644 --- a/src/RuleSet/RuleSet.php +++ b/src/RuleSet/RuleSet.php @@ -29,11 +29,15 @@ abstract class RuleSet implements Renderable, Commentable /** * @var int + * + * @internal since 8.8.0 */ protected $iLineNo; /** * @var array + * + * @internal since 8.8.0 */ protected $aComments; diff --git a/src/Settings.php b/src/Settings.php index 79d99803c..8d4bd4686 100644 --- a/src/Settings.php +++ b/src/Settings.php @@ -16,6 +16,8 @@ class Settings * and `mb_strpos` functions. Otherwise, the normal (ASCII-Only) functions will be used. * * @var bool + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $bMultibyteSupport; @@ -23,6 +25,8 @@ class Settings * The default charset for the CSS if no `@charset` declaration is found. Defaults to utf-8. * * @var string + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $sDefaultCharset = 'utf-8'; @@ -30,6 +34,8 @@ class Settings * Whether the parser silently ignore invalid rules instead of choking on them. * * @var bool + * + * @internal since 8.8.0, will be made private in 9.0.0 */ public $bLenientParsing = true; diff --git a/src/Value/CSSFunction.php b/src/Value/CSSFunction.php index 82ffc48c8..14992aa8d 100644 --- a/src/Value/CSSFunction.php +++ b/src/Value/CSSFunction.php @@ -13,6 +13,8 @@ class CSSFunction extends ValueList { /** * @var string + * + * @internal since 8.8.0 */ protected $sName; diff --git a/src/Value/Value.php b/src/Value/Value.php index 4b174db0b..6232d126e 100644 --- a/src/Value/Value.php +++ b/src/Value/Value.php @@ -16,6 +16,8 @@ abstract class Value implements Renderable { /** * @var int + * + * @internal since 8.8.0 */ protected $iLineNo; diff --git a/src/Value/ValueList.php b/src/Value/ValueList.php index 80b26f97f..9ae3da99c 100644 --- a/src/Value/ValueList.php +++ b/src/Value/ValueList.php @@ -14,11 +14,15 @@ abstract class ValueList extends Value { /** * @var array + * + * @internal since 8.8.0 */ protected $aComponents; /** * @var string + * + * @internal since 8.8.0 */ protected $sSeparator;