Skip to content

Commit 31ed3d6

Browse files
jrfnljrfnl
committed
✨ New feature: PHPCSDev ruleset
This adds a new external PHPCS standard called `PHPCSDev` for use by sniff developers to check the code style of their sniff repo code. Often, sniff repos will use the code style of the standard they are adding. However, not all sniff repos are actually about code style. So for those repos which need a basic standard which will still keep their code-base consistent, this standard should be useful. The standard checks the following: * Compliance with PSR-2. * Use of camelCaps variable and function names. * Use of normalized arrays. * All files, classes, functions and properties are documented with a docblock and contain the minimally needed information. * A small number of arbitrary additional code style checks. * PHP cross-version compatibility, while allowing for the tokens back-filled by PHPCS itself. **Note**: for optimal results, the project custom ruleset should set the `testVersion` config variable. This is not done by default as config variables are currently difficult to overrule. Refs: - squizlabs/PHP_CodeSniffer#2197 - squizlabs/PHP_CodeSniffer#1821 The ruleset can be used like any other ruleset and specific sniffs and settings can be added to or overruled from a custom project based ruleset. Includes adding QA checks for this ruleset to the Travis script.
1 parent 06eb4dd commit 31ed3d6

4 files changed

Lines changed: 229 additions & 0 deletions

File tree

‎.travis.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ language: php
44

55
## Cache composer and apt downloads.
66
cache:
7+
apt: true
78
directories:
89
# Cache directory for older Composer versions.
910
- $HOME/.composer/cache/files
@@ -14,14 +15,36 @@ php:
1415
- 5.4
1516
- 7.3
1617

18+
# Define the stages used.
19+
stages:
20+
- name: sniff
21+
- name: test
22+
1723
jobs:
1824
fast_finish: true
25+
include:
26+
#### SNIFF STAGE ####
27+
- stage: sniff
28+
php: 7.3
29+
addons:
30+
apt:
31+
packages:
32+
- libxml2-utils
33+
script:
34+
# Validate the xml file.
35+
# @link http://xmlsoft.org/xmllint.html
36+
- xmllint --noout --schema ./vendor/squizlabs/php_codesniffer/phpcs.xsd ./PHPCSDev/ruleset.xml
37+
38+
# Check the code-style consistency of the xml files.
39+
- diff -B ./PHPCSDev/ruleset.xml <(xmllint --format "./PHPCSDev/ruleset.xml")
1940

2041

2142
before_install:
2243
# Speed up build time by disabling Xdebug when its not needed.
2344
- phpenv config-rm xdebug.ini || echo 'No xdebug config.'
2445

46+
- export XMLLINT_INDENT=" "
47+
2548
# --prefer-dist will allow for optimal use of the travis caching ability.
2649
- composer install --prefer-dist --no-suggest
2750

