Audit Public Sniff Properties

What problem would the enhancement address for VIP?

There are 47 instances of public properties within sniff classes. Public properties allow changing sniff behaviour by customising a ruleset by passing different types of values via the ruleset. VIP uses itself to adjust how a WPCS sniff runs.

However, I suspect that some of the instances are NOT meant to be changed - whitelisted Batcache params, restricted constant names and declarations, etc.

Describe the solution you'd like

Audit the uses and convert to private where suitable. Document the rest on a wiki page.

I'll create a linked list of the 47 instances, possibly along with who added them, to check if they are meant to be public or not.

For those that are meant to be changeable, then a better approach for some cases is to have a private default list of values, and then a public custom list, and the two lists merged together - that way, the custom rulesets don't need to also add in the default values as well.

Additional context

Note that this would technically be a breaking change, since it is possible that someone was already making use of these unintentional public properties in their own rulesets. As such, this would require a bump from 0.y.z to 0.y+1.0, or a normal major release if 1.0.0 has been released in the meantime.

One approach here would be to initially make all of the public properties private, and then introduce other public properties if needed, and have a process for merging these two sets of data together. One example is a simple case in WPCS.

Here are all of the public properties. Some of them will be false poitives (i.e. should be left as public):

AbstractVariableRestrictionsSniff.php
- public $exclude;
Classes/DeclarationCompatibilitySniff.php
- public $checkClasses;
- public $checkClassesGroups;
Constants/RestrictionConstantssSniff.php
- public $restrictedConstantNames;
- public $restrictedConstantDeclaration;
Files/IncludingFileSniff.php
- public $getPathFunctions;
- public $restrictedConstants;
- public $allowedConstants;
- public $slashingFunctions;
Functions/CheckReturnValueSniff.php
- public $catch;
- public $notFunctions;
JS/DangerouslySetInnerHTMLSniff.php
- public $supportedTokenizers;
JS/HTMLExecutingFunctionsSniff.php
- public $HTMLExecutingFunctions;
- public $supportedTokenizers;
JS/InnerHTMLSniff.php
- public $supportedTokenizers;
JS/StringConcatSniff.php
- public $supportedTokenizers;
JS/StrippingTagsSniff.php
- public $supportedTokenizers;
JS/WindowSniff.php
- public $supportedTokenizers;
Performance/BatcacheWhitelistedParamsSniff.php
- public $whitelistes_batcache_params;
Performance/TaxonomyMetaInOptionsSniff.php
- public $option_functions;
- public $taxonomy_term_patterns;
Security/MustacheSniff.php
- public $supportedTokenizers;
Security/ProperEscapingFunctionSniff.php
- public $escaping_functions;
Security/TwigSniff.php
- public $supportedTokenizers;
Security/UnderscorejsSniff.php
- public $supportedTokenizers;
Security/VuejsSniff.php
- public $supportedTokenizers;
UserExperience/AdminBarRemovalSniff.php
- public $supportedTokenizers;
- public $remove_only;
Variables/ServerVariablesSniff.php
- public $restrictedVariables;
Variables/VariableAnalysisHelper.php
- public $owner;
- public $opener;
- public $closer;
- public $variables;
- public $name;
- public $scopeType;
- public $typeHint;
- public $passByReference;
- public $firstDeclared;
- public $firstInitialized;
- public $firstRead;
- public $ignoreUnused;
Variables/VariableAnalysisSniff.php
- public $sitePassByRefFunctions;
- public $allowUnusedCaughtExceptions;
- public $allowUnusedFunctionParameters;
- public $validUnusedVariableNames;
VersionControl/MergeConflictSniff.php
- public $supportedTokenizers;

Working list (will be edited) for properties not yet checked or excluded:

AbstractVariableRestrictionsSniff.php
- public $exclude;
Classes/DeclarationCompatibilitySniff.php
- public $checkClasses;
- public $checkClassesGroups;
Constants/RestrictionConstantssSniff.php
- public $restrictedConstantNames;
- public $restrictedConstantDeclaration;
Files/IncludingFileSniff.php
- public $getPathFunctions;
- public $restrictedConstants;
- public $allowedConstants;
- public $slashingFunctions;
Functions/CheckReturnValueSniff.php
- public $catch;
- public $notFunctions;
JS/HTMLExecutingFunctionsSniff.php
- public $HTMLExecutingFunctions;
Performance/BatcacheWhitelistedParamsSniff.php
- public $whitelistes_batcache_params;
Performance/TaxonomyMetaInOptionsSniff.php
- public $option_functions;
- public $taxonomy_term_patterns;
Security/ProperEscapingFunctionSniff.php
- public $escaping_functions;
UserExperience/AdminBarRemovalSniff.php
- public $remove_only;
Variables/ServerVariablesSniff.php
- public $restrictedVariables;
Variables/VariableAnalysisHelper.php
- public $owner;
- public $opener;
- public $closer;
- public $variables;
- public $name;
- public $scopeType;
- public $typeHint;
- public $passByReference;
- public $firstDeclared;
- public $firstInitialized;
- public $firstRead;
- public $ignoreUnused;
Variables/VariableAnalysisSniff.php
- public $sitePassByRefFunctions;
- public $allowUnusedCaughtExceptions;
- public $allowUnusedFunctionParameters;
- public $validUnusedVariableNames;

