Skip to content

New feature: PHPCSDev ruleset #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 14, 2019
Merged

New feature: PHPCSDev ruleset #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
31ed3d6
:sparkles: New feature: PHPCSDev ruleset
jrfnl Aug 14, 2019
85382c0
:wrench: QA: add code style check for the code in this repo
jrfnl Aug 14, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitattributes
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
/.gitattributes export-ignore
/.gitignore export-ignore
/.travis.yml export-ignore
/phpcs.xml.dist export-ignore

#
# Auto detect text files and perform LF normalization
Expand Down
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,4 @@
vendor/
composer.lock
.phpcs.xml
phpcs.xml
27 changes: 27 additions & 0 deletions .travis.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ language: php

## Cache composer and apt downloads.
cache:
apt: true
directories:
# Cache directory for older Composer versions.
- $HOME/.composer/cache/files
Expand All @@ -14,15 +15,41 @@ php:
- 5.4
- 7.3

# Define the stages used.
stages:
- name: sniff
- name: test

jobs:
fast_finish: true
include:
#### SNIFF STAGE ####
- stage: sniff
php: 7.3
addons:
apt:
packages:
- libxml2-utils
script:
# Check the code style of the code base.
- composer check-cs

# Validate the xml file.
# @link http://xmlsoft.org/xmllint.html
- xmllint --noout --schema ./vendor/squizlabs/php_codesniffer/phpcs.xsd ./PHPCSDev/ruleset.xml

# Check the code-style consistency of the xml files.
- diff -B ./PHPCSDev/ruleset.xml <(xmllint --format "./PHPCSDev/ruleset.xml")


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

- export XMLLINT_INDENT=" "

# --prefer-dist will allow for optimal use of the travis caching ability.
# The Composer PHPCS plugin takes care of setting the installed_paths for PHPCS.
- composer install --prefer-dist --no-suggest


Expand Down
171 changes: 171 additions & 0 deletions PHPCSDev/ruleset.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,171 @@
<?xml version="1.0"?>
<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">

<description>A PSR-2 based standard for use by sniff developers to check the code style of external PHPCS standards</description>

<!--
####################################################################
PHP: Check PHP cross version compatibility.
For optimal results, the custom project ruleset should set the testVersion
config variable.
For compatibility with the PHP version supported by PHP_CodeSniffer 3.0+,
this would typically be set like: <config name="testVersion" value="5.4-"/>.
####################################################################
-->
<rule ref="PHPCompatibility">
<exclude name="PHPCompatibility.Constants.NewConstants.t_finallyFound"/>
<exclude name="PHPCompatibility.Constants.NewConstants.t_yieldFound"/>
<exclude name="PHPCompatibility.Constants.NewConstants.t_ellipsisFound"/>
<exclude name="PHPCompatibility.Constants.NewConstants.t_powFound"/>
<exclude name="PHPCompatibility.Constants.NewConstants.t_pow_equalFound"/>
<exclude name="PHPCompatibility.Constants.NewConstants.t_spaceshipFound"/>
<exclude name="PHPCompatibility.Constants.NewConstants.t_coalesceFound"/>
<exclude name="PHPCompatibility.Constants.NewConstants.t_coalesce_equalFound"/>
<exclude name="PHPCompatibility.Constants.NewConstants.t_yield_fromFound"/>
</rule>


<!--
####################################################################
Code style: Check style for compliance with PSR2.
####################################################################
-->
<rule ref="PSR2"/>


<!--
####################################################################
Code style: Naming Conventions.
####################################################################
-->

<!-- Check that variable names are in camelCase. -->
<rule ref="Squiz.NamingConventions.ValidVariableName">
<exclude name="Squiz.NamingConventions.ValidVariableName.PrivateNoUnderscore"/>
</rule>

<!-- Check that function and method names are in camelCase. -->
<rule ref="Generic.NamingConventions.CamelCapsFunctionName">
<properties>
<!-- Allow for two adjacent capital letters for acronyms. -->
<property name="strict" value="false"/>
</properties>
</rule>


<!--
####################################################################
Code style: Various other additions.
####################################################################
-->

