Skip to content
This repository was archived by the owner on Jan 21, 2020. It is now read-only.

Commit d81e6c6

Browse files
geerteltinkgeerteltink
committed
Merge pull request #5 from xtreamwayz/feature/new-rules
Close #5
2 parents 893316d + 7dc2f78 commit d81e6c6

File tree

76 files changed

+4572
-40
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

76 files changed

+4572
-40
lines changed

‎.gitignore

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
/.phpcs-cache
2+
/clover.xml
3+
/composer.lock
4+
/coveralls-upload.json
5+
/docs/html/
6+
/mkdocs.site.yml
7+
/phpcs.log
8+
/phpcs.xml
9+
/phpunit.xml
10+
/test/fix/
11+
/vendor/
12+
/zf-mkdoc-theme.tgz
13+
/zf-mkdoc-theme/

‎.travis.yml

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
sudo: false
2+
language: php
3+
4+
php:
5+
- 7.1
6+
- 7.2
7+
- nightly
8+
9+
cache:
10+
directories:
11+
- $HOME/.composer/cache
12+
13+
before_install:
14+
- composer self-update
15+
16+
install: travis_retry composer update --prefer-dist
17+
18+
script:
19+
- vendor/bin/phpcs
20+
- vendor/bin/phpcs $(find test/fixable/* | sort) --report=summary --report-file=phpcs.log; diff test/expected-report.txt phpcs.log
21+
22+
stages:
23+
- Validate against schema
24+
- Validate fixes
25+
- Test
26+
27+
jobs:
28+
allow_failures:
29+
- php: nightly
30+
31+
include:
32+
- stage: Validate against schema
33+
addons:
34+
apt:
35+
packages:
36+
- libxml2-utils
37+
script: xmllint --noout --schema vendor/squizlabs/php_codesniffer/phpcs.xsd src/ZendCodingStandard/ruleset.xml
38+
39+
- stage: Validate fixes
40+
before_script:
41+
- cp -R test/fixable/ test/fix/
42+
script: vendor/bin/phpcbf test/fix; diff test/fix test/fixed
43+
44+
notifications:
45+
email: false

‎CHANGELOG.md

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,141 @@
22

33
All notable changes to this project will be documented in this file, in reverse chronological order by release.
44

5+
## 2.0.0 - TBD
6+
7+
### Added
8+
9+
- [#5](https://github.com/zendframework/zend-coding-standard/pull/5) adds
10+
online documentation: https://docs.zendframework.com/zend-coding-standard/
11+
- [#5](https://github.com/zendframework/zend-coding-standard/pull/5) adds
12+
PSR-12 rules.
13+
14+
*NOTE:* PSR-12 is not finalized. e.g. The `!` operator and `:` placement for
15+
return values are still under discussion. We will change these rules, and,
16+
when PSR-12 is finalized, adapt them.
17+
- [#5](https://github.com/zendframework/zend-coding-standard/pull/5) extends
18+
PSR-12 with ZendFramework specific rules:
19+
20+
*NOTE:* Most of these rules should look familiar as they are already being
21+
used in components rewritten for PHP 7.1.
22+
23+
- There should be one space on either side of an equals sign used to assign
24+
a value to a variable. In case of a block of related assignments, more
25+
space may be inserted before the equal sign to promote readability.
26+
- Short array syntax must be used to define arrays.
27+
- All values in multiline arrays must be indented with 4 spaces.
28+
- All array values must be followed by a comma, including the last value.
29+
- Whitespace is not allowed around the opening bracket or before the
30+
closing bracket when referencing an array.
31+
- The `global` keyword may not be used.
32+
- The `PHP_SAPI` constant must be used instead of the `php_sapi_name()`
33+
function.
34+
- PHP function calls must be in lowercase.
35+
- PHP functions which are an alias may not be used.
36+
- Deprecated functions should not be used.
37+
- Comments may be omitted and should not be used for typehinted arguments.
38+
- Comments may not start with `#`.
39+
- Comments may not be empty.
40+
- The words _private_, _protected_, _static_, _constructor_, _deconstructor_,
41+
_Created by_, _getter_ and _setter_, may not be used in comments.
42+
- The annotations `@api`, `@author`, `@category`, `@created`, `@package`,
43+
`@subpackage` and `@version` may not be used in comments. Git commits
44+
provide accurate information.
45+
- The asterisks in a doc comment should align, and there should be one space
46+
between the asterisk and tag.
47+
- Comment tags `@param`, `@throws` and `@return` should not be aligned or
48+
contain multiple spaces between the tag, type and description.
49+
- If a function throws any exceptions, they should be documented in `@throws`
50+
tags.
51+
- The `@var` tag may be used in inline comments to document the _Type_ of
52+
properties.
53+
- Single-line comments with a `@var` tag should be written as one-liners.
54+
- Shorthand scalar typehint variants must be used in docblocks.
55+
- Each PHP file should have a page level docblock with `@see`, `@copyright`
56+
and `@license`. The copyright date should only be adjusted if the file has
57+
changed.
58+
- Each PHP file should have a strict type declaration at the top after the
59+
page level docblock.
60+
- Import statements should be alphabetically sorted.
61+
- Import statements should not be grouped.
62+
- Each import statement should be on its own line.
63+
- Absolute class name references, functions and constants should be imported.
64+
- Unused import statements are not allowed.
65+
- Classes and function within the same namespace should not be imported.
66+
- Imports should not have an alias with the same name.
67+
- A class should not have unused private constants, (or write-only)
68+
properties and methods.
69+
- Class name resolution via `::class` should be used instead of
70+
`__CLASS__`, `get_class()`, `get_class($this)`, `get_called_class()` and
71+
`get_parent_class()`.
72+
- Methods may not have the final declaration in classes declared as final.
73+
- The colon used with return type declarations MUST be surrounded with 1
74+
space.
75+
- Nullable and optional arguments, which are marked as `= null`, must have
76+
the `?` symbol present.
77+
- Control Structures must have at least one statement inside of the body.
78+
- Catch blocks may be empty.
79+
- Catch blocks must be reachable.
80+
- Catch blocks must use `Throwable` instead of `Exception`.
81+
- The not (`!`) operator must be followed by exactly one space.
82+
- The `&&` and `||` operators must be used instead of `AND` and `OR`.
83+
- The null coalescing operator `??` should be used when possible.
84+
- Assignment operators (eg `+=`, `.=`) should be used when possible.
85+
- Unused variables should not be passed to closures via `use`.
86+
- The code may not contain unreachable code.
87+
- The backtick operator may not be used for execution of shell commands.
88+
- Class and Interface names should be unique in a project and must have a
89+
unique fully qualified name.
90+
- Methods that only call the parent method should not be defined.
91+
- Files that contain PHP code should only have PHP code and should not have
92+
any _"inline HTML"_.
93+
- There must be exactly one space after a type cast.
94+
- Constructors should be named `__construct`, not after the class.
95+
- The opening PHP tag should be the first item in the file.
96+
- Strings should not be concatenated together unless used in multiline for
97+
readability.
98+
- Loose `==` and `!=` comparison operators should not be used. Use `===`
99+
and `!==` instead.
100+
- Language constructs must be used without parentheses where possible.
101+
- Short list syntax `[...]` should be used instead of `list(...)`.
102+
- Short form of type keywords must be used. i.e. `bool` instead of
103+
`boolean`, `int` instead of `integer`, etc. The `binary` and `unset` cast
104+
operators are not allowed.
105+
- Parentheses should not be used if they can be omitted.
106+
- Semicolons `;` should not be used if they can be omitted.
107+
- Variables should be returned directly instead of assigned to a variable
108+
which is not used.
109+
- The `self` keyword should be used instead of the current class name, and
110+
should not have spaces around `::`.
111+
- Static methods should not use `$this`.
112+
- Double quote strings may only be used if they contain variables.
113+
- Strings should not be enclosed in parentheses when being echoed.
114+
- Type casts should not have whitespace inside the parentheses.
115+
- The opening brace for functions should be on a new line with no blank
116+
lines surrounding it.
117+
- The PHP constructs `echo`, `print`, `return`, `include`, `include_once`,
118+
`require`, `require_once`, and `new`, should have one space after them.
119+
- The object operator `->` should not have any spaces around it.
120+
- Semicolons should not have spaces before them.
121+
- The code should not contain superfluous whitespaces. e.g. multiple empty
122+
lines, trailing spaces, etc.
123+
124+
### Changed
125+
126+
- Nothing.
127+
128+
### Deprecated
129+
130+
- Nothing.
131+
132+
### Removed
133+
134+
- Nothing.
135+
136+
### Fixed
137+
138+
- Nothing.
139+
5140
## 1.0.0 - 2016-11-09
6141

7142
Initial public release. Incorporates rules for:

‎LICENSE.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Copyright (c) 2016, Zend Technologies USA, Inc.
1+
Copyright (c) 2016-2018, Zend Technologies USA, Inc.
22

33
All rights reserved.
44

‎README.md

Lines changed: 95 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,28 @@
1-
Zend Framework Coding Standard
2-
==============================
1+
# zend-coding-standard
32

4-
Repository with all coding standard ruleset for Zend Framework repositories.
3+
[![Build Status](https://secure.travis-ci.org/zendframework/zend-coding-standard.svg?branch=master)](https://secure.travis-ci.org/zendframework/zend-coding-standard)
54

5+
The coding standard ruleset for Zend Framework components.
66

7-
Installation
8-
------------
7+
This specification extends and expands [PSR-12](https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md),
8+
the extended coding style guide and requires adherence to [PSR-1](https://www.php-fig.org/psr/psr-1),
9+
the basic coding standard. These are minimal specifications and don't address all factors, including things like:
10+
11+
- whitespace around operators
12+
- alignment of array keys and operators
13+
- alignment of object operations
14+
- how to format multi-line conditionals
15+
- what and what not to import, and how
16+
- etc.
17+
18+
Contributors have different coding styles and so do the maintainers. During code reviews there are regularly
19+
discussions about spaces and alignments, where and when was said that a function needs to be imported. And
20+
that's where this coding standard comes in: To have internal consistency in a component and between components.
21+
22+
> Note: PSR-12 is not finalized. e.g. The `!` operator and `:` placement for return values are still under discussion.
23+
We will change these rules, and, when PSR-12 is finalized, adapt them.
24+
25+
## Installation
926

1027
1. Install the module via composer by running:
1128

@@ -22,26 +39,36 @@ Installation
2239
}
2340
```
2441

25-
3. Create file `phpcs.xml` on base path of your repository with content:
42+
3. Create file `phpcs.xml` on base path of your repository with this content:
2643

2744
```xml
2845
<?xml version="1.0"?>
29-
<ruleset name="Zend Framework Coding Standard">
30-
<rule ref="./vendor/zendframework/zend-coding-standard/ruleset.xml"/>
31-
46+
<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
47+
xsi:noNamespaceSchemaLocation="vendor/squizlabs/php_codesniffer/phpcs.xsd">
48+
49+
<arg name="basepath" value="."/>
50+
<arg name="cache" value=".phpcs-cache"/>
51+
<arg name="colors"/>
52+
<arg name="extensions" value="php"/>
53+
<arg name="parallel" value="80"/>
54+
55+
<!-- Show progress -->
56+
<arg value="p"/>
57+
3258
<!-- Paths to check -->
3359
<file>config</file>
3460
<file>src</file>
3561
<file>test</file>
62+
63+
<!-- Include all rules from the Zend Coding Standard -->
64+
<rule ref="ZendCodingStandard"/>
3665
</ruleset>
3766
```
3867

3968
You can add or exclude some locations in that file.
4069
For a reference please see: https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-ruleset.xml
4170

42-
43-
Usage
44-
-----
71+
## Usage
4572

4673
* To run checks only:
4774

@@ -50,7 +77,62 @@ Usage
5077
```
5178

5279
* To automatically fix many CS issues:
53-
80+
5481
```bash
5582
$ composer cs-fix
5683
```
84+
85+
## Ignoring parts of a File
86+
87+
> Note: Before PHP_CodeSniffer version 3.2.0, `// @codingStandardsIgnoreStart` and `// @codingStandardsIgnoreEnd` were
88+
> used. These are deprecated and will be removed in PHP_CodeSniffer version 4.0.
89+
90+
Disable parts of a file:
91+
```php
92+
$xmlPackage = new XMLPackage;
93+
// phpcs:disable
94+
$xmlPackage['error_code'] = get_default_error_code_value();
95+
$xmlPackage->send();
96+
// phpcs:enable
97+
```
98+
99+
Disable a specific rule:
100+
```php
101+
// phpcs:disable Generic.Commenting.Todo.Found
102+
$xmlPackage = new XMLPackage;
103+
$xmlPackage['error_code'] = get_default_error_code_value();
104+
// TODO: Add an error message here.
105+
$xmlPackage->send();
106+
// phpcs:enable
107+
```
108+
109+
## Development
110+
111+
> **New rules or Sniffs may not be introduced in minor or bugfix releases and should always be based on the develop
112+
branch and queued for the next major release, unless considered a bugfix for existing rules.**
113+
114+
If you want to test changes against ZendFramework components or your own projects, install your forked
115+
zend-coding-standard globally with composer:
116+
```bash
117+
$ composer global config repositories.zend-coding-standard vcs [email protected]:<FORK_NAMESPACE>/zend-coding-standard.git
118+
$ composer global require --dev zendframework/zend-coding-standard:dev-<FORKED_BRANCH>
119+
120+
# For this to work, add this to your path: ~/.composer/vendor/bin
121+
# Using `-s` prints the rules that triggered the errors so they can be reviewed easily. `-p` is for progress display.
122+
$ phpcs -sp --standard=ZendCodingStandard src test
123+
```
124+
Make sure you remove the global installation after testing from your global composer.json file!!!
125+
126+
Documentation can be previewed locally by installing [MkDocs](https://www.mkdocs.org/#installation) and run
127+
`mkdocs serve`. This will start a server where you can read the docs.
128+
129+
## Reference
130+
131+
Rules can be added, excluded or tweaked locally, depending on your preferences. More information on how to do this can
132+
be found here:
133+
134+
- [Coding Standard Tutorial](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Coding-Standard-Tutorial)
135+
- [Configuration Options](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Configuration-Options)
136+
- [Selectively Applying Rules](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-Ruleset#selectively-applying-rules)
137+
- [Customisable Sniff Properties](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Customisable-Sniff-Properties)
138+
- [Slevomat Coding Standard](https://github.com/slevomat/coding-standard)

0 commit comments

Comments
 (0)