silverorange / coding-standard
silverorange PHP coding standards.
Installs: 4 268
Dependents: 3
Suggesters: 0
Security: 0
Stars: 1
Watchers: 19
Forks: 6
Open Issues: 0
Requires
- squizlabs/php_codesniffer: ^3.2.3
README
Coding standards for silverorange PHP projects. These are standards to be used with the PHPCS tool.
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:
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.
{ "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
<?xml version="1.0"?> <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.
For new packages:
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:
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.
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.
$ 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.
Standards
Several standards are provided:
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.
Documentation exists for the legacy standard.
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.
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.
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.
For autoloading classes, projects must follow PSR-4. This allows efficient auto-loading and promotes organizing code using namespaces.
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.
SilverorangePEAR
Based on PEAR
standard but updated to not require method and class
documentation. This should not be used for new packages.
Sublime Setup
If you are using Sublime Text:
- 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):
{ "user": { "linters": { "phpcs": { "@disable": false, "args": [] } } } }
- Create a Sublime project in the project root.
- Add the following to the Sublime project settings:
{ "SublimeLinter": { "linters": { "phpcs": { "phpcs_executable_path": "{project}/vendor/bin/phpcs" } } } }
This will allow you to use different rulesets with different projects.
Atom Setup
If you are using Atom:
- Set up linter-phpcs as described here.
- Open the package settings for linter-phpcs and set
Coding Standard Or Config File
toSilverorangeLegacy
or whichever current coding standard you are using. Also set theTab Width
field to4
.