Add PHP CS Fixer as a formatting tool and lint-stage during github CI

[Zombaya]

During review of #2403, errors in formatting/code style were sometimes spotted by the reviewers and had to be manually fixed.

I strongly believe this is something better suited for a tool to handle. I feel this will lessen the burden on both
contributors and reviewers as the formatting of the code will no longer be a point of discussion.

Description of changes

• Installed PHP CS Fixer as by the recommended way from the readme in a seperate tool-directory.
• Added a new github action to lint code using PHP CS Fixer
  • On failure, it will show a message on how to fix the formatting problems. See this github action report for reference.
• Added instructions on how to use PHP CS Fixer in CONTRIBUTING.md
• Ran tools/php-cs-fixer/vendor/bin/php-cs-fixer fix -v and autoformatted all code in a seperate commit
• Modified .gitattributes to avoid exporting newly added files

Rationale of certain choices

PHP CS Fixer as formatting tool

There are other tools which can be used as a formatting tool (such as PHP_CodeSniffer). Since I personally had the most experience using PHP CS Fixer and because the tool was already mentioned in CONTRIBUTING.md, I chose to use this tool specifically.

Fixed version

I opted to use an exact version in composer.json in tools/php-cs-fixer to avoid formatting-conflicts resulting from different version of the tool used.

This is the latest version available and supports php 7.4|8.*.

I believe we should not support older versions here since this is only used to develop the library, not by end-users of the library.

As a downside, this means that occasionally the version will have to be manually bumped in tools/php-cs-fixer/composer.json to keep the formatting-standard up to date.

PSR-12 PER as standard

Since PSR-standards were already referenced in CONTRIBUTING.md, PSR-2 has been deprecated in favor of PSR-12 since 2019-08-10, which is now deprecated in favor of PER and I feel the larger PHP-world is migrating to PER, I found this to be the most suitable standard to start with.

Possible improvements

• Install php-cs-fixer using a post-install-hook from composer. I opted not to do this because I believe this will cause issues when somebody tries to install for the first time using PHP <= 7.3.
• Create a symlink to tools/php-cs-fixer/vendor/bin/php-cs-fixer in vendor/bin to make it easier to run the tool. I opted not to do this since I feared issues when somebody would use windows or mac to develop this library.

Merge-strategy

To review my actual changes, I'd review my first commit separately from the second.
The first commit holds all relevant changes to the configuration of the project. The second commit only contains changes made by PHP CS Fixer, so only contains formatting changes.

Because the autoformat changes so many files, I'd not merge this PR directly.
Once some commits will have been committed to master, this PR will have mergeconflicts which will be hard/tedious to fix manually.
Instead, I would rebase on master, skip/drop my latest commit containing the automatic formatting of all files and recreate that commit manually.

### Option 1 ###
git fetch origin
git rebase -i origin/master
# Only pick first commit here, do not pick second commit 

composer install --working-dir=tools/php-cs-fixer
tools/php-cs-fixer/vendor/bin/php-cs-fixer fix -v
git add .
git commit -m 'Autoformat src and tests to PSR-12 using php-cs-fixer'

### Option 2 ###
git fetch origin
git reset --hard origin/master
git cherry-pick COMMIT-HASH-OF-FIRST-COMMIT
composer install --working-dir=tools/php-cs-fixer
tools/php-cs-fixer/vendor/bin/php-cs-fixer fix -v
git add .
git commit -m 'Autoformat src and tests to PSR-12 using php-cs-fixer'

Post Scriptum

Feel free to let me know if you feel this wouldn't be of benefit to the project or that this PR needs some tweaks before it can be merged.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[SamRemis]

Thank you :) this PR makes everything look much neater; I'll try to get it merged soon, but it's another long review process since it touches so many files. This is modifying some autogenerated code, so I'd like to modify the code generator before merging this so that it doesn't give us warnings every release with newly autogenerated code. Since this is mostly whitespace changes, I think it'll be much faster though.

[SamRemis]

Actually, I could add it in as part of this PR, that probably makes more sense. Can you grant me rights to edit it?

[Zombaya]

Glad to hear you see value in my PR :-).

I already checked the "Allow edits and access to secrets by maintainers" and now I invited you as a collaborator on my project, so you should be able to contribute to it (once you accept the invitation).

Hats off to you if you are willing to go through the whole PR.

If you want to make sure I did not manually add something nefarious in my second commit, feel free to drop it and recreate it. Only thing I did there was run the tool so I don't take credit for that commit at all.

We could also do it in increments if that is easier to process. To do this, we would simply need to modify php-cs-fixer.dist.php and decrease the scope of files to fix. Afterwards we could increase the scope again, review, merge, increase scope, review, merge, ...

[stobrien89]

Hi @Zombaya,

Thanks again for the contribution and apologies for the delay— we were a bit busy with some major functionality and are just now finding the time to focus on community PRs. Could you rebase? Interested in resuming our review of this.

[Zombaya]

Hi @stobrien89 ,

It's a busy time at work so I wasn't able to get to it immediately. I've done the following:

• rebased onto master
• changed the standard from PSR-12 to PER
• updated php-cs-fixer to latest version
• Instead of locking the version of php-cs-fixer by setting the a strict version in tools/php-cs-fixer/composer.json, I've added the lock-file of that directory to the project.
• added script-aliases to make it easier to install and run php-cs-fixer.
• Ran php-cs-fixer again in a seperate commit. I had to run it twice since some files were not fully fixed after one run.

You can now run:

• composer install-cs-fix: installs the php-cs-fixer in the directory tools/php-cs-fixer
• composer cs-fix: runs php-cs-fixer and fixes formatting for all files

To review this, I'd focus on verifying the first commit and generating the changes of the second commit yourself, so you are certain I did not manually tamper with the files.

I would not want to be in your shoes if you are going to review all those changes one by one. I'd be imppressed if you were to pull that one off!

[Zombaya]

I noticed I forgot to update contributing.md to reflect the change of codestyle from PSR-12 to PER and to update the lint-CI-job to output the new composer commands to fix your codestyle.

I ammended the commit and pushed again.