Further renaming of RuleSet classes

[JakeQZ]

Ref: https://developer.mozilla.org/en-US/docs/Web/API/CSS_Object_Model/CSS_Declaration

We still have some misnamed classes in RuleSet:

• The class named RuleSet represents what is now known as a declaration block (the declaration block does not include the selector);
• The class named DeclarationBlock represents what is now known as a rule (a rule has a selector and a declaration block, or may be an at-rule);
• The class named AtRuleSet represents what is now known as an at-rule;
• A 'rule set' is not now a concept in the CSS grammar, and the namepsace could perhaps be better named as Rule.

To rename these in a seamless manner presents some problems:

• We can't rename RuleSet to DeclarationBlock unless we move it to a different namespace, as a DeclarationBlock class already exists (and will need a class_alias() during the transition period);
• The ideal namespace for these classes is probably Rule, but there was previously a class named Rule in that namespace (which currently has a class_alias()); so if we renamed DeclarationBlock to Rule and moved it there, it may cause upgrade issues (we can make a major release to absolve responsibility, but I'd rather not land users with unexpected problems);
• AtRuleSet implements AtRule, though I think changing the class name to be the same as the interface name will be possible with use as.

@sabberworm, @oliverklee, would welcome your thoughts.

[oliverklee]

First of all, I'm all for naming for having more correct (and hence less confusing) names!

The ideal namespace for these classes is probably Rule, but there was previously a class named Rule in that namespace

My best guess is that there's no (technical) problem with class names being prefixes of other class names (even though it might by a tad confusing for humans). I'd say we give it a go, and prioritize correct naming.

AtRuleSet implements AtRule, though I think changing the class name to be the same as the interface name will be possible with use as.

Yes, that's correct AFAIK.

We can't rename RuleSet to DeclarationBlock unless we move it to a different namespace, as a DeclarationBlock class already exists (and will need a class_alias() during the transition period);

This would probably work if we put it in the new Rule namespace, right?

[oliverklee]

Hmmmmm…

At the moment, we have Parser, Settings etc. on the same namespace level as the different "CSS thing" sub-namespaces.

Maybe we can add an additional sub-namespace for these "CSS things" (and I'd need your brainpower to come up with a suitable name). Then we can move/add the reworked classes their (using class aliases for backward compatibility).

WDYT?

[JakeQZ]

At the moment, we have Parser, Settings etc. on the same namespace level as the different "CSS thing" sub-namespaces.

Maybe we can add an additional sub-namespace for these "CSS things" (and I'd need your brainpower to come up with a suitable name). Then we can move/add the reworked classes their (using class aliases for backward compatibility).

WDYT?

I like this idea. It kills two birds with one stone.

The "CSS things" - i.e. objects reprenting elements of the parsed CSS - can be considered to be part of the CSS Object Model (CSSOM). It's a JavaScript interface, for which PHP has no equivalent. But PHP does have an equivalent for the DOM interface. And this library, to all extents and purposes, is providing an equivalent for CSSOM.

So we could move all the classes for 'CSS things' into a namespace Sabberworm\CSS\ObjectModel.

The referenced documentation would be useful for ensuring the moved classes have accurate names. Though JavaScript doesn't have namespaces, and the W3C interface also has some misnomers, e.g. "The CSSStyleDeclaration interface is the base class for objects that represent CSS declaration blocks".

[oliverklee]

Great! Then let's do that!

In addition to the CSS OM, there's also the CSS typed OM. We might want have a look at that as well and check whether to adopt anything from there.

Would you be willing to create a checklist of renamings (or classes to create) in this ticket, @JakeQZ ?

[JakeQZ]

Would you be willing to create a checklist of renamings (or classes to create) in this ticket, @JakeQZ ?

I've made a start with #1545 but it's not a complete list yet.

I'm also thinking that I much prefer namings like CssElement to CSSElement - the capital letters shout at me a bit, and make it harder to decompose the class name - though in PHP they are case insensitive anyway.

[oliverklee]

Yes, I'd also prefer CssElement over CSSElement.

This is also what the PER-3 coding style strongly recommends:

Abbreviations, acronyms, and initialisms SHOULD be treated like regular words, thus they SHOULD be written with an uppercase first character, followed by lowercase characters.