Skip to content

Commit bfc4899

Browse files
jrfnljrfnl
authored
Merge pull request #1 from PHPCSStandards/feature/add-phpcsdev-ruleset
New feature: PHPCSDev ruleset
2 parents 06eb4dd + 85382c0 commit bfc4899

7 files changed

Lines changed: 287 additions & 0 deletions

File tree

‎.gitattributes‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
/.gitattributes export-ignore
99
/.gitignore export-ignore
1010
/.travis.yml export-ignore
11+
/phpcs.xml.dist export-ignore
1112

1213
#
1314
# Auto detect text files and perform LF normalization

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
11
vendor/
22
composer.lock
3+
.phpcs.xml
4+
phpcs.xml

‎.travis.yml‎

Lines changed: 27 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,15 +15,41 @@ 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+
# Check the code style of the code base.
35+
- composer check-cs
36+
37+
# Validate the xml file.
38+
# @link http://xmlsoft.org/xmllint.html
39+
- xmllint --noout --schema ./vendor/squizlabs/php_codesniffer/phpcs.xsd ./PHPCSDev/ruleset.xml
40+
41+
# Check the code-style consistency of the xml files.
42+
- diff -B ./PHPCSDev/ruleset.xml <(xmllint --format "./PHPCSDev/ruleset.xml")
1943

2044

2145
before_install:
2246
# Speed up build time by disabling Xdebug when its not needed.
2347
- phpenv config-rm xdebug.ini || echo 'No xdebug config.'
2448

49+
- export XMLLINT_INDENT=" "
50+
2551
# --prefer-dist will allow for optimal use of the travis caching ability.
52+
# The Composer PHPCS plugin takes care of setting the installed_paths for PHPCS.
2653
- composer install --prefer-dist --no-suggest
2754

2855

‎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: 36 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,40 @@ 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+
For an example project-based ruleset using the `PHCPSDev` standard, have a look at the [`phpcs.xml.dist` file](https://github.com/PHPCSStandards/PHPCSDevTools/blob/develop/phpcs.xml.dist) in this repo.
96+
97+
6298
Contributing
6399
-------
64100
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: 7 additions & 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" : {
@@ -32,6 +33,12 @@
3233
"scripts" : {
3334
"lint": [
3435
"@php ./vendor/jakub-onderka/php-parallel-lint/parallel-lint . -e php --exclude vendor"
36+
],
37+
"check-cs": [
38+
"@php ./vendor/squizlabs/php_codesniffer/bin/phpcs"
39+
],
40+
"fix-cs": [
41+
"@php ./vendor/squizlabs/php_codesniffer/bin/phpcbf"
3542
]
3643
}
3744
}

‎phpcs.xml.dist‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
<?xml version="1.0"?>
2+
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="Coding Standard for PHPCSDevTools" xsi:noNamespaceSchemaLocation="./vendor/squizlabs/php_codesniffer/phpcs.xsd">
3+
<description>Check the code of the PHPCSDevTools standard itself.</description>
4+
5+
<!--
6+
#############################################################################
7+
COMMAND LINE ARGUMENTS
8+
https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-ruleset.xml
9+
#############################################################################
10+
-->
11+
12+
<file>.</file>
13+
14+
<!-- Exclude Composer vendor directory. -->
15+
<exclude-pattern>*/vendor/*</exclude-pattern>
16+
17+
<!-- Only check PHP files. -->
18+
<arg name="extensions" value="php"/>
19+
20+
<!-- Show progress, show the error codes for each message (source). -->
21+
<arg value="ps"/>
22+
23+
<!-- Strip the filepaths down to the relevant bit. -->
24+
<arg name="basepath" value="./"/>
25+
26+
<!-- Check up to 8 files simultaneously. -->
27+
<arg name="parallel" value="8"/>
28+
29+
<!--
30+
#############################################################################
31+
USE THE PHPCSDev RULESET
32+
#############################################################################
33+
-->
34+
35+
<rule ref="PHPCSDev"/>
36+
37+
<!-- Set minimum PHP version supported to PHP 5.4. -->
38+
<config name="testVersion" value="5.4-"/>
39+
40+
<!-- Enforce short arrays. -->
41+
<rule ref="Generic.Arrays.DisallowLongArraySyntax"/>
42+
43+
</ruleset>

0 commit comments

Comments
 (0)