silverorange Coding Standards

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:

1. Set up Sublime Linter with PHPCS as described here.
2. In the Sublime Linter settings, make sure you have the following settings (do not remove the other settings):

   {
     "user": {
       "linters": {
         "phpcs": {
           "@disable": false,
           "args": []
         }
       }
     }
   }
3. Create a Sublime project in the project root.
4. 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:

1. Set up linter-phpcs as described here.
2. 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.