Tutorial: Getting started with PHP Codesniffer

Tutorial given on September 29, 2017 at the PHP North West Conference, Manchester, United Kingdom.
http://conference.phpnw.org.uk/phpnw17/tutorial-day/
---------------------------------------------------------------
So you'd heard of the PHP Codesniffer and thought you'd give it a try. You set it up & ran it over one of your projects and it tells you there are over 6000 things wrong with your code... Darn... that sounds like work. Let's leave it for another day....

Or not.

In this workshop I'll help you to properly get started with PHPCS. Everyone can bring their own project to work on. We'll look at the different rulesets available, select the one(s) which will work best for your project. Next, we'll look at customizing the ruleset to best suit your project & team's needs and we'll start auto-fixing issues. If all goes well, those 6000 things "wrong" will be down to zilch by the end of the workshop & you've got a pull request ready to prove it!

Transcript

1. Getting Started with PHP Codesniffer Thaliesin
2. Agenda 1. Intro round 2. Creating a style guide 3. Creating a ruleset === BREAK === 4. Fine tuning the ruleset 5. Fixing the code base 6. Keeping the code base clean 7. Closing
3. Hello! Juliette Reinders Folmer @jrf_nl @jrfnl
4. Previous experience with PHP Codesniffer ? What project did you bring with you ? What do you hope to learn today ? Who are you ? Marnhe du Plooy
5. Install Check phpcs –i // Composer setup (from project root): vendor/bin/phpcs -i
6. Creating a Code Style Handbook StockSnap
7. Why Code Style Consistency Is Important Easier to maintain & debug Easier to start contributing Easier to comprehend
8. Code Style Documentation Code Smells Code Metrics Best Practices Code Compatibility
9. PHP (+ inc) JS CSS
10. Firkin
11. Required or recommended ? What rules should these comply with ? What code structures do you want to address ?
12. Existing Code Consistency phpcs –p . --standard=Generic,PSR1,PSR2,PEAR,MySource,Squiz,Zend --report-info --extensions=php --ignore=*/vendor/* =./2017029-phpcs-info.txt
13. Creating a PHP Codesniffer Ruleset Adrian
14. How It Works PHP CodeSniffer Coding Standard phpcs phpcbf ruleset sniffs checks + fixers
15. PHPCS Build-in Standards PEAR PSR1 PSR2 Zend MySource PHPCS Squiz
16. Which Standard Reports on What ? phpcs –p . --standard=PSR1 --extensions=php --report-source --report-summary Repeat for PSR2, PEAR, Squiz, Zend
17. Which Rules Are Contained in Each Standard ? phpcs –e --standard=Generic Repeat for PSR1, PSR2, PEAR, Squiz, Zend, MySource
18. Starting a Custom Ruleset <?xml version="1.0"?> <ruleset name="Project/Organisation name"> <description>Some description</description> <file>.</file> <rule ref="...."/> </ruleset> .phpcs.xml.dist
19. Standard.Subset.Sniff.ErrorCode Standard.Subset.Sniff.ErrorCode Standard.Subset.Sniff.ErrorCode Standard.Subset.Sniff.ErrorCode
20. Standard.Subset.Sniff.ErrorCode Include: <rule ref="…" /> Exclude: <exclude name="…" /> ~~~~~~~~
21. <?xml version="1.0"?> <ruleset name="MyProject"> <rule ref="PSR1" /> <rule ref="PSR2"> <exclude name="Generic.Files.LineEndings" /> </rule> <config name="testVersion" value="5.1-99.0"/> <rule ref="PHPCompatibility"> <exclude name="PHPCompatibility.PHP. DeprecatedIniDirectives.safe_modeRemoved"> </rule> </ruleset> Standard A Standard B
22. Adding More Standards phpcs --config-set installed_paths /path/to/dir/above/standard phpcs --config-show phpcs --config-set installed_paths /path/to/dir/above/standard1,/path/to/dir/above/standard2
23. Finding Suitable Sniff(s) <?php // Target style – shouldn't give errors. if (true === $something) { } // Wrong style. if( $something==true ) { } phpcs –p –s ./test.php –extensions=php –-standard=Generic,PSR1,PSR2,PEAR,Squiz,MySource,Zend
24. Comparing Behaviour of Sniffs phpcs –p –s ./test-function-declaration.php --extensions=php --standard=PEAR --sniffs=PEAR.Functions.FunctionDeclaration vs phpcs –p –s ./test-function-declaration.php --extensions=php --standard=Squiz --sniffs=Squiz.Functions.FunctionDeclaration
25. https://github.com/squizlabs/PHP_CodeSniffer/wiki/ Customisable-Sniff-Properties
26. Standard.Subset.Sniff.ErrorCode Include: <rule ref="…" /> Exclude: <exclude name="…" /> ~~~~~~~~
27. MarcoMaru
28. Fine Tuning Your Ruleset falconp4
29. Run PHP Codesniffer phpcs --report-full --report-source --report-summary =./2017029-phpcs-full.txt =./2017029-phpcs-source.txt =./2017029-phpcs-summary.txt
30. <?xml version="1.0"?> <ruleset name="MyProject"> <exclude-pattern>*/vendor/*</exclude-pattern> <rule ref="PSR1" /> <rule ref="PSR2"> <exclude name="Generic.Files.LineEndings" /> </rule> <config name="testVersion" value="5.1-99.0"/> <rule ref="PHPCompatibility"> <exclude name="PHPCompatibility.PHP. DeprecatedIniDirectives.safe_modeRemoved"> </rule> <rule ref="PHPCompatibility.PHP.Deprecated IniDirectives.magic_quotes_runtimeRemoved"> <exclude-pattern>*/MyFile\.php</exclude-pattern> </rule> <rule ref="Generic.Metrics.NestingLevelSniff" /> <rule ref="PEAR.Commenting" /> </ruleset> Standard A Standard B
31. Customizing Messages <?xml version="1.0"?> <ruleset name="MyProject"> <rule ref="Generic.Commenting.Todo.CommentFound"> <message>Please review this TODO comment: %s</message> <severity>8</severity> <type>error</type> </rule> </ruleset>
32. Customizing Sniffs <?xml version="1.0"?> <ruleset name="MyProject"> <rule ref="Generic.Files.LineLength"> <properties> <property name="lineLimit" value="90"/> <property name="absoluteLineLimit" value="100"/> </properties> </rule> </ruleset>
33. Customizing Sniffs <?xml version="1.0"?> <ruleset name="MyProject"> <rule ref="Generic.PHP.ForbiddenFunctions"> <properties> <property name="forbiddenFunctions" type="array" value="delete=>unset,print=>echo, create_function=>null" /> </properties> </rule> </ruleset>
34. Marnhe du Plooy
35. Auto-Fixing Ulrike Mai
36. Running the Fixer phpcbf
37. PHPCS vs PHPCBF phpcs-only="true" vs phpcbf-only="true"
38. Handling Rule Exceptions // @codingStandardsIgnoreLine <code line to be ignored> // @codingStandardsIgnoreStart ... <code> ... // @codingStandardsIgnoreEnd // @codingStandardsIgnoreFile
39. Review, Fine Tune & Review Some More Manual Fixes
40. Ryan McGuire
41. mzsu Keeping the Code base Clean
42. Running PHPCS via Travis before_install: - export PHPCS_DIR=/tmp/phpcs - git clone -b master --depth 1 https://github.com/squizlabs/PHP_CodeSniffer.git $PHPCS_DIR script: - $PHPCS_DIR/bin/phpcs . –-standard=phpcs.xml --runtime-set ignore_warnings_on_exit 1
43. Only run PHPCS once per build.
44. Running PHPCS Selectively matrix: include: ... - php: '7.1' env: SNIFF=1 before_install: ... - if [[ "$SNIFF" == "1" ]]; then git clone -b master --depth 1 https://github.com/squizlabs/PHP_CodeSniffer.git $PHPCS_DIR; fi script: - if [[ "$SNIFF" == "1" ]]; then $PHPCS_DIR/bin/phpcs; fi
45. Lessons Learned
46. Thanks! Slides: https://speakerdeck.com/jrf Code: https://github.com/jrfnl/ make-phpcs-work-for-you Docs: https://github.com/squizlabs/ PHP_Codesniffer/wiki Feedback: https://joind.in/22139