You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* 'master' of https://github.com/sabberworm/PHP-CSS-Parser: (57 commits)
Update PHP-CS-Fixer and PHPStan
Update README.md
Update PHP-CS-Fixer and PHPStan
Update PHP-CS-Fixer and PHPStan
Update PHP-CS-Fixer and PHPStan
Run the tests on CI with all warnings enabled
Show the Composer configuration in the CI jobs
Add PHPDoc
Fixes for CI
Add missing code after catchup merge
Fix unit tests
Code refactor for CI
Streamline parsing functions
Re-implement ParserState anchors with dedicated Anchor class
Add back code that got dropped while resolving conflicts
Fix indents
Use PHPUnit 5.x features in the tests
Add unit tests for interface implementation in `CSSList` classes
Add more detailed unit tests for `Comment`
Sync the code documentation from the README to the source files
...
Copy file name to clipboardExpand all lines: README.md
+24-19Lines changed: 24 additions & 19 deletions
Original file line number
Diff line number
Diff line change
@@ -33,7 +33,7 @@ The resulting CSS document structure can be manipulated prior to being output.
33
33
34
34
#### Charset
35
35
36
-
The charset option is used only if no `@charset` declaration is found in the CSS file. UTF-8 is the default, so you won’t have to create a settings object at all if you don’t intend to change that.
36
+
The charset option will only be used if the CSS file does not contain an `@charset` declaration. UTF-8 is the default, so you won’t have to create a settings object at all if you don’t intend to change that.
37
37
38
38
```php
39
39
$settings = \Sabberworm\CSS\Settings::create()
@@ -43,7 +43,7 @@ $parser = new \Sabberworm\CSS\Parser($css, $settings);
43
43
44
44
#### Strict parsing
45
45
46
-
To have the parser choke on invalid rules, supply a thusly configured `\Sabberworm\CSS\Settings` object:
46
+
To have the parser throw an exception when encountering invalid/unknown constructs (as opposed to trying to ignore them and carry on parsing), supply a thusly configured `\Sabberworm\CSS\Settings` object:
47
47
48
48
```php
49
49
$parser = new \Sabberworm\CSS\Parser(
@@ -52,6 +52,8 @@ $parser = new \Sabberworm\CSS\Parser(
52
52
);
53
53
```
54
54
55
+
Note that this will also disable a workaround for parsing the unquoted variant of the legacy IE-specific `filter` rule.
56
+
55
57
#### Disable multibyte functions
56
58
57
59
To achieve faster parsing, you can choose to have PHP-CSS-Parser use regular string functions instead of `mb_*` functions. This should work fine in most cases, even for UTF-8 files, as all the multibyte characters are in string literals. Still it’s not recommended using this with input you have no control over as it’s not thoroughly covered by test cases.
@@ -67,29 +69,26 @@ The resulting data structure consists mainly of five basic types: `CSSList`, `Ru
67
69
68
70
#### CSSList
69
71
70
-
`CSSList` represents a generic CSS container, most likely containing declaration blocks (rule sets with a selector), but it may also contain at-rules, charset declarations, etc. `CSSList` has the following concrete subtypes:
71
-
72
-
*`Document` – representing the root of a CSS file.
73
-
*`MediaQuery` – represents a subsection of a `CSSList` that only applies to an output device matching the contained media query.
72
+
`CSSList` represents a generic CSS container, most likely containing declaration blocks (rule sets with a selector), but it may also contain at-rules, charset declarations, etc.
74
73
75
-
To access the items stored in a `CSSList` – like the document you got back when calling `$parser->parse()` –, use `getContents()`, then iterate over that collection and use instanceof to check whether you’re dealing with another `CSSList`, a `RuleSet`, a `Import` or a `Charset`.
74
+
To access the items stored in a `CSSList` – like the document you got back when calling `$parser->parse()` –, use `getContents()`, then iterate over that collection and use `instanceof` to check whether you’re dealing with another `CSSList`, a `RuleSet`, a `Import` or a `Charset`.
76
75
77
76
To append a new item (selector, media query, etc.) to an existing `CSSList`, construct it using the constructor for this class and use the `append($oItem)` method.
78
77
79
78
#### RuleSet
80
79
81
80
`RuleSet` is a container for individual rules. The most common form of a rule set is one constrained by a selector. The following concrete subtypes exist:
82
81
83
-
*`AtRuleSet` – for generic at-rules which do not match the ones specifically mentioned like`@import`, `@charset` or `@media`. A common example for this is `@font-face`.
82
+
*`AtRuleSet` – for generic at-rules for generic at-rules which are not covered by specific classes, i.e., not`@import`, `@charset` or `@media`. A common example for this is `@font-face`.
84
83
*`DeclarationBlock` – a `RuleSet` constrained by a `Selector`; contains an array of selector objects (comma-separated in the CSS) as well as the rules to be applied to the matching elements.
85
84
86
85
Note: A `CSSList` can contain other `CSSList`s (and `Import`s as well as a `Charset`), while a `RuleSet` can only contain `Rule`s.
87
86
88
-
If you want to manipulate a `RuleSet`, use the methods `addRule(Rule $rule)`, `getRules()` and `removeRule($rule)` (which accepts either a `Rule`instance or a rule name; optionally suffixed by a dash to remove all related rules).
87
+
If you want to manipulate a `RuleSet`, use the methods `addRule(Rule $rule)`, `getRules()` and `removeRule($rule)` (which accepts either a `Rule` or a rule name; optionally suffixed by a dash to remove all related rules).
89
88
90
89
#### Rule
91
90
92
-
`Rule`s just have a key (the rule) and a value. These values are all instances of a `Value`.
91
+
`Rule`s just have a string key (the rule) and a `Value`.
93
92
94
93
#### Value
95
94
@@ -98,19 +97,21 @@ If you want to manipulate a `RuleSet`, use the methods `addRule(Rule $rule)`, `g
98
97
*`Size` – consists of a numeric `size` value and a unit.
99
98
*`Color` – colors can be input in the form #rrggbb, #rgb or schema(val1, val2, …) but are always stored as an array of ('s' => val1, 'c' => val2, 'h' => val3, …) and output in the second form.
100
99
*`CSSString` – this is just a wrapper for quoted strings to distinguish them from keywords; always output with double quotes.
101
-
*`URL` – URLs in CSS; always output in URL("") notation.
100
+
*`URL` – URLs in CSS; always output in `URL("")` notation.
101
+
102
+
There is another abstract subclass of `Value`, `ValueList`: A `ValueList` represents a lists of `Value`s, separated by some separation character (mostly `,`, whitespace, or `/`).
102
103
103
-
There is another abstract subclass of `Value`, `ValueList`. A `ValueList` represents a lists of `Value`s, separated by some separation character (mostly `,`, whitespace, or `/`). There are two types of `ValueList`s:
104
+
There are two types of `ValueList`s:
104
105
105
-
*`RuleValueList` – The default type, used to represent all multi-valued rules like `font: bold 12px/3 Helvetica, Verdana, sans-serif;` (where the value would be a whitespace-separated list of the primitive value `bold`, a slash-separated list and a comma-separated list).
106
+
*`RuleValueList` – The default type, used to represent all multivalued rules like `font: bold 12px/3 Helvetica, Verdana, sans-serif;` (where the value would be a whitespace-separated list of the primitive value `bold`, a slash-separated list and a comma-separated list).
106
107
*`CSSFunction` – A special kind of value that also contains a function name and where the values are the function’s arguments. Also handles equals-sign-separated argument lists like `filter: alpha(opacity=90);`.
107
108
108
109
#### Convenience methods
109
110
110
-
There are a few convenience methods on Document to ease finding, manipulating and deleting rules:
111
+
There are a few convenience methods on `Document` to ease finding, manipulating and deleting rules:
111
112
112
-
*`getAllDeclarationBlocks()` – does what it says; no matter how deeply nested your selectors are. Aliased as `getAllSelectors()`.
113
-
*`getAllRuleSets()` – does what it says; no matter how deeply nested your rule sets are.
113
+
*`getAllDeclarationBlocks()` – does what it says; no matter how deeply nested the selectors are. Aliased as `getAllSelectors()`.
114
+
*`getAllRuleSets()` – does what it says; no matter how deeply nested the rule sets are.
114
115
*`getAllValues()` – finds all `Value` objects inside `Rule`s.
0 commit comments