README

silverorange PHP项目的编码标准。这些标准与PHPCS工具一起使用。

按项目使用

推荐使用按项目配置而不是全局配置，但这需要在项目中添加支持。要为项目使用这些规则

1. 使用composer将其作为require-dev依赖项安装

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

2. 添加post-install-cmd和post-update-cmd以将编码标准注册到phpcs

需要安装和更新后都执行，因为不带锁文件的composer install不会执行post-install-cmd脚本。

{
  "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. 创建一个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. 创建一个用于检查项目的composer脚本

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

5. 添加一个Jenkins管道阶段以自动检查文件

代码检查管道阶段应添加到其他管道阶段之前，以确保如果代码检查失败则它们不会运行。有关向现有管道添加阶段的帮助或创建新管道的帮助，请参阅Jenkins Pipeline手册。

对于新包

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

对于旧包

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

全局使用

如果没有可用的按项目配置，则可以将SilverorangeLegacy标准设置为默认使用。

1. 全局安装标准

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

2. 使用PHP Code Sniffer注册标准

您可以使用逗号分隔多个路径。

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

3. 设置全局phpcs标准

$ phpcs --config-set default_standard SilverorangeLegacy

现在使用不带其他参数的phpcs将使用SilverorangeLegacy标准。

标准

提供了一些标准

SilverorangeLegacy

用于检查旧包的整个项目的代码。它省略了一些我们希望在旧包中为编写的新代码使用的规则，以避免出错。不建议为新项目使用此标准。

旧标准文档存在。

SilverorangeTransitional

用于作为提交后钩子或CI测试。这确保了所有添加到旧包中的新代码都遵循旧指南中的最佳实践。这包括整个项目不会通过但应通过所有新拉取请求中修改的文件的规则。

SilverorangeTransitionalPrettier

基于PSR-2标准，但更新以支持Prettier代码自动格式化。PSR-2的PSR-4自动加载规则被放宽，以便我们的旧代码符合规则集。此标准应用于所有旧silverorange PHP包。

Silverorange

基于PSR-2。PSR-2基于PSR-1，并包括所有规则。Silverorange标准扩展PSR-2以添加禁止使用的函数。

对于自动加载类，项目必须遵循PSR-4规范。这允许高效地自动加载，并促进使用命名空间组织代码。

SilverorangePrettier

基于Silverorange标准，但更新以支持Prettier代码自动格式化。除了PSR-2规则外，还包括额外的检查，以促进代码质量和一致性。这个标准应适用于所有新的silverorange PHP包。

SilverorangePEAR

基于PEAR标准，但更新为不需要方法和类文档。不应用于新包。

Sublime Setup

如果您正在使用Sublime Text

1. 按照此处所述设置Sublime Linter与PHPCS。
2. 在Sublime Linter设置中，确保您有以下设置（不要删除其他设置）

   {
     "user": {
       "linters": {
         "phpcs": {
           "@disable": false,
           "args": []
         }
       }
     }
   }

3. 在项目根目录中创建一个Sublime项目。
4. 将以下内容添加到Sublime项目设置中

   {
     "SublimeLinter": {
       "linters": {
         "phpcs": {
           "phpcs_executable_path": "{project}/vendor/bin/phpcs"
         }
       }
     }
   }

这将允许您使用不同的规则集处理不同的项目。

Atom Setup

如果您正在使用Atom

1. 按照此处所述设置linter-phpcs。
2. 打开linter-phpcs的包设置，将Coding Standard Or Config File设置为SilverorangeLegacy或您正在使用的任何当前编码标准。还将Tab Width字段设置为4。