Arrays/ArrayDeclarationSpacing: how to deprecate the `allow_single_item_single_line_associative_arrays` property?

[rodrigoprimo]

PR #2688 updates the WordPress.Arrays.ArrayDeclarationSpacing sniff to use "arrays with explicit keys" instead of "associative arrays" in its error messages. As part of that change, @jrfnl suggested deprecating the allow_single_item_single_line_associative_arrays property in favor of a new name in a separate PR, keeping both properties until the 4.0 release.

As far as I could check, this would be the first public property deprecation since WPCS 2.0, so I'd like to discuss the best approach before implementing it.

Previous approach

Before WPCS 2.0, two public properties were deprecated with a backwards compatibility layer:

1. EscapeOutputSniff::$customSanitizingFunctions became $customEscapingFunctions (78791a6)
2. ValidVariableNameSniff::$customVariablesWhitelist became $customPropertiesWhitelist (be11bc2)

The pattern used was:

• Keep the old property public, mark as @deprecated in the docblock.
• Check if the old property was changed from its default (using ! empty() for array properties).
• If changed, merge the old property's value into the new one and issue a deprecation notice via $phpcsFile->addWarning() at line 0.
• Both properties were removed in the 2.0 release (405f264).

Questions

1. Is the addWarning() approach from the pre-2.0 era still the preferred way to handle this? Or is there a better alternative?
2. For a boolean property (default true), the detection would check true !== $this->old_property_name to catch any non-default value. However, this approach won't trigger the deprecation notice when the old property is explicitly set to its default value (hopefully an edge case). As far as I could find, there is no way to check whether the user explicitly set a property. Is there a better way to handle this?

[jrfnl]

1. Is the addWarning() approach from the pre-2.0 era still the preferred way to handle this? Or is there a better alternative?

Just my two cents:

• I would start with a soft deprecation (changelog + docblock only) in the next minor.
• Then in the ~last minor before the next major, we could consider adding a warning for those people still using the old property name.

To gauge the impact, you could try to do some code searches for XML files containing the text allow_single_item_single_line_associative_arrays.

If the impact is very low, you could even consider submitting PRs to the few repos using the property ;-)

Note: yes, I'm aware that would not catch usage in private repos, so we'd still want to add the warning in the "last version before".

2. For a boolean property (default true), the detection would check true !== $this->old_property_name to catch any non-default value. However, this approach won't trigger the deprecation notice when the old property is explicitly set to its default value (hopefully an edge case). As far as I could find, there is no way to check whether the user explicitly set a property. Is there a better way to handle this?

Might be worth investigating if this could be handled by making the old property private and adding a set of magic methods to handle the property setting for the old property...