‎PHPCSDev/ruleset.xml‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
<?xml version="1.0"?>
2+
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="PHPCSDev" namespace="PHPCSStandards\PHPCSDev" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/squizlabs/PHP_CodeSniffer/master/phpcs.xsd">
3+
4+
<description>A PSR-2 based standard for use by sniff developers to check the code style of external PHPCS standards</description>
5+
6+
<!--
7+
####################################################################
8+
PHP: Check PHP cross version compatibility.
9+
For optimal results, the custom project ruleset should set the testVersion
10+
config variable.
11+
For compatibility with the PHP version supported by PHP_CodeSniffer 3.0+,
12+
this would typically be set like: <config name="testVersion" value="5.4-"/>.
13+
####################################################################
14+
-->
15+
<rule ref="PHPCompatibility">
16+
<exclude name="PHPCompatibility.Constants.NewConstants.t_finallyFound"/>
17+
<exclude name="PHPCompatibility.Constants.NewConstants.t_yieldFound"/>
18+
<exclude name="PHPCompatibility.Constants.NewConstants.t_ellipsisFound"/>
19+
<exclude name="PHPCompatibility.Constants.NewConstants.t_powFound"/>
20+
<exclude name="PHPCompatibility.Constants.NewConstants.t_pow_equalFound"/>
21+
<exclude name="PHPCompatibility.Constants.NewConstants.t_spaceshipFound"/>
22+
<exclude name="PHPCompatibility.Constants.NewConstants.t_coalesceFound"/>
23+
<exclude name="PHPCompatibility.Constants.NewConstants.t_coalesce_equalFound"/>
24+
<exclude name="PHPCompatibility.Constants.NewConstants.t_yield_fromFound"/>
25+
</rule>
26+
27+
28+
<!--
29+
####################################################################
30+
Code style: Check style for compliance with PSR2.
31+
####################################################################
32+
-->
33+
<rule ref="PSR2"/>
34+
35+
36+
<!--
37+
####################################################################
38+
Code style: Naming Conventions.
39+
####################################################################
40+
-->
41+
42+
<!-- Check that variable names are in camelCase. -->
43+
<rule ref="Squiz.NamingConventions.ValidVariableName">
44+
<exclude name="Squiz.NamingConventions.ValidVariableName.PrivateNoUnderscore"/>
45+
</rule>
46+
47+
<!-- Check that function and method names are in camelCase. -->
48+
<rule ref="Generic.NamingConventions.CamelCapsFunctionName">
49+
<properties>
50+
<!-- Allow for two adjacent capital letters for acronyms. -->
51+
<property name="strict" value="false"/>
52+
</properties>
53+
</rule>
54+
55+
56+
<!--
57+
####################################################################
58+
Code style: Various other additions.
59+
####################################################################
60+
-->
61+
62+
<!-- PSR2 appears to ignore blank lines for superfluous whitespace and in several other places. Let's fix that. -->
63+
<rule ref="Squiz.WhiteSpace.SuperfluousWhitespace">
64+
<properties>
65+
<property name="ignoreBlankLines" value="false"/>
66+
</properties>
67+
</rule>
68+
<rule ref="Squiz.WhiteSpace.SuperfluousWhitespace.StartFile">
69+
<severity>5</severity>
70+
</rule>
71+
<rule ref="Squiz.WhiteSpace.SuperfluousWhitespace.EndFile">
72+
<severity>5</severity>
73+
</rule>
74+
<rule ref="Squiz.WhiteSpace.SuperfluousWhitespace.EmptyLines">
75+
<severity>5</severity>
76+
</rule>
77+
78+
<!-- Ensure exactly one blank line before each property declaration. -->
79+
<rule ref="Squiz.WhiteSpace.MemberVarSpacing"/>
80+
81+
<!-- Ensure exactly one blank line before each function declaration, two blank lines
82+
before the first function and 0 after the last. -->
83+
<rule ref="Squiz.WhiteSpace.FunctionSpacing">
84+
<properties>
85+
<property name="spacing" value="1"/>
86+
<property name="spacingBeforeFirst" value="1"/>
87+
<property name="spacingAfterLast" value="0"/>
88+
</properties>
89+
</rule>
90+
91+
<rule ref="Generic.PHP.LowerCaseType"/>
92+
<rule ref="Generic.WhiteSpace.ArbitraryParenthesesSpacing"/>
93+
<rule ref="PSR12.Classes.ClassInstantiation"/>
94+
<rule ref="PSR12.Keywords.ShortFormTypeKeywords"/>
95+
<rule ref="PSR12.Operators.OperatorSpacing"/>
96+
97+
<!-- Align the equal operator in assignment blocks. -->
98+
<rule ref="Generic.Formatting.MultipleStatementAlignment">
99+
<properties>
100+
<property name="maxPadding" value="25"/>
101+
</properties>
102+
</rule>
103+
104+
<rule ref="PEAR.Files.IncludingFile"/>
105+
<rule ref="PEAR.Files.IncludingFile.UseInclude">
106+
<severity>0</severity>
107+
</rule>
108+
<rule ref="PEAR.Files.IncludingFile.UseIncludeOnce">
109+
<severity>0</severity>
110+
</rule>
111+
112+
113+
<!--
114+
####################################################################
115+
Code style: Array declarations.
116+
####################################################################
117+
-->
118+
119+
<!-- Use normalized array indentation. -->
120+
<rule ref="Generic.Arrays.ArrayIndent"/>
121+
<rule ref="Squiz.Arrays.ArrayDeclaration"/>
122+
123+
<!-- Ignoring the Squiz indentation rules as normalized arrays are preferred. -->
124+
<rule ref="Squiz.Arrays.ArrayDeclaration.KeyNotAligned">
125+
<severity>0</severity>
126+
</rule>
127+
<rule ref="Squiz.Arrays.ArrayDeclaration.ValueNotAligned">
128+
<severity>0</severity>
129+
</rule>
130+
<rule ref="Squiz.Arrays.ArrayDeclaration.CloseBraceNotAligned">
131+
<severity>0</severity>
132+
</rule>
133+
134+
<!-- Single and multi-line arrays are both allowed. -->
135+
<rule ref="Squiz.Arrays.ArrayDeclaration.SingleLineNotAllowed">
136+
<severity>0</severity>
137+
</rule>
138+
<rule ref="Squiz.Arrays.ArrayDeclaration.MultiLineNotAllowed">
139+
<severity>0</severity>
140+
</rule>
141+
142+
143+
<!--
144+
####################################################################
145+
Docs: Verify the documentation.
146+
####################################################################
147+
-->
148+
149+
<rule ref="Generic.Commenting.DocComment">
150+
<!-- Having a @see or @internal tag before the @param tags is fine. -->
151+
<exclude name="Generic.Commenting.DocComment.ParamNotFirst"/>
152+
</rule>
153+
154+
<rule ref="PEAR.Commenting">
155+
<!-- Exclude PEAR specific tag requirements. -->
156+
<exclude name="PEAR.Commenting.FileComment.MissingVersion"/>
157+
<exclude name="PEAR.Commenting.FileComment.MissingAuthorTag"/>
158+
<exclude name="PEAR.Commenting.FileComment.MissingCategoryTag"/>
159+
<exclude name="PEAR.Commenting.FileComment.MissingLicenseTag"/>
160+
<exclude name="PEAR.Commenting.FileComment.MissingLinkTag"/>
161+
<exclude name="PEAR.Commenting.ClassComment.MissingAuthorTag"/>
162+
<exclude name="PEAR.Commenting.ClassComment.MissingCategoryTag"/>
163+
<exclude name="PEAR.Commenting.ClassComment.MissingLicenseTag"/>
164+
<exclude name="PEAR.Commenting.ClassComment.MissingLinkTag"/>
165+
<exclude name="PEAR.Commenting.ClassComment.MissingPackageTag"/>
166+
167+
<!-- Having a @see or @internal tag before the @category tag is fine. -->
168+
<exclude name="PEAR.Commenting.ClassComment.CategoryTagOrder"/>
169+
</rule>
170+
171+
</ruleset>

