Resolve parameter conflation in RuleSet methods

[JakeQZ]

Several RuleSet methods currently accept a string or a Rule (or null):

• getRules;
• getRulesAssoc;
• removeRule.

For static analysis, it would be good to avoid this overloading.

getRules

From the PHPDoc:

Passing a Rule behaves like calling getRules($rule->getRule())

Does this shortcut have much value, or could we deprecate passing a Rule without offering an alternative?

getRulesAssoc

From the PHPDoc:

This method exists mainly for backwards-compatibility and is really only partially useful.

Can we deprecate and remove it?

removeRule

This method seems to provide two distinct functions, depending on whether a string or a Rule is passed. I think we should create a separate method for one or the other, with the alternative parameter being deprecated in the original.

Question is, which alternative parameter should be deprecated (and moved to the new method)?

I think the most common usage of the original method should be retained. But I don't know what that is...

[JakeQZ]

@sabberworm, @oliverklee, your input and/or agreement would be welcome, particularly regarding removeRule().

[oliverklee]

Ah, that's why:

The values of CSS are represented untyped, that is using String objects.

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

So their object model is a bit different to what we have.

[JakeQZ]

Yes, there doesn't seem to be an object/interface in CSSOM that represents a "(property) declaration".

[JakeQZ]

On further consideration, I propose

• removeRule() removes a single Rule, and no longer accepts a string;
  • For removing declarations by property name (or prefix), a removeMatchingRules() method is added to provide the functionality deprecated/removed from the original method (this can also accept null to remove all declarations);
• Passing a Rule to getRules() is deprecated and removed, with no alternative provided;
• getRulesAssoc() is deprecated and removed, with no alternative provided.

@sabberworm, @oliverklee, if there are no objections, I will proceed with this.

(Note they are now called declarations not rules, but renaming is part of a longer-term plan, and adding a new method at this stage using Declaration in the name instead of Rule would lead to inconsistency.)

[oliverklee]

Sounds good!

[JakeQZ]

On looking again, we only really need to deprecate passing a Rule to getRulesAssoc(). The method can remain for now with a string parameter; it may be useful for some users.

[JakeQZ]

PRs #1248, #1249, #1254, #1253 and #1255 implemented the proposed plan. #1251 and #1252 were backports for deprecation and replacements. Further tests were added for RuleSet, which were required to complete #974, and are referenced there. Closing as resolved.