<!-- PSR2 appears to ignore blank lines for superfluous whitespace and in several other places. Let's fix that. -->
<rule ref="Squiz.WhiteSpace.SuperfluousWhitespace">
<properties>
<property name="ignoreBlankLines" value="false"/>
</properties>
</rule>
<rule ref="Squiz.WhiteSpace.SuperfluousWhitespace.StartFile">
<severity>5</severity>
</rule>
<rule ref="Squiz.WhiteSpace.SuperfluousWhitespace.EndFile">
<severity>5</severity>
</rule>
<rule ref="Squiz.WhiteSpace.SuperfluousWhitespace.EmptyLines">
<severity>5</severity>
</rule>

<!-- Ensure exactly one blank line before each property declaration. -->
<rule ref="Squiz.WhiteSpace.MemberVarSpacing"/>

<!-- Ensure exactly one blank line before each function declaration, two blank lines
before the first function and 0 after the last. -->
<rule ref="Squiz.WhiteSpace.FunctionSpacing">
<properties>
<property name="spacing" value="1"/>
<property name="spacingBeforeFirst" value="1"/>
<property name="spacingAfterLast" value="0"/>
</properties>
</rule>

<rule ref="Generic.PHP.LowerCaseType"/>
<rule ref="Generic.WhiteSpace.ArbitraryParenthesesSpacing"/>
<rule ref="PSR12.Classes.ClassInstantiation"/>
<rule ref="PSR12.Keywords.ShortFormTypeKeywords"/>
<rule ref="PSR12.Operators.OperatorSpacing"/>

<!-- Align the equal operator in assignment blocks. -->
<rule ref="Generic.Formatting.MultipleStatementAlignment">
<properties>
<property name="maxPadding" value="25"/>
</properties>
</rule>

<rule ref="PEAR.Files.IncludingFile"/>
<rule ref="PEAR.Files.IncludingFile.UseInclude">
<severity>0</severity>
</rule>
<rule ref="PEAR.Files.IncludingFile.UseIncludeOnce">
<severity>0</severity>
</rule>


<!--
####################################################################
Code style: Array declarations.
####################################################################
-->

<!-- Use normalized array indentation. -->
<rule ref="Generic.Arrays.ArrayIndent"/>
<rule ref="Squiz.Arrays.ArrayDeclaration"/>

<!-- Ignoring the Squiz indentation rules as normalized arrays are preferred. -->
<rule ref="Squiz.Arrays.ArrayDeclaration.KeyNotAligned">
<severity>0</severity>
</rule>
<rule ref="Squiz.Arrays.ArrayDeclaration.ValueNotAligned">
<severity>0</severity>
</rule>
<rule ref="Squiz.Arrays.ArrayDeclaration.CloseBraceNotAligned">
<severity>0</severity>
</rule>

<!-- Single and multi-line arrays are both allowed. -->
<rule ref="Squiz.Arrays.ArrayDeclaration.SingleLineNotAllowed">
<severity>0</severity>
</rule>
<rule ref="Squiz.Arrays.ArrayDeclaration.MultiLineNotAllowed">
<severity>0</severity>
</rule>


<!--
####################################################################
Docs: Verify the documentation.
####################################################################
-->

<rule ref="Generic.Commenting.DocComment">
<!-- Having a @see or @internal tag before the @param tags is fine. -->
<exclude name="Generic.Commenting.DocComment.ParamNotFirst"/>
</rule>

<rule ref="PEAR.Commenting">
<!-- Exclude PEAR specific tag requirements. -->
<exclude name="PEAR.Commenting.FileComment.MissingVersion"/>
<exclude name="PEAR.Commenting.FileComment.MissingAuthorTag"/>
<exclude name="PEAR.Commenting.FileComment.MissingCategoryTag"/>
<exclude name="PEAR.Commenting.FileComment.MissingLicenseTag"/>
<exclude name="PEAR.Commenting.FileComment.MissingLinkTag"/>
<exclude name="PEAR.Commenting.ClassComment.MissingAuthorTag"/>
<exclude name="PEAR.Commenting.ClassComment.MissingCategoryTag"/>
<exclude name="PEAR.Commenting.ClassComment.MissingLicenseTag"/>
<exclude name="PEAR.Commenting.ClassComment.MissingLinkTag"/>
<exclude name="PEAR.Commenting.ClassComment.MissingPackageTag"/>

