Skip to content

Annotated Ruleset

Jump to bottom
Juliette edited this page Oct 28, 2023 · 9 revisions

PHP_CodeSniffer allows developers to design their own coding standards by creating a simple ruleset XML file that both pulls in sniffs from existing standards and customises them for the developer's needs. This XML file can be named anything you like, as long as it has an xml extension and complies to the ruleset.xml format. The file can be stored anywhere, making it perfect for placing under version control with a project's source code and unit tests.

Once created, a ruleset file can be used with the --standard command line argument. In the following example, PHP_CodeSniffer will use the coding standard defined in a custom ruleset file called custom_ruleset.xml:

$ phpcs --standard=/path/to/custom_ruleset.xml test.php

The Annotated Sample File

The following sample file documents the ruleset.xml format and shows you the complete range of features that the format supports. The file is designed for documentation purposes only and is not a working coding standard.

xml version="1.0"?>
<ruleset name="Custom Standard" namespace="MyProject\CS\Standard">

 

 
 <description>A custom coding standarddescription>

 
 <config name="zend_ca_path" value="/path/to/ZendCodeAnalyzer"/>


 <file>./path/to/directoryfile>
 <file>./path/to/file.phpfile>

 
 <exclude-pattern>*/tests/*exclude-pattern>
 <exclude-pattern>*/data/*exclude-pattern>


 <exclude-pattern type="relative">^/tests/*exclude-pattern>
 <exclude-pattern type="relative">^/data/*exclude-pattern>

 
 <arg name="extensions" value="php,inc" />
 <arg name="report" value="summary"/>
 <arg name="colors"/>
 <arg value="sp"/>

 
 <ini name="memory_limit" value="64M"/>

 
 <autoload>/path/to/autoload.phpautoload>
 <autoload>/path/to/other/autoload.phpautoload>
 <autoload>./autoload.phpautoload>

 
 <rule ref="PEAR"/>

 
 <rule ref="/home/username/standards/mystandard"/>

 
 <rule ref="/home/username/standards/custom.xml"/>

 
 <rule ref="./standards/mystandard"/>
 <rule ref="../username/custom.xml"/>

 
 <rule ref="Squiz">
  <exclude name="Squiz.PHP.CommentedOutCode"/>
 rule>

 
 <rule ref="Squiz">
  <exclude name="Squiz.Strings.DoubleQuoteUsage.ContainsVar"/>
 rule>

 
 <rule ref="Squiz">
  <exclude name="Squiz.PHP"/>
 rule>


 <rule ref="Squiz">
  <exclude name="Generic"/>
 rule>

 
 <rule ref="Generic.CodeAnalysis.UnusedFunctionParameter"/>
 <rule ref="Generic.Commenting.Todo"/>
 <rule ref="Generic.ControlStructures.InlineControlStructure"/>

 
 <rule ref="/path/to/standards/Generic/Sniffs/Commenting/TodoSniff.php"/>
 <rule ref="../Generic/Sniffs/ControlStructures/InlineControlStructureSniff.php"/>

 
 <rule ref="Generic.Commenting.Todo.TaskFound">
  <message>Please review this TODO comment: %smessage>
  <severity>3severity>
 rule>

 
 <rule ref="Generic.Commenting.Todo.CommentFound">
  <type>errortype>
 rule>
 <rule ref="Squiz.Strings.DoubleQuoteUsage.ContainsVar">
  <type>warningtype>
 rule>

 
 <rule ref="Generic.Formatting.MultipleStatementAlignment">
  <type>errortype>
 rule>
 <rule ref="Squiz.Strings">
  <type>warningtype>
 rule>
 <rule ref="PSR12">
  <type>warningtype>
 rule>

 
 <rule ref="Generic.Files.LineLength.MaxExceeded">
  <message>Line contains %2$s chars, which is more than the limit of %1$smessage>
 rule>
 <rule ref="Generic.Files.LineLength.TooLong">
  <message>Line longer than %s characters; contains %s charactersmessage>
 rule>

 
 <rule ref="Generic.Files.LineLength">
  <properties>
   <property name="lineLimit" value="90"/>
   <property name="absoluteLineLimit" value="100"/>
  properties>
 rule>

 
 <rule ref="Generic.Files.LineEndings">
  <properties>
   <property name="eolChar" value="\r\n"/>
  properties>
 rule>

 
 <rule ref="Generic.Formatting.MultipleStatementAlignment">
  <properties>
   <property name="maxPadding" value="8"/>
   <property name="ignoreMultiLine" value="true"/>
  properties>
 rule>
 

 <rule ref="Generic.PHP.ForbiddenFunctions">
  <properties>
   <property name="forbiddenFunctions" type="array">
    <element key="delete" value="unset"/>
    <element key="print" value="echo"/>
    <element key="create_function" value="null"/>
   property>
  properties>
 rule>

 
 <rule ref="Generic.PHP.ForbiddenFunctions">
  <properties>
   <property name="forbiddenFunctions" type="array" value="delete=>unset,print=>echo,create_function=>null" />
  properties>
 rule>

 
 <rule ref="Generic.PHP.ForbiddenFunctions">
  <properties>
   <property name="forbiddenFunctions" type="array" extend="true">
    <element key="sizeof" value="count"/>
   property>
  properties>
 rule>

 
 <rule ref="Squiz.Strings.DoubleQuoteUsage.ContainsVar">
  <severity>0severity>
 rule>

 
 <rule ref="Internal.NoCodeFound">
  <severity>0severity>
 rule>

 
 <rule ref="Squiz.Strings.DoubleQuoteUsage">
    <exclude-pattern>*/tests/*exclude-pattern>
    <exclude-pattern>*/data/*exclude-pattern>
 rule>

 
 <rule ref="Squiz.Strings.DoubleQuoteUsage.ContainsVar">
    <exclude-pattern>*/tests/*exclude-pattern>
    <exclude-pattern>*/data/*exclude-pattern>
 rule>

  
 <rule ref="Squiz.Strings.DoubleQuoteUsage">
    <include-pattern>*/templates/*include-pattern>
    <include-pattern>*\.tpl$include-pattern>
 rule>

 
 <rule ref="Squiz.Strings.DoubleQuoteUsage.ContainsVar">
    <include-pattern>*/templates/*include-pattern>
    <include-pattern>*\.tpl$include-pattern>
 rule>

ruleset>

Selectively Applying Rules

All tags in a ruleset file, with the exception of ruleset and description, can be selectively applied when a specific tool is being run. The two tools that are available are phpcs (the coding standards checker) and phpcbf (the coding standards fixer). Restrictions are applied by using the phpcs-only and phpcbf-only tag attributes.

Setting the phpcs-only attribute to true will only apply the rule when the phpcs tool is running. The rule will not be applied while the file is being fixed with the phpcbf tool.

Setting the phpcbf-only attribute to true will only apply the rule when the phpcbf tool is fixing a file. The rule will not be applied while the file is being checked with the phpcs tool.

The following sample file shows a ruleset.xml file that makes use of selective rules. The file is designed for documentation purposes only and is not a working coding standard.

xml version="1.0"?>
<ruleset name="Selective Standard">

 
 <config phpcs-only="true" name="zend_ca_path" value="/path/to/ZendCodeAnalyzer"/>

 
 <exclude-pattern phpcbf-only="true">*/3rdparty/*exclude-pattern>

 
 <rule ref="Squiz">
  <exclude phpcbf-only="true" name="Generic.WhiteSpace.ScopeIndent"/>
 rule>

 
 <rule ref="Generic.Commenting.Todo.CommentFound">
  <severity phpcbf-only="true">0severity>
 rule>

 
 <rule ref="Generic.Files.LineLength">
  <properties>
   <property phpcs-only="true" name="lineLimit" value="80"/>
   <property phpcbf-only="true" name="lineLimit" value="120"/>
  properties>
 rule>

ruleset>

For everyone

Introduction
Requirements
Usage
Advanced Usage
Reporting
Configuration Options
Fixing Errors Automatically
FAQ

For coding standard creators

Annotated Ruleset
Customisable Sniff Properties

For sniff developers

Coding Standard Tutorial
Version 3.0 Upgrade Guide
Version 1.3.0 Upgrade Guide

Clone this wiki locally