‎README.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ This is a set of tools to aid developers of sniffs for [PHP CodeSniffer](https:/
2222
+ [Composer Project-based Installation](#composer-project-based-installation)
2323
+ [Composer Global Installation](#composer-global-installation)
2424
+ [Stand-alone Installation](#stand-alone-installation)
25+
* [Features](#features)
26+
+ [PHPCSDev ruleset for sniff repos](#phpcsdev-ruleset-for-sniff-repos)
2527
* [Contributing](#contributing)
2628
* [License](#license)
2729

@@ -59,6 +61,38 @@ composer global require phpcsstandards/phpcsdevtools:^1.0
5961
```
6062

6163

64+
Features
65+
------------------------------
66+
67+
### PHPCSDev ruleset for sniff repos
68+
69+
Once this project is installed, you will see a new `PHPCSDev` ruleset in the list of installed standards when you run `phpcs -i`.
70+
71+
**Important: This ruleset currently requires PHP_CodeSniffer >= `3.4.0+`.**
72+
73+
> As sniffs developers will mostly work with the latest version of PHP_CodeSniffer, this shouldn't cause any problems.
74+
>
75+
> Similarly, the CS check in automated CI runs should normally be run on a high PHPCS version for the best results.
76+
77+
The `PHPCSDev` standard can be used by sniff developers to check the code style of their sniff repo code.
78+
79+
Often, sniff repos will use the code style of the standard they are adding. However, not all sniff repos are actually about code style.
80+
81+
So for those repos which need a basic standard which will still keep their code-base consistent, this standard should be useful.
82+
83+
The standard checks your code against the following:
84+
* Compliance with [PSR-2](https://www.php-fig.org/psr/psr-2/).
85+
* Use of camelCase variable and function names.
86+
* Use of normalized arrays.
87+
* All files, classes, functions and properties are documented with a docblock and contain the minimally needed information.
88+
* A small number of arbitrary additional code style checks.
89+
* PHP cross-version compatibility, while allowing for the tokens back-filled by PHPCS itself.
90+
Note: for optimal results, the project custom ruleset should set the `testVersion` config variable.
91+
This is not done by default as config variables are currently [difficult](https://github.com/squizlabs/PHP_CodeSniffer/issues/2197) [to overrule](https://github.com/squizlabs/PHP_CodeSniffer/issues/1821).
92+
93+
The ruleset can be used like any other ruleset and specific sniffs and settings can be added to or overruled from a custom project based ruleset.
94+
95+
6296
Contributing
6397
-------
6498
Contributions to this project are welcome. Just clone the repo, branch off from `develop`, make your changes, commit them and send in a pull request.

‎composer.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
"require" : {
2323
"php" : ">=5.4",
2424
"squizlabs/php_codesniffer" : "^3.0.2",
25+
"phpcompatibility/php-compatibility" : "^9.0.0",
2526
"dealerdirect/phpcodesniffer-composer-installer" : "^0.5"
2627
},
2728
"require-dev" : {

0 commit comments

Comments
 (0)