<!-- Having a @see or @internal tag before the @category tag is fine. -->
<exclude name="PEAR.Commenting.ClassComment.CategoryTagOrder"/>
</rule>

</ruleset>
36 changes: 36 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ This is a set of tools to aid developers of sniffs for [PHP CodeSniffer](https:/
+ [Composer Project-based Installation](#composer-project-based-installation)
+ [Composer Global Installation](#composer-global-installation)
+ [Stand-alone Installation](#stand-alone-installation)
* [Features](#features)
+ [PHPCSDev ruleset for sniff repos](#phpcsdev-ruleset-for-sniff-repos)
* [Contributing](#contributing)
* [License](#license)

Expand Down Expand Up @@ -59,6 +61,40 @@ composer global require phpcsstandards/phpcsdevtools:^1.0
```


Features
------------------------------

### PHPCSDev ruleset for sniff repos

Once this project is installed, you will see a new `PHPCSDev` ruleset in the list of installed standards when you run `phpcs -i`.

**Important: This ruleset currently requires PHP_CodeSniffer >= `3.4.0+`.**

> As sniffs developers will mostly work with the latest version of PHP_CodeSniffer, this shouldn't cause any problems.
>
> Similarly, the CS check in automated CI runs should normally be run on a high PHPCS version for the best results.

The `PHPCSDev` standard can be used 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 your code against the following:
* Compliance with [PSR-2](https://www.php-fig.org/psr/psr-2/).
* Use of camelCase 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](https://github.com/squizlabs/PHP_CodeSniffer/issues/2197) [to overrule](https://github.com/squizlabs/PHP_CodeSniffer/issues/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.

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.


Contributing
-------
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.
Expand Down
7 changes: 7 additions & 0 deletions composer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
"require" : {
"php" : ">=5.4",
"squizlabs/php_codesniffer" : "^3.0.2",
"phpcompatibility/php-compatibility" : "^9.0.0",
"dealerdirect/phpcodesniffer-composer-installer" : "^0.5"
},
"require-dev" : {
Expand All @@ -32,6 +33,12 @@
"scripts" : {
"lint": [
"@php ./vendor/jakub-onderka/php-parallel-lint/parallel-lint . -e php --exclude vendor"
],
"check-cs": [
"@php ./vendor/squizlabs/php_codesniffer/bin/phpcs"
],
"fix-cs": [
"@php ./vendor/squizlabs/php_codesniffer/bin/phpcbf"
]
}
}
43 changes: 43 additions & 0 deletions phpcs.xml.dist
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
<?xml version="1.0"?>
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="Coding Standard for PHPCSDevTools" xsi:noNamespaceSchemaLocation="./vendor/squizlabs/php_codesniffer/phpcs.xsd">
<description>Check the code of the PHPCSDevTools standard itself.</description>

<!--
#############################################################################
COMMAND LINE ARGUMENTS
https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-ruleset.xml
#############################################################################
-->

<file>.</file>

<!-- Exclude Composer vendor directory. -->
<exclude-pattern>*/vendor/*</exclude-pattern>

<!-- Only check PHP files. -->
<arg name="extensions" value="php"/>

<!-- Show progress, show the error codes for each message (source). -->
<arg value="ps"/>

<!-- Strip the filepaths down to the relevant bit. -->
<arg name="basepath" value="./"/>

<!-- Check up to 8 files simultaneously. -->
<arg name="parallel" value="8"/>

<!--
#############################################################################
USE THE PHPCSDev RULESET
#############################################################################
-->

<rule ref="PHPCSDev"/>

<!-- Set minimum PHP version supported to PHP 5.4. -->
<config name="testVersion" value="5.4-"/>

<!-- Enforce short arrays. -->
<rule ref="Generic.Arrays.DisallowLongArraySyntax"/>

</ruleset>