silverorange Coding Standards
, (*1)
Coding standards for silverorange PHP projects. These are standards to be used
with the PHPCS tool., (*2)
Per-Project Usage
per-project configuration is preferred over global configuration but does
require support to be added to the project. To use these rules for a project:, (*3)
1. install as a require-dev dependency using composer
$ composer require --dev silverorange/coding-standard squizlabs/php_codesniffer
2. add a post-install-cmd and post-update-cmd to register the coding standard with phpcs
Post install and post update are both required because composer install
without a lock file will not execute the post-install-cmd script., (*4)
{
"scripts": {
"post-install-cmd": "./vendor/bin/phpcs --config-set installed_paths vendor/silverorange/coding-standard/src",
"post-update-cmd": "./vendor/bin/phpcs --config-set installed_paths vendor/silverorange/coding-standard/src"
}
}
3. create a phpcs.xml
<ruleset name="MyProjectName">
<description>A custom coding standard.</description>
<arg name="colors"/>
<arg name="tab-width" value="4"/>
<arg name="extensions" value="php"/>
<arg name="encoding" value="utf-8"/>
<arg name="warning-severity" value="0"/>
<rule src="SilverorangeLegacy"/>
</ruleset>
4. create a composer script to lint the project
{
"scripts": {
"lint": "./vendor/bin/phpcs"
}
}
5. add a Jenkins pipeline stage to automatically lint files
The code lint pipeline stage should be added before other pipeline stages so
they do not run if the code lint fails. See the
Jenkins Pipeline Manual for help
with adding a stage to an existing pipeline, or for help creating a new
pipeline., (*5)
For new packages:, (*6)
stage('Lint Modified Files') {
when {
not {
branch 'master'
}
}
steps {
sh '''
master_sha=$(git rev-parse origin/master)
newest_sha=$(git rev-parse HEAD)
files=$(git diff --diff-filter=ACRM --name-only $master_sha...$newest_sha)
if [ -n "$files" ]; then
./vendor/bin/phpcs \
--standard=Silverorange \
--tab-width=4 \
--encoding=utf-8 \
--warning-severity=0 \
--extensions=php \
$files
fi
'''
}
}
For legacy packages:, (*7)
stage('Lint Modified Files') {
when {
not {
branch 'master'
}
}
steps {
sh '''
master_sha=$(git rev-parse origin/master)
newest_sha=$(git rev-parse HEAD)
files=$(git diff --diff-filter=ACRM --name-only $master_sha...$newest_sha)
if [ -n "$files" ]; then
./vendor/bin/phpcs \
--standard=SilverorangeTransitional \
--tab-width=4 \
--encoding=utf-8 \
--warning-severity=0 \
--extensions=php \
$files
fi
'''
}
}
Global Usage
The SilverorangeLegacy standard can be set to be used by default if no
per-project configuration is available., (*8)
1. Install standard globally
$ composer global require silverorange/coding-standard:dev-master
2. Register the standard with PHP Code Sniffer
You can use commas to delineate multiple paths., (*9)
$ phpcs --config-set installed_paths ~/.composer/vendor/silverorange/coding-standard/src
3. Set the global phpcs standard
$ phpcs --config-set default_standard SilverorangeLegacy
Now calling phpcs with no additional arguments will use the
SilverorangeLegacy standard., (*10)
Standards
Several standards are provided:, (*11)
SilverorangeLegacy
Intended for linting the entire project for a legacy package. This omits some
rules we'd like to use for new code written for legacy packages in order to
run without error. It is not recommended to use this standard for new projects., (*12)
Documentation exists for the legacy standard., (*13)
SilverorangeTransitional
Intended for use as a post-commit hook or CI test. This ensures all new code
added to legacy packages follows best practices within the legacy guidelines.
This includes rules that will not pass for the entire project, but should pass
for all modified files in a new pull request., (*14)
SilverorangeTransitionalPrettier
Based on PSR-2 standard but updated to
support Prettier code auto-formatting.
The PSR-4 autoloading rules of PSR-2 are relaxed to allow our legacy code to
comply with the ruleset. This standard should be used for all legacy
silverorange PHP packages., (*15)
Silverorange
Based on PSR-2. PSR-2 builds on, and
includes all rules from PSR-1, The
Silverorange standard extends PSR-2 to add forbidden functions., (*16)
For autoloading classes, projects must follow
PSR-4. This allows efficient auto-loading
and promotes organizing code using namespaces., (*17)
SilverorangePrettier
Based on Silverorange standard but updated to support
Prettier code auto-formatting. In
addition to PSR-2 rules, additional checks are included to promote code
quality and consistency. This standard should be used for all new silverorange
PHP packages., (*18)
SilverorangePEAR
Based on PEAR standard but updated to not require method and class
documentation. This should not be used for new packages., (*19)
Sublime Setup
If you are using Sublime Text:, (*20)
- Set up Sublime Linter with PHPCS as described
here.
- In the Sublime Linter settings, make sure you have the following settings
(do not remove the other settings):
json
{
"user": {
"linters": {
"phpcs": {
"@disable": false,
"args": []
}
}
}
}
- Create a Sublime project in the project root.
- Add the following to the Sublime project settings:
json
{
"SublimeLinter": {
"linters": {
"phpcs": {
"phpcs_executable_path": "{project}/vendor/bin/phpcs"
}
}
}
}
This will allow you to use different rulesets with different projects., (*21)
Atom Setup
If you are using Atom:, (*22)
- Set up linter-phpcs as described here.
- Open the package settings for linter-phpcs and set
Coding Standard Or Config File to SilverorangeLegacy or whichever
current coding standard you are using. Also set the Tab Width field to 4.
Wallogit.com
