Do not report errors when a path is provided to CLI, but file is not included in a phpcs.xml file.

[jannes-io]

Is your feature request related to a problem?

I would like PHPCS to do nothing if the provided file is not explicitly included through the phpcs.xml(.dist).

Given we have /home/developer/project set up as follows:

src/
-- included/
---- test.php
-- ignored/
---- test.php
vendor/
composer.json
phpcs.xml
...

And a phpcs.xml as such:

<?xml version="1.0" encoding="UTF-8"?>
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="vendor/squizlabs/php_codesniffer/phpcs.xsd">

    <arg name="basepath" value="."/>
    <arg name="extensions" value="php"/>

    <rule ref="PSR12"/>

    <file>src/included</file>
</ruleset>

And you run the phpcs command on a non-included file, it still outputs errors.

./vendor/bin/phpcs /home/developer/project/ignored/test.php -q -s

So I would like to add a flag to silence phpcs if the provided file is not in phpcs.xml.

Context: neovim users can use phpcs as a "language server" through none-ls (formerly known as null-ls) (somewhat related to #640 I suppose, neovim superiority 😆). We can add custom arguments, and it essentially just runs phpcs on the current open file.

spawning command "./vendor/bin/phpcs" at /home/developer/project with args { "--report=json", "-q", "-s", "--runtime-set", "ignore_warnings_on_exit", "1", "--runtime-set", "ignore_errors_on_exit", "1", "--stdin-path=/home/developer/project/src/ignored/test.php", "--basepath=", "-q", "--report=emacs", "-" }

Then it parses the output, and adds in-line errors/warnings/...

Currently it's also doing this for files that aren't even in the project, like in vendor, in ignored directories,... which is really annoying. I don't care if a vendor uses a different codestyle from me..

Describe the solution you'd like

When a phpcs.xml is detected, and it has file entries, and the file provided through stdin is not in one of the file entries, just return nothing.

I understand this might break backwards compatibility, for that reason, perhaps this behavior could be added behind a new flag? (we have the ability to customize the input args in none-ls, so we can easily add an extra flag)

Additional context (optional)

• I have read the Contribution Guidelines and this is not a support question.
• I intend to create a pull request to implement this feature. (provided I get some pointers where to look)

[jrfnl]

@jannes-io I understand your problem and thank you for providing the neovim context.

I believe your problem can already be solved with the current configuration options without adding new flags or changing the behaviour for PHPCS for everyone.

What is currently happening in your situation is that you overrule the <file> argument set in the configuration file with the explicit file you request to be scanned from the command line.

What you want to happen is that certain directories are never scanned.

So, I believe the below configuration will fix that for you, as the changed <file> directive will now scan - and allow for scanning - all php files by default, while the exclude-pattern settings will ensure that PHPCS bows out for those directories which should never be scanned.

<?xml version="1.0" encoding="UTF-8"?>
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="vendor/squizlabs/php_codesniffer/phpcs.xsd">

    <file>.</file>

    <exclude-pattern>/src/ignored/</exclude-pattern>
    <exclude-pattern>/vendor/</exclude-pattern>

    <arg name="basepath" value="."/>
    <arg name="extensions" value="php"/>

    <rule ref="PSR12"/>

</ruleset>

You could, of course, change <file>.</file> to <file>./src/</file> if you like and then get rid of the <exclude-pattern>/vendor/</exclude-pattern>, but I'll leave that up to you as those kind of choices depend on the individual project/repo layout.

Mind/just so you are aware: just like passing explicit file names on the command-line will overrule <file>, passing the --ignore=.... argument on the command-line will overrule the top-level <exclude-pattern>s set in a ruleset.

[jannes-io]

Hi @jrfnl , thanks for your speedy response.

Interesting, so with exclude-pattern it does exclude. I see now how providing a file in stdin just overwrites the files tag defined in phpcs.xml

I can't exactly go and add vendor to the exclude-pattern of every project. I also do a bit of OSS development in the Symfony ecosystem from time-to-time, I can't be editing their phpcs files or adding my own (non-dist) every time I want to clone a repo.

It's clear that the "convention" is to add everything that should be scanned by phpcs to files tags, and then exclusions are only to create further exceptions inside of those files.

Example: https://github.com/doctrine/orm/blob/3.5.x/phpcs.xml.dist

So I'd prefer to have a solution where I can modify my personal development setup, and leave anything defined in the project alone.

[jrfnl]

So I'd prefer to have a solution where I can modify my personal development setup, and leave anything defined in the project alone.

@jannes-io You're in luck, as that is also already possible.

If no --standard=... argument is used on the command-line, PHPCS will try to find the following files (listed in order of precedence):

• .phpcs.xml
• phpcs.xml
• .phpcs.xml.dist
• phpcs.xml.dist

What this means is, that if a project has a phpcs.xml file, you can just have your own local .phpcs.xml to overload that file without even needing to touch the CLI args as PHPCS will automatically pick up on the file.

If you then add something like the below in your .phpcs.xml file, you import and can then add to/adjust/overload whatever you want from the original ruleset.

<?xml version="1.0"?>
<ruleset name="my own ruleset">

    <!-- Import the project ruleset -->
    <rule ref="phpcs.xml.dist"/>

    <!-- Add your own additional rules/overload rules. -->
    <exclude-pattern>...</exclude-pattern>

</ruleset>

Also see: https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/About-Standards-for-PHP_CodeSniffer#how-does-php_codesniffer-determine-which-standard-or-ruleset-to-apply-

Pro-tip: if a project is using PHPCS natively, it is recommended for the project ruleset to be called [.]phpcs.xml.dist and for the .phpcs.xml and phpcs.xml file names to be added to the project .gitignore file.

Having that kind of setup in a project, makes what I explained above about ruleset overloading very straight-forward for contributors to the project.
If any of the OSS projects you contribute use the .phpcs.xml filename, a PR to change that filename and update their .gitignore would be a good contribution in my opinion.

If that wouldn't be accepted, you can still ignore your overload file via your own local .git/info/exclude file.
And you can even overload the .phpcs.xml file if needs be, but that would mean passing the --standard=... CLI argument, like --standard=my-overload-ruleset.xml.

Hope that helps ;-)