At this point, I don't think we've seen a sufficient number of users trying to amend public property values to the point where the expected default content is not present.

While it would be nice to be confident that some minimum default values are present, that users can supplement, I don't think that adding this in, in a more formalised way, is the best use of time right now.

Can be re-opened again if the issue is deemed worthy, or individual properties can be dealt with on a case-by-case basis.

Proposal: for those properties for which the visibility ought to be changes, add the new private properties in VIPCS 2.x and throw a deprecation warning if the value of the public property is not the same as the private one (= changed from within a custom ruleset).

That way customers, who would be (ab)using the fact that these properties are currently public, would get some warning about this upcoming change.

Updated list as per July 20, 2025 categorized by my opinion on the action which should be taken:

Properties which should stay `public`

AbstractVariableRestrictionsSniff.php
- public $exclude;
UserExperience/AdminBarRemovalSniff.php
- public $remove_only;

Properties which should be made `private`

👉🏻 or protected if you want to allow potential child classes to overrule the property value.

Classes/DeclarationCompatibilitySniff.php - these properties expect a multi-level array format which can't even be set from within a ruleset.
- public $checkClasses;
- public $checkClassesGroups;
Constants/RestrictionConstantssSniff.php - what good is it to restrict constants when the list of restricted constants can be cleared from within a ruleset ?
Candidate for public/private logic, i.e. have an empty array for the public property and the non-overwritable base list in the private property and then merge those lists when the sniff runs. This would allow users to add to the list, but not remove anything from it.
- public $restrictedConstantNames;
- public $restrictedConstantDeclaration;
Files/IncludingFileSniff.php - Candidate for public/private logic (as described above)
- public $getPathFunctions;
- public $restrictedConstants;
- public $allowedConstants;
- public $allowedKeywords;
- public $slashingFunctions;
Functions/CheckReturnValueSniff.php - neither of these should ever have been public. $catch could be considered a candidate for protected if there would be external sniffs extending this sniff.
- public $catch;
- public $notFunctions;
Performance/TaxonomyMetaInOptionsSniff.php - could be considered for public/private logic, but I can't think of a valid use-case for it.
- public $option_functions;
- public $taxonomy_term_patterns;
Variables/ServerVariablesSniff.php - this property expects a multi-level array format which can't even be set from within a ruleset.
- public $restrictedVariables;

Properties to ignore

JS/HTMLExecutingFunctionsSniff.php - sniff is deprecated and will be removed in 4.0
- public $HTMLExecutingFunctions;

Properties which should be removed

Aside from the above, the following sniffs contain a public $supportedTokenizers property.
That property is/was needed for sniffs supporting the scanning of JS/CSS files in PHPCS < 4.0.
As of PHPCS 4.0, scanning JS/CSS files is no longer supported by PHPCS.
The WAIT-4.0/DROP-SUPPORT-FOR-PHPCS-lt-4/feature/remove-css-js-sniff-code branch (for issue #442) includes a commit removing these properties.

JS/DangerouslySetInnerHTMLSniff (sniff removal)
JS/HTMLExecutingFunctionsSniff (sniff removal)
JS/InnerHTMLSniff (sniff removal)
JS/StringConcatSniff (sniff removal)
JS/StrippingTagsSniff (sniff removal)
JS/WindowSniff (sniff removal)
Security/MustacheSniff (JS file support will be removed)
Security/TwigSniff (JS file support will be removed)
Security/UnderscorejsSniff (JS file support will be removed)
Security/VeujsSniff (JS file support will be removed)
UserExperience/AdminBarRemovalSniff.php (CSS file support will be removed)

Note: the "Candidate for public/private logic" actions do not have to wait for the next major as the public property would not be removed.

Navigation Menu

Repository navigation

Audit Public Sniff Properties #234

What problem would the enhancement address for VIP?

Describe the solution you'd like

Additional context

Properties which should stay `public`

Properties which should be made `private`

Properties to ignore

Properties which should be removed

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Audit Public Sniff Properties #234

Description

What problem would the enhancement address for VIP?

Describe the solution you'd like

Additional context

Activity

GaryJones commented on Jan 6, 2019

GaryJones commented on Jan 6, 2019

GaryJones commented on Jan 17, 2019

GaryJones commented on Jan 20, 2019

jrfnl commented on Sep 14, 2020

jrfnl commented on Jul 19, 2025

Properties which should stay public

Properties which should be made private

Properties to ignore

Properties which should be removed

jrfnl commented on Jul 19, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Properties which should stay `public`

Properties which should be made `private`