Add new "About Standards" page

This new page contains more generic information about:
* The difference between a project ruleset and a standard.
* Requirements for a standard.
* Naming conventions for sniffs.

Author: jrfnl

wiki/About-Standards-for-PHP_CodeSniffer.md

@@ -0,0 +1,263 @@
+## Table of contents
+
+* [A Project ruleset or a standard ?](#a-project-ruleset-or-a-standard-)
+* [About standards](#about-standards)
+* [Creating an external standard for PHP_CodeSniffer](#creating-an-external-standard-for-php_codesniffer)
+* [Creating new rules](#creating-new-rules)
+   * [Naming conventions](#naming-conventions)
+
+***
+
+## A Project ruleset or a standard ?
+
+The terminology used for coding standards in the context of PHP_CodeSniffer can be confusing.
+When do you use a project ruleset ? When should you use a standard ?
+
+Let's try and clarify this.
+
+As a general rule of thumb: individual projects should use a project ruleset to document the rules enforced for the project.
+Project rulesets may _include_ one or more predefined standards.
+
+If a group of projects should use the same rules, you could create an external standard to define the common rules. This external standard can then be included in the project specific ruleset for each individual project.
+
+The typical differences between project-specific rulesets and standards are:
+
+|                                                                               | Project specific ruleset | External standard              |
+|-------------------------------------------------------------------------------|--------------------------|--------------------------------|
+| File name                                                                     | `[.]phpcs.xml[.dist]`    | `ruleset.xml`                  |
+| Location                                                                      | Project root directory   | Standard directory (see below) |
+| Will automatically be used when no standard is provided on the command line ? | Yes                      | No                             |
+| Can have custom sniffs ?                                                      | No                       | Yes                            |
+| Can be installed ?                                                            | No                       | Yes                            |
+| Reusability by other projects ?                                               | Limited                  | Yes                            |
+
+For optimal reusability, it is in most cases a good idea for a standard to be in its own repository and to be maintained as a separate project.
+
+A `[.]phpcs.xml[.dist]` file and a `ruleset.xml` file can largely contain the same type of directives.
+The [Annotated ruleset](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Annotated-Ruleset) page contains information on all the directives you can use.
+
+Keep in mind that for a _standard_ to be optimally reusable, it should not contain project specific information, such as `<file>` directives or `<exclude-patterns>`, while a project specific `[.]phpcs.xml[.dist]` ruleset file _can_ contain that information.
+
+You may also find the [Customisable Sniff Properties](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Customisable-Sniff-Properties) page a handy reference for customisations which can be made to PHP_CodeSniffer native sniffs.
+
+<p align="right"><a href="#table-of-contents">back to top</a></p>
+
+
+## About standards
+
+In the context of PHP_CodeSniffer, a _"standard"_ is a predefined collection of rules for code to follow.
+Examples of standards are: PSR2 and PSR12, but a standard can also be eco-system specific, such as a Joomla or Doctrine standard, company specific or specific to a group of (related) projects.
+
+PHP_CodeSniffer has a number of build-in standards. However, if you want to define your own standard, you can.
+In terms of PHP_CodeSniffer, this is regarded as an _"external standard"_ and the path to the standard can be registered with PHP_CodeSniffer using the `--config-set installed_paths path/to/standard` command.
+
+A standard _may_ contain sniffs, but it doesn't have to. More about this below.
+
+<p align="right"><a href="#table-of-contents">back to top</a></p>
+
+
+## Creating an external standard for PHP_CodeSniffer
+
+The first thing to do is to think of a name for the standard.
+
+Rules to keep in mind:
+* The standard name CANNOT contain spaces, `.` characters or slashes.
+* The standard name CANNOT be named "Internal".
+* IF the standard will contain custom sniffs, the standard name MUST be a name which can be used in a PHP namespace, i.e. it is not allowed to start with a number, not allowed to contain dashes etc.
+
+Once you have a good name:
+* Create a directory with that name (case-sensitive).
+* Create a file in that directory called `ruleset.xml` with the following contents and replace `StandardName` in the below code snippet with your chosen name.
+```xml
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="StandardName" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+</ruleset>
+```
+
+If your chosen standard name is `MyCompanyStandard`, the directory structure would now look like this:
+```
+- MyCompanyStandard (directory)
+  - ruleset.xml (file)
+```
+
+Now you can start adding rules to the standard.
+
+For example, if your standard wants to enforce space indentation, you can add the `Generic.WhiteSpace.DisallowTabIndent` sniff to your ruleset:
+```xml
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="YourStandardName" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+    <rule ref="Generic.WhiteSpace.DisallowTabIndent"/>
+
+</ruleset>
+```
+
+As mentioned before, have a look at the [Annotated ruleset](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Annotated-Ruleset) and the [Customisable Sniff Properties](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Customisable-Sniff-Properties) pages for inspiration on what directives and customisations you can add to your ruleset.
+
+<p align="right"><a href="#table-of-contents">back to top</a></p>
+
+
+## Creating new rules
+
+There may be rules you want to enforce for which you cannot find an existing sniff, either in the PHP_CodeSniffer build-in standards or in any of the available generic external standards.
+
+In that case, you can write your own sniff to enforce that rule.
+
+> If the sniff could be generically usable, please be a good open source citizen and consider opening an issue in PHP_CodeSniffer, or in one of the external standards repositories, and offer to contribute the sniff, making it available for others to use as well.
+
+> [!IMPORTANT]
+> All sniffs in a standard are automatically included. There is no need to include the sniff(s) in the `ruleset.xml` via a `<rule ref=.../>`.
+
+
+There is a [Coding Standard Tutorial](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Coding-Standard-Tutorial) available on how to write a sniff.
+
+<p align="right"><a href="#table-of-contents">back to top</a></p>
+
+
+### Naming conventions
+
+Sniffs need to follow strict directory layout and naming conventions to allow for PHP_CodeSniffer to autoload sniff files correctly, translate between sniff codes and sniff class names, and to set any customisations indicated in a ruleset for a particular sniff.
+
+#### 1. Directory structure
+
+A sniff MUST belong to a standard and MUST be in a category.
+
+The directory structure MUST be as follows:
+```
+[StandardName]/Sniffs/[CategoryName]/
+```
+
+* The `[StandardName]` directory MAY be nested deeper inside a project.
+* No directories should exist under the `[CategoryName]` directory.
+
+#### 2. Sniff file name
+
+All sniff files MUST end on `Sniff.php` and be located within a `[CategoryName]` directory.
+
+All sniffs MUST have a name, so a sniff class called just and only `Sniff` is not allowed.
+
+Both the sniff name and the category name MUST be valid symbol names in PHP.
+
+
+#### 3. Namespace and class name
+
+The namespace and class name MUST follow [PSR-4](https://www.php-fig.org/psr/psr-4/).
+
+This means that - taking the example directory structure above in to account - the namespace name MUST end on `[StandardName]\Sniffs\[CategoryName]` and the class name MUST be exactly the same as the file name (minus the `.php` file extension).
+
+> [!NOTE]
+> As long as an external standard is registered with PHP_CodeSniffer via `installed_paths` and the standard follows the directory layout and naming conventions, PHP_CodeSniffer can, and will, automatically handle the sniff autoloading.
+>
+> As the PHP_CodeSniffer autoloader is essential for the translation between sniff codes (as used in rulesets) and sniff class names, it is strongly discouraged to set up autoloading of sniff classes via Composer, as this can interfere with the _error code to sniff class_ translation.
+
+
+#### Examples
+
+
+##### Valid:
+```
+<?php
+// File: MyStandard/Sniffs/Operators/OperatorSpacingSniff.php
+
+namespace MyStandard\Sniffs\Operators;
+
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+
+class OperatorSpacingSniff implements Sniff {...}
+```
+
+Prefixing the namespace is allowed:
+```
+<?php
+// File: MyStandard/Sniffs/Operators/OperatorSpacingSniff.php
+
+namespace NS\Prefix\MyStandard\Sniffs\Operators;
+
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+
+class OperatorSpacingSniff implements Sniff {...}
+```
+
+Be sure to inform PHP_CodeSniffer about the namespace prefix by annotating it in the `ruleset.xml` file in the `namespace` attribute on the `ruleset` node:
+```xml
+<?xml version="1.0"?>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="MyStandard" namespace="NS\Prefix\MyStandard" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
+
+</ruleset>
+```
+
+Nesting the standard directory deeper inside a project is allowed:
+```
+<?php
+// File: src/Tools/PHPCS/MyStandard/Sniffs/Operators/OperatorSpacingSniff.php
+
+namespace Vendor\Tools\PHPCS\MyStandard\Sniffs\Operators;
+
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+
+class OperatorSpacingSniff implements Sniff {...}
+```
+The same note about setting the `namespace` attribute in the `ruleset.xml` file applies.
+
+Also make sure that the `installed_paths` configuration option is set correctly and points to the `MyStandard` directory.
+
+
+##### Invalid:
+
+Sniff name not ending on `Sniff`:
+```
+<?php
+// File: MyStandard/Sniffs/Operators/OperatorSpacing.php
+
+namespace MyStandard\Sniffs\Operators;
+
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+
+class OperatorSpacing implements Sniff {...}
+```
+
+Sniff not placed in a (sub-)directory under a `Sniffs` directory:
+```
+<?php
+// File: MyStandard/Operators/OperatorSpacing.php
+
+namespace MyStandard\Operators;
+
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+
+class OperatorSpacingSniff implements Sniff {...}
+```
+
+Not following the required directory structure (missing `[CategoryName]` subdirectory):
+```
+<?php
+// File: MyStandard/Sniffs/OperatorSpacingSniff.php
+
+namespace MyStandard\Sniffs;
+
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+
+class OperatorSpacingSniff implements Sniff {...}
+```
+
+Not following the required directory structure (missing `[StandardName]` top-level directory):
+```
+<?php
+// File: src/Sniffs/Operators/OperatorSpacingSniff.php
+
+namespace Sniffs\Operators;
+
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\Sniff;
+
+class OperatorSpacingSniff implements Sniff {...}
+```
+
+<p align="right"><a href="#table-of-contents">back to top</a></p>

wiki/Annotated-Ruleset.md

@@ -2,15 +2,23 @@ PHP_CodeSniffer allows developers to design their own coding standards by creati
 
 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
+```bash
+$ phpcs --standard=/path/to/custom_ruleset.xml test.php
+```
+
+By default, PHP_CodeSniffer will look for the following files: `.phpcs.xml`, `phpcs.xml`, `.phpcs.xml.dist`, `phpcs.xml.dist`.
+If you use one of these names for your standard, PHP_CodeSniffer will automatically find anf use it if no `--standard` is provided on the command-line.
+
+For projects, it is recommended to use one of the `.dist` filenames.
+
 
 ## 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
 <?xml version="1.0"?>
-<ruleset name="Custom Standard" namespace="MyProject\CS\Standard">
+<ruleset name="CustomStandard" namespace="MyProject\CS\CustomStandard">
 
  <!--
     The name attribute of the ruleset tag is displayed
@@ -190,6 +198,9 @@ The following sample file documents the ruleset.xml format and shows you the com
     If you are including sniffs that are not installed, you can
     reference the sniff class using an absolute or relative path
     instead of using the sniff code.
+    Sniffs included via a path reference should still follow the
+    naming conventions for PHP_CodeSniffer as outlined in
+    https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/About-Standards-for-PHP_CodeSniffer#naming-conventions
  -->
  <rule ref="/path/to/standards/Generic/Sniffs/Commenting/TodoSniff.php"/>
  <rule ref="../Generic/Sniffs/ControlStructures/InlineControlStructureSniff.php"/>
@@ -479,4 +490,4 @@ The following sample file shows a ruleset.xml file that makes use of selective r
  </rule>
 
 </ruleset>
-```
+```

wiki/Coding-Standard-Tutorial.md

@@ -1,5 +1,7 @@
 In this tutorial, we will create a new coding standard with a single sniff. Our sniff will prohibit the use of Perl style hash comments.
 
+Sniffs need to follow [strict directory layout and naming conventions](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/About-Standards-for-PHP_CodeSniffer#naming-conventions).
+
 ## Creating the Coding Standard Directory
 
 All sniffs in PHP_CodeSniffer must belong to a coding standard. A coding standard is a directory with a specific sub-directory structure and a `ruleset.xml` file, so we can create one very easily. Let's call our coding standard _MyStandard_. Run the following commands to create the coding standard directory structure:

wiki/_Sidebar.md

@@ -11,6 +11,7 @@ For everyone
 
 For coding standard creators
 
+[[About Standards for PHP_CodeSniffer]]  
 [[Annotated Ruleset]]  
 [[Customisable Sniff Properties]]