[jannes-io]

I will play around with those options to see if I can find something that'll satisfy my needs. I was hoping for a solution where I didn't have to create any custom phpcs.xml files, and I could just clone any repo with a phpcs.xml(.dist) and have my editor ignore non-included files by default.

I can't be editing their phpcs files or adding my own (non-dist) every time I want to clone a repo.

If that's out of the question, I'll probably have to create some wrapper script around phpcs that can auto exclude files that aren't explicitly defined in <files> tags if any are defined.

[jrfnl]

I was hoping for a solution where I didn't have to create any custom phpcs.xml files, and I could just clone any repo with a phpcs.xml(.dist) and have my editor ignore non-included files by default.

That sounds like something to take up with the developers of the editor you use. There may be configuration options in the editor which can help you there.

I can't be editing their phpcs files or adding my own (non-dist) every time I want to clone a repo.

If that's out of the question, I'll probably have to create some wrapper script around phpcs that can auto exclude files that aren't explicitly defined in <files> tags if any are defined.

One other thing which comes to mind, but again, this involves editor configuration, PHPCS accepts multiple standards on the command line, like --standard=phpcs.xml.dist,my-extra-rules.xml.

You could see about creating a very generic my-extra-rules.xml file which you can use with all the projects and see if there is a way for the editor to always include that in the command it sends to PHPCS (while also respecting the default project configuration file).

[jrfnl]

I can't exactly go and add vendor to the exclude-pattern of every project.

P.S.: regarding 👆🏻 - if you think you can improve an OSS project's PHPCS configuration to make it more straight-forward for contributors to contribute using their favorite IDE, I'd say that kind of PR would be a valid improvement to pull.
Might be annoying to have to do that in lots of projects, but if you explain how it will make the contributing experience better, I bet a lot of projects would welcome the change and you'd be making OSS contributing a better experience for everyone.

[jannes-io]

Hi, thank you so much for your help and explanation of possible solutions to my issue.

I will definitely be having a look at what the possibilities are in terms of using an alternate standard alongside the project's standard, or by dynamically generating a standard/ignore list that is the inverse of the files list. You've given me some ideas to get started.

That sounds like something to take up with the developers of the editor you use.

Well, (un)fortunately, in neovim/vim.., this type of stuff is up to the user to configure and write themselves in vimscript or lua. So I am the developer of my editor 😆

I'd say that kind of PR would be a valid improvement to pull.

While I generally agree with you there, I understand for maintainers it's a fine line to walk. For PHPCS/Stan/Psalm configs it is probably fine, but generally committing things like .idea or .vscode is frowned upon. I would personally also never allow editor-specific configuration in repositories that I maintain, professionally or not.

So again, thanks for the detailed explanation and pointers that got me looking in the right direction, I now know what I have to do to get it to work.