Zend Coding Standard 2

.gitignore

@@ -0,0 +1,13 @@
+/.phpcs-cache
+/clover.xml
+/composer.lock
+/coveralls-upload.json
+/docs/html/
+/mkdocs.site.yml
+/phpcs.log
+/phpcs.xml
+/phpunit.xml
+/test/fix/
+/vendor/
+/zf-mkdoc-theme.tgz
+/zf-mkdoc-theme/

.travis.yml

@@ -0,0 +1,45 @@
+sudo: false
+language: php
+
+php:
+- 7.1
+- 7.2
+- nightly
+
+cache:
+  directories:
+    - $HOME/.composer/cache
+
+before_install:
+  - composer self-update
+
+install: travis_retry composer update --prefer-dist
+
+script:
+  - vendor/bin/phpcs
+  - vendor/bin/phpcs $(find test/fixable/* | sort) --report=summary --report-file=phpcs.log; diff test/expected-report.txt phpcs.log
+
+stages:
+  - Validate against schema
+  - Validate fixes
+  - Test
+
+jobs:
+  allow_failures:
+    - php: nightly
+
+  include:
+    - stage: Validate against schema
+      addons:
+        apt:
+          packages:
+          - libxml2-utils
+      script: xmllint --noout --schema vendor/squizlabs/php_codesniffer/phpcs.xsd src/ZendCodingStandard/ruleset.xml
+
+    - stage: Validate fixes
+      before_script:
+      - cp -R test/fixable/ test/fix/
+      script: vendor/bin/phpcbf test/fix; diff test/fix test/fixed
+
+notifications:
+  email: false

CHANGELOG.md

@@ -2,6 +2,141 @@
 
 All notable changes to this project will be documented in this file, in reverse chronological order by release.
 
+## 2.0.0 - TBD
+
+### Added
+
+- [#5](https://github.com/zendframework/zend-coding-standard/pull/5) adds 
+  online documentation: https://docs.zendframework.com/zend-coding-standard/
+- [#5](https://github.com/zendframework/zend-coding-standard/pull/5) adds 
+  PSR-12 rules.
+
+  *NOTE:* PSR-12 is not finalized. e.g. The `!` operator and `:` placement for
+  return values are still under discussion. We will change these rules, and, 
+  when PSR-12 is finalized, adapt them.
+- [#5](https://github.com/zendframework/zend-coding-standard/pull/5) extends 
+  PSR-12 with ZendFramework specific rules:
+
+  *NOTE:* Most of these rules should look familiar as they are already being
+  used in components rewritten for PHP 7.1. 
+
+  - There should be one space on either side of an equals sign used to assign 
+    a value to a variable. In case of a block of related assignments, more 
+    space may be inserted before the equal sign to promote readability.
+  - Short array syntax must be used to define arrays. 
+  - All values in multiline arrays must be indented with 4 spaces. 
+  - All array values must be followed by a comma, including the last value. 
+  - Whitespace is not allowed around the opening bracket or before the 
+    closing bracket when referencing an array.
+  - The `global` keyword may not be used.
+  - The `PHP_SAPI` constant must be used instead of the `php_sapi_name()` 
+    function.
+  - PHP function calls must be in lowercase.
+  - PHP functions which are an alias may not be used.
+  - Deprecated functions should not be used.
+  - Comments may be omitted and should not be used for typehinted arguments.
+  - Comments may not start with `#`.
+  - Comments may not be empty.
+  - The words _private_, _protected_, _static_, _constructor_, _deconstructor_,
+    _Created by_, _getter_ and _setter_, may not be used in comments.
+  - The annotations `@api`, `@author`, `@category`, `@created`, `@package`,
+    `@subpackage` and `@version` may not be used in comments. Git commits 
+    provide accurate information.
+  - The asterisks in a doc comment should align, and there should be one space 
+    between the asterisk and tag.
+  - Comment tags `@param`, `@throws` and `@return` should not be aligned or 
+    contain multiple spaces between the tag, type and description.
+  - If a function throws any exceptions, they should be documented in `@throws` 
+    tags.
+  - The `@var` tag may be used in inline comments to document the _Type_ of 
+    properties.
+  - Single-line comments with a `@var` tag should be written as one-liners.
+  - Shorthand scalar typehint variants must be used in docblocks.
+  - Each PHP file should have a page level docblock with `@see`, `@copyright` 
+    and `@license`. The copyright date should only be adjusted if the file has 
+    changed.
+  - Each PHP file should have a strict type declaration at the top after the 
+    page level docblock.
+  - Import statements should be alphabetically sorted.
+  - Import statements should not be grouped.
+  - Each import statement should be on its own line.
+  - Absolute class name references, functions and constants should be imported.
+  - Unused import statements are not allowed.
+  - Classes and function within the same namespace should not be imported.
+  - Imports should not have an alias with the same name.
+  - A class should not have unused private constants, (or write-only) 
+    properties and methods.
+  - Class name resolution via `::class` should be used instead of 
+    `__CLASS__`, `get_class()`, `get_class($this)`, `get_called_class()` and 
+    `get_parent_class()`.
+  - Methods may not have the final declaration in classes declared as final.
+  - The colon used with return type declarations MUST be surrounded with 1 
+    space.
+  - Nullable and optional arguments, which are marked as `= null`, must have 
+    the `?` symbol present.
+  - Control Structures must have at least one statement inside of the body.    
+  - Catch blocks may be empty.
+  - Catch blocks must be reachable.
+  - Catch blocks must use `Throwable` instead of `Exception`.    
+  - The not (`!`) operator must be followed by exactly one space.
+  - The `&&` and `||` operators must be used instead of `AND` and `OR`.
+  - The null  coalescing operator `??` should be used when possible.
+  - Assignment operators (eg `+=`, `.=`) should be used when possible.
+  - Unused variables should not be passed to closures via `use`.    
+  - The code may not contain unreachable code.
+  - The backtick operator may not be used for execution of shell commands.
+  - Class and Interface names should be unique in a project and must have a 
+    unique fully qualified name.
+  - Methods that only call the parent method should not be defined.
+  - Files that contain PHP code should only have PHP code and should not have
+    any _"inline HTML"_.
+  - There must be exactly one space after a type cast. 
+  - Constructors should be named `__construct`, not after the class.
+  - The opening PHP tag should be the first item in the file. 
+  - Strings should not be concatenated together unless used in multiline for 
+    readability. 
+  - Loose `==` and `!=` comparison operators should not be used. Use `===` 
+    and `!==` instead.
+  - Language constructs must be used without parentheses where possible.
+  - Short list syntax `[...]` should be used instead of `list(...)`.
+  - Short form of type keywords must be used. i.e. `bool` instead of 
+    `boolean`, `int` instead of `integer`, etc. The `binary` and `unset` cast 
+    operators are not allowed.
+  - Parentheses should not be used if they can be omitted.
+  - Semicolons `;` should not be used if they can be omitted.
+  - Variables should be returned directly instead of assigned to a variable 
+    which is not used.
+  - The `self` keyword should be used instead of the current class name, and 
+    should not have spaces around `::`.
+  - Static methods should not use `$this`. 
+  - Double quote strings may only be used if they contain variables. 
+  - Strings should not be enclosed in parentheses when being echoed.
+  - Type casts should not have whitespace inside the parentheses.
+  - The opening brace for functions should be on a new line with no blank 
+    lines surrounding it.
+  - The PHP constructs `echo`, `print`, `return`, `include`, `include_once`, 
+    `require`, `require_once`, and `new`, should have one space after them.
+  - The object operator `->` should not have any spaces around it.
+  - Semicolons should not have spaces before them.
+  - The code should not contain superfluous whitespaces. e.g. multiple empty
+    lines, trailing spaces, etc.
+
+### Changed
+
+- Nothing.
+
+### Deprecated
+
+- Nothing.
+
+### Removed
+
+- Nothing.
+
+### Fixed
+
+- Nothing.
+
 ## 1.0.0 - 2016-11-09
 
 Initial public release. Incorporates rules for:

LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2016, Zend Technologies USA, Inc.
+Copyright (c) 2016-2018, Zend Technologies USA, Inc.
 
 All rights reserved.
 

README.md

@@ -1,11 +1,28 @@
-Zend Framework Coding Standard
-==============================
+# zend-coding-standard
 
-Repository with all coding standard ruleset for Zend Framework repositories.
+[![Build Status](https://secure.travis-ci.org/zendframework/zend-coding-standard.svg?branch=master)](https://secure.travis-ci.org/zendframework/zend-coding-standard)
 
+The coding standard ruleset for Zend Framework components.
 
-Installation
-------------
+This specification extends and expands [PSR-12](https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md), 
+the extended coding style guide and requires adherence to [PSR-1](https://www.php-fig.org/psr/psr-1), 
+the basic coding standard. These are minimal specifications and don't address all factors, including things like:
+
+- whitespace around operators
+- alignment of array keys and operators
+- alignment of object operations
+- how to format multi-line conditionals
+- what and what not to import, and how
+- etc.
+
+Contributors have different coding styles and so do the maintainers. During code reviews there are regularly 
+discussions about spaces and alignments, where and when was said that a function needs to be imported. And 
+that's where this coding standard comes in: To have internal consistency in a component and between components.
+
+> Note: PSR-12 is not finalized. e.g. The `!` operator and `:` placement for return values are still under  discussion. 
+We will change these rules, and, when PSR-12 is finalized, adapt them.
+
+## Installation
 
 1. Install the module via composer by running:
 
@@ -22,26 +39,36 @@ Installation
    }
    ```
 
-3. Create file `phpcs.xml` on base path of your repository with content:
+3. Create file `phpcs.xml` on base path of your repository with this content:
 
    ```xml
    <?xml version="1.0"?>
-   <ruleset name="Zend Framework Coding Standard">
-       <rule ref="./vendor/zendframework/zend-coding-standard/ruleset.xml"/>
-
+   <ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:noNamespaceSchemaLocation="vendor/squizlabs/php_codesniffer/phpcs.xsd">
+
+       <arg name="basepath" value="."/>
+       <arg name="cache" value=".phpcs-cache"/>
+       <arg name="colors"/>
+       <arg name="extensions" value="php"/>
+       <arg name="parallel" value="80"/>
+
+       <!-- Show progress -->
+       <arg value="p"/>
+
        <!-- Paths to check -->
        <file>config</file>
        <file>src</file>
        <file>test</file>
+
+       <!-- Include all rules from the Zend Coding Standard -->
+       <rule ref="ZendCodingStandard"/>
    </ruleset>
    ```
 
 You can add or exclude some locations in that file.
 For a reference please see: https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-ruleset.xml
 
-
-Usage
------
+## Usage
 
 * To run checks only:
 
@@ -50,7 +77,62 @@ Usage
   ```
 
 * To automatically fix many CS issues:
- 
+
   ```bash
   $ composer cs-fix
   ```
+
+## Ignoring parts of a File
+
+> Note: Before PHP_CodeSniffer version 3.2.0, `// @codingStandardsIgnoreStart` and `// @codingStandardsIgnoreEnd` were
+> used. These are deprecated and will be removed in PHP_CodeSniffer version 4.0.
+
+Disable parts of a file:
+```php
+$xmlPackage = new XMLPackage;
+// phpcs:disable
+$xmlPackage['error_code'] = get_default_error_code_value();
+$xmlPackage->send();
+// phpcs:enable
+```
+
+Disable a specific rule:
+```php
+// phpcs:disable Generic.Commenting.Todo.Found
+$xmlPackage = new XMLPackage;
+$xmlPackage['error_code'] = get_default_error_code_value();
+// TODO: Add an error message here.
+$xmlPackage->send();
+// phpcs:enable
+```
+
+## Development
+
+> **New rules or Sniffs may not be introduced in minor or bugfix releases and should always be based on the develop 
+branch and queued for the next major release, unless considered a bugfix for existing rules.**
+
+If you want to test changes against ZendFramework components or your own projects, install your forked 
+zend-coding-standard globally with composer: 
+```bash
+$ composer global config repositories.zend-coding-standard vcs [email protected]:<FORK_NAMESPACE>/zend-coding-standard.git
+$ composer global require --dev zendframework/zend-coding-standard:dev-<FORKED_BRANCH>
+
+# For this to work, add this to your path: ~/.composer/vendor/bin
+# Using `-s` prints the rules that triggered the errors so they can be reviewed easily. `-p` is for progress display.
+$ phpcs -sp --standard=ZendCodingStandard src test
+```
+Make sure you remove the global installation after testing from your global composer.json file!!!
+
+Documentation can be previewed locally by installing [MkDocs](https://www.mkdocs.org/#installation) and run 
+`mkdocs serve`. This will start a server where you can read the docs.
+
+## Reference
+
+Rules can be added, excluded or tweaked locally, depending on your preferences. More information on how to do this can
+be found here:
+
+- [Coding Standard Tutorial](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Coding-Standard-Tutorial)
+- [Configuration Options](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Configuration-Options)
+- [Selectively Applying Rules](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-Ruleset#selectively-applying-rules)
+- [Customisable Sniff Properties](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Customisable-Sniff-Properties)
+- [Slevomat Coding Standard](https://github.com/slevomat/coding-standard)