Coding standards for silverorange PHP projects. These are standards to be used with the PHPCS tool.

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:

$ composer require --dev silverorange/coding-standard squizlabs/php_codesniffer

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"
  }
}

<?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>

{
  "scripts": {
    "lint": "./vendor/bin/phpcs"
  }
}

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
    '''
  }
}

The SilverorangeLegacy standard can be set to be used by default if no per-project configuration is available.

$ composer global require silverorange/coding-standard:dev-master

You can use commas to delineate multiple paths.

$ phpcs --config-set installed_paths ~/.composer/vendor/silverorange/coding-standard/src

$ phpcs --config-set default_standard SilverorangeLegacy

Now calling phpcs with no additional arguments will use the SilverorangeLegacy standard.

Several standards are provided:

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.

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.

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.

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.

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.

Based on PEAR standard but updated to not require method and class documentation. This should not be used for new packages.

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.

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.