-
-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #26 from PHPCSStandards/feature/add-readme
Add a README
- Loading branch information
Showing
1 changed file
with
195 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,2 +1,195 @@ | ||
| # Standards | ||
| A collection of code standards for use with PHP_CodeSniffer | ||
| PHPCSExtra | ||
| ===================================================== | ||
|
|
||
| <div aria-hidden="true"> | ||
|
|
||
| [](https://packagist.org/packages/phpcsstandards/phpcsextra) | ||
| [](https://travis-ci.com/PHPCSStandards/PHPCSExtra/branches) | ||
| [](https://github.com/PHPCSStandards/PHPCSExtra/releases) | ||
| :construction: | ||
| [](https://packagist.org/packages/phpcsstandards/phpcsextra#dev-develop) | ||
| [](https://travis-ci.com/PHPCSStandards/PHPCSExtra/branches) | ||
| [](https://github.com/PHPCSStandards/PHPCSExtra/commits/develop) | ||
|
|
||
| [](https://packagist.org/packages/phpcsstandards/phpcsextra) | ||
| [](https://travis-ci.com/PHPCSStandards/PHPCSExtra) | ||
|
|
||
| [](https://github.com/PHPCSStandards/PHPCSExtra/blob/master/LICENSE) | ||
|  | ||
|
|
||
| </div> | ||
|
|
||
| * [Introduction](#introduction) | ||
| * [Minimum Requirements](#minimum-requirements) | ||
| * [Installation](#installation) | ||
| + [Composer Project-based Installation](#composer-project-based-installation) | ||
| + [Composer Global Installation](#composer-global-installation) | ||
| * [Features](#features) | ||
| * [Sniffs](#sniffs) | ||
| + [NormalizedArrays](#normalizedarrays) | ||
| + [Universal](#universal) | ||
| * [Contributing](#contributing) | ||
| * [License](#license) | ||
|
|
||
|
|
||
| Introduction | ||
| ------------------------------------------- | ||
|
|
||
| PHPCSExtra is a collection of sniffs and standards for use with [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer). | ||
|
|
||
|
|
||
| Minimum Requirements | ||
| ------------------------------------------- | ||
|
|
||
| * PHP 5.4 or higher. | ||
| * [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) version **3.3.1** or higher. | ||
| * [PHPCSUtils](https://github.com/PHPCSStandards/PHPCSUtils) version **1.0.0** or higher. | ||
|
|
||
|
|
||
| Installation | ||
| ------------------------------------------- | ||
|
|
||
| Installing via Composer is highly recommended. | ||
|
|
||
| [Composer](http://getcomposer.org/) will automatically install the project dependencies and register the rulesets from PHPCSExtra and other external standards with PHP_CodeSniffer using the [DealerDirect Composer PHPCS plugin](https://github.com/Dealerdirect/phpcodesniffer-composer-installer/). | ||
|
|
||
| ### Composer Project-based Installation | ||
|
|
||
| Run the following from the root of your project: | ||
| ```bash | ||
| composer require --dev phpcsstandards/phpcsextra:"^1.0" | ||
| ``` | ||
|
|
||
| ### Composer Global Installation | ||
|
|
||
| Alternatively, you may want to install this standard globally: | ||
| ```bash | ||
| composer global require --dev phpcsstandards/phpcsextra:"^1.0" | ||
| ``` | ||
|
|
||
|
|
||
| Features | ||
| ------------------------------------------- | ||
|
|
||
| Once this project is installed, you will see two new rulesets in the list of installed standards when you run `phpcs -i`: `NormalizedArrays` and `Universal`. | ||
|
|
||
| * The `NormalizedArrays` ruleset is a standard to check the formatting of array declarations. | ||
| * The `Universal` ruleset is **NOT** a standard, but a sniff collection. | ||
| It should **NOT** be included in custom rulesets as a standard as it contains contradictory rules. | ||
| Instead include individual sniffs from this standard in a custom project/company ruleset to use them. | ||
|
|
||
|
|
||
| Sniffs | ||
| ------------------------------------------- | ||
|
|
||
| **Legend**: | ||
| * :wrench: = Includes auto-fixer. | ||
| * :bar_chart: = Includes metrics. | ||
| * :books: = Includes CLI documentation. | ||
|
|
||
|
|
||
| ### NormalizedArrays | ||
|
|
||
| #### `NormalizedArrays.Arrays.ArrayBraceSpacing` :wrench: :bar_chart: :books: | ||
|
|
||
| Enforce consistent spacing for the open/close braces of array declarations. | ||
|
|
||
| The sniff allows for having different settings for: | ||
| - Space between the array keyword and the open parenthesis for long arrays via the `keywordSpacing` property. | ||
| Accepted values: (int) number of spaces or `false` to turn this check off. Defaults to `0` spaces. | ||
| - Spaces on the inside of the braces for empty arrays via the `spacesWhenEmpty` property. | ||
| Accepted values: (string) `newline`, (int) number of spaces or `false` to turn this check off. Defaults to `0` spaces. | ||
| - Spaces on the inside of the braces for single-line arrays via the `spacesSingleLine` property; | ||
| Accepted values: (int) number of spaces or `false` to turn this check off. Defaults to `0` spaces. | ||
| - Spaces on the inside of the braces for multi-line arrays via the `spacesMultiLine` property. | ||
| Accepted values: (string) `newline`, (int) number of spaces or `false` to turn this check off. Defaults to `newline`. | ||
|
|
||
| Note: if any of the above properties are set to `newline`, it is recommended to also include an array indentation sniff. This sniff will not handle the indentation. | ||
|
|
||
| #### `NormalizedArrays.Arrays.CommaAfterLast` :wrench: :bar_chart: :books: | ||
|
|
||
| Enforce/forbid a comma after the last item in an array declaration. | ||
|
|
||
| By default, this sniff will: | ||
| * Forbid a comma after the last array item for single-line arrays. | ||
| * Enforce a comma after the last array item for multi-line arrays. | ||
|
|
||
| This can be changed for each type or array individually by setting the `singleLine` or `multiLine` properties in a custom ruleset. | ||
|
|
||
| Use any of the following values to change the properties: `enforce`, `forbid` or `skip` to not check the comma after the last array item for a particular type of array. | ||
|
|
||
|
|
||
| ### Universal | ||
|
|
||
| #### `Universal.Arrays.DuplicateArrayKey` :books: | ||
|
|
||
| Detects duplicate array keys in array declarations. | ||
|
|
||
| #### `Universal.Arrays.MixedArrayKeyTypes` :books: | ||
|
|
||
| Best practice sniff: don't use a mix of integer and numeric keys for array items. | ||
|
|
||
| #### `Universal.Arrays.MixedKeyedUnkeyedArray` :books: | ||
|
|
||
| Best practice sniff: don't use a mix of keyed and unkeyed array items. | ||
|
|
||
| #### `Universal.ControlStructures.DisallowAlternativeSyntax` :wrench: :bar_chart: :books: | ||
|
|
||
| Disallow using the alternative syntax for control structures. | ||
|
|
||
| * This sniff contains a `allowWithInlineHTML` property to allow alternative syntax when inline HTML is used within the control structure. In all other cases, the use of the alternative syntax will still be disallowed. | ||
| * The sniff has modular error codes to allow for making exceptions based on specific control structures and/or specific control structures in combination with inline HTML. | ||
|
|
||
| #### `Universal.ControlStructures.IfElseDeclaration` :wrench: :bar_chart: :books: | ||
|
|
||
| Verify that else(if) statements with braces are on a new line. | ||
|
|
||
| #### `Universal.Lists.DisallowLongListSyntax` :wrench: :bar_chart: :books: | ||
|
|
||
| Disallow the use of long `list`s. | ||
|
|
||
| #### `Universal.Lists.DisallowShortListSyntax` :wrench: :bar_chart: :books: | ||
|
|
||
| Disallow the use of short lists. | ||
|
|
||
| #### `Universal.Namespaces.DisallowCurlyBraceSyntax` :bar_chart: :books: | ||
|
|
||
| Disallow the use of the alternative namespace declaration syntax using curly braces. | ||
|
|
||
| #### `Universal.Namespaces.EnforceCurlyBraceSyntax` :bar_chart: :books: | ||
|
|
||
| Enforce the use of the alternative namespace syntax using curly braces. | ||
|
|
||
| #### `Universal.Namespaces.OneDeclarationPerFile` :books: | ||
|
|
||
| Disallow the use of multiple namespaces within a file. | ||
|
|
||
| #### `Universal.UseStatements.DisallowUseClass` :bar_chart: :books: | ||
|
|
||
| Forbid using import `use` statements for classes/traits/interfaces. | ||
|
|
||
| Individual sub-types - with/without alias, global imports, imports from the same namespace - can be forbidden by just including that specific error code and/or allowed including the whole sniff and excluding specific error codes. | ||
|
|
||
| #### `Universal.UseStatements.DisallowUseConst` :bar_chart: :books: | ||
|
|
||
| Forbid using import `use` statements for constants. | ||
|
|
||
| Individual sub-types - with/without alias, global imports, imports from the same namespace - can be forbidden by just including that specific error code and/or allowed including the whole sniff and excluding specific error codes. | ||
|
|
||
| #### `Universal.UseStatements.DisallowUseFunction` :bar_chart: :books: | ||
|
|
||
| Forbid using import `use` statements for functions. | ||
|
|
||
| Individual sub-types - with/without alias, global imports, imports from the same namespace - can be forbidden by just including that specific error code and/or allowed including the whole sniff and excluding specific error codes. | ||
|
|
||
|
|
||
|
|
||
| Contributing | ||
| ------- | ||
| Contributions to this project are welcome. Clone the repo, branch off from `develop`, make your changes, commit them and send in a pull request. | ||
|
|
||
| If unsure whether the changes you are proposing would be welcome, open an issue first to discuss your proposal. | ||
|
|
||
| License | ||
| ------- | ||
| This code is released under the GNU Lesser General Public License (LGPLv3). For more information, visit http://www.gnu.org/copyleft/lesser.html |