Where to place the Custom Ruleset if WPCS is run globally?

[smileBeda]

In past I have created custom rulesets successfully when using WPCS locally in a project.
I simply installed WPCS in the specific project and then put the custom Ruleset in the project's main directory.

But now I want to add a custom ruleset that applies to my global WPCS instance.
I use WPCS in Sublime Text so I installed it several months ago in my Mac path /users/username/wpcs and followed the steps to use WPCS in sublime. This is working perfectly fine.

But when I place my new custom rule set into either:

• the current directory I am scanning

• OR into the users/username/wpcs path where WPCS is globally installed

• OR in its parent directory users/username/ then that ruleset is not "seen/applied"

What am I doing wrong?
As far I understand from the Docs, the custom ruleset (BTW named phpcs.xml, so it takes priority if there are others, which is not the case, but just to be safe), if added to either current dir or parent dir should simply be automatically applied?

[jrfnl]

@TukuToi I have a feeling this is three questions in one, so I'm going to try and pick it apart and answer them individually.

1. PHPCS looks for a custom ruleset in the directory you are scanning and directories above it.
   When it finds a phpcs.xml.dist, .phpcs.xml.dist, phpcs.xml or .phpcs.xml file in any of those directories, it will use that automatically and apply it to the code under scan.

The precedence order is as per the above list with a .phpcs.xml file having the highest precedence and a phpcs.xml.dist file the lowest, in other words: if a phpcs.xml file is found as well as a phpcs.xml.dist file, the phpcs.xml file will be used.

2. I don't know Sublime well, but I do know that a lot of IDEs when running PHPCS, place a temp file with the current changes to a file being edited somewhere and scan that instead of the file as it is on disk.
   When that happens, PHPCS will look for a custom ruleset in the directory of the temp file and those above it (as described in [1]) and will likely not find the custom ruleset.
   You will need to go into the settings for Sublime to tell Sublime to use your custom ruleset. I can't tell you how to do this, but the tutorial linked in the WPCS wiki should be able to help you figure this out (I hope).

3. PHPCS does not look for a custom ruleset in the directory in which you have installed the standard.
   If you want a "generic" ruleset which you can apply to multiple projects, you are better off creating an external standard and registering this standard with PHPCS. You can then reference that standard by name in your project ruleset(s) or in Sublime.

Does that help ?

[smileBeda]

It helps to get me started to resolve this problem, yes.

I have tried to place the file in all possible directories I knew of which are:

• the global WPCS install path /users/username/wpcs (and parents thereof)
• the project I scan (and parents thereof)

I did not think about the peculiarity that Sublime might use another folder altogether to scan the files

In case that helps understand what I want, I just want to "overwrite" a couple WPCS rules, not create a full blown new standard.
I want to do that only on this one project.

For example, I want to register my own "esc_" function and stop WPCS from telling me "you are not escaping/please use esc_".
So that is why I use the custom rule set, and in previous projects I simply placed that file into the scanned directory - but the difference there was, that I also installed WPCS directly on those projects, thus not using the global WPCS I have on my machine, but a local one.

I might as well just repeat what worked in past (namely install WPCS in this particular project and not use the global one)
But I would prefer to be able to "switch" quickly on a global basis while in Sublime (thus, I thought I am smart and just place the ruleset in my project, and remove it/move to it to other projects if I need it there)

I will check now on the Sublime if I can figure out where it scans the files, and try to place the ruleset there.

[jrfnl]

More than anything that sounds like a Sublime peculiarity in how it handles PHPCS global vs PHPCS local install as whether you have PHPCS installed globally or locally makes no difference in how it tries to find the rulesets.

[smileBeda]

I found https://gist.github.com/andrewlimaza/fe68efd141e2e9e8d8e46407d90b90b2 - looking at those Sublime settings, I see they actually set the standard to that file with "--standard": "~/bin/phpcs.xml",

I tried that using their sample xml file, which did not work, but it did work with the https://raw.githubusercontent.com/WordPress/WordPress-Coding-Standards/develop/phpcs.xml.dist.sample file.

So far so good, then I removed all "customisation" from that sample file and added my own custom rule:

<rule ref="WordPress.Security.EscapeOutput.OutputNotEscaped">
		<properties>
			<property name="customEscapingFunctions" type="string">
				<element value="out_html" />
				<element value="X_Sanitize" />
			</property>
		</properties>
	</rule>

It is supposed to recognise a X_Sanitize::out_html() as a validly escaped value.
But the WPCS tells me that all output should be run thru escaping functions. Found 'X_Sanitize'

So now, I guess my only issue left is how do pass a custom rule that uses a class method (although, even if I try just for testing with echo out_html() the rule still does not apply, so I guess something is fishy with my rule per se)

This might be stuff for a new discussion, I guess.

---

TL;DR:
To add a custom rule set - in sublime - you have to specify the path to the ruleset in the phpcs_additional_args --standard argument in the phpcs.sublime-settings (user settings) file. This can be reached thru the menu Sublime Text > Preferences > Package Settings > PHP Code Sniffer > Settings User.

Hope that helps someone struggling with the same, and thanks for pointing me to the right direction!

[jrfnl]

It is supposed to recognise a X_Sanitize::out_html() as a validly escaped value.
But the WPCS tells me that all output should be run thru escaping functions. Found 'X_Sanitize'

So now, I guess my only issue left is how do pass a custom rule that uses a class method (although, even if I try just for testing with echo out_html() the rule still does not apply, so I guess something is fishy with my rule per se)

You're not doing anything wrong here, it's just that that is something which isn't supported in WPCS (yet).
The EscapeOutput sniff in WPCS only supports functions - also see WordPress/WordPress-Coding-Standards#1176

[smileBeda]

Did not see this reply prior. It matches what I found - it seems to validate the class but not the method so for now I’ll have to stick with that or add a actual global function which in turn calls the method.

Thanks a lot for the help here!

[smileBeda]

As an update, this seems to do the job:

	<rule ref="WordPress.Security.EscapeOutput">
		<properties>
			<property name="customEscapingFunctions" type="array">
				<element value="X_Sanitize"/>
			</property>
		</properties>
	</rule>

It will not check if the right method is actually used - it seems not capable of that, but at least it checks for the class. This is a bit sad, because I might have classes with distinct methods that do different things, and it would be wrong to use method A when really method B would be the required one, yet I seem I cannot specific it with class::method or class->method syntax...

Apart of that It seems I had too much specified the <rule ref="WordPress.Security.EscapeOutput"> in my earlier case... and used string instead of array in the type.
So that is now resolved, leaves the issue with using class methods seems not the best way to use WPCS... and perhaps PHP at all, maybe I should just create a global function API that then on its own calls the class::methods

If anyone has an idea or knows how to register class methods for WPCS I am happy to hear 👍