Skip to content

Commit 1b8c73e

Browse files
gmazzapgmazzap
committed
Improve docs
1 parent 0d5ee82 commit 1b8c73e

File tree

2 files changed

+221
-71
lines changed

2 files changed

+221
-71
lines changed

‎README.md

Lines changed: 32 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ It means they can be installed by adding the entry to composer.json `require-dev
1212
```json
1313
{
1414
"require-dev": {
15-
"inpsyde/php-coding-standards": "^0.9"
15+
"inpsyde/php-coding-standards": "~0.10.0"
1616
}
1717
}
1818
```
@@ -114,6 +114,15 @@ See https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.
114114

115115
The tree of used rules are listed in the `/docs/rules-list/wordpress.md` file in this repo.
116116

117+
## PHPCompatibility
118+
119+
See https://github.com/wimg/PHPCompatibility.
120+
121+
It allows to analyse code for compatibility with higher and lower versions of PHP.
122+
The default target version is PHP 7.0+.
123+
124+
Target version can be changed via custom `phpcs.xml`.
125+
117126

118127
## Generic Rules
119128

@@ -127,76 +136,28 @@ The tree of used rules are listed in the `/docs/rules-list/generic.md` file in t
127136

128137
## Custom Rules
129138

130-
Few custom rules are also in use.
131-
Customs rules are:
132-
133-
- Enforce argument type declaration, with few exception (e.g. hook callbacks or `ArrayAccess` methods)
134-
- Ensure that any assignment inside conditions in wrapped in parenthesis
135-
- Disallow short open PHP tag
136-
- Use minimum 3 chars for names (with a few exclusions)
137-
- No public class properties
138-
- Max 50 lines per function/method, excluding blank lines and comments-only lines.
139-
- Ensure that actions callbacks do not return anything, while filter callbacks return something.
140-
- Max 100 chars per line, excluding leading indent size and long string inWP translation functions
141-
- Discourage usage of getters and setters.
142-
- Discourage usage of `else`.
143-
- Discourage usage of `define` where `const` is preferable.
144-
- Discourage usage of more than 10 properties per class.
145-
- Enforce return type declaration, with few exceptions (e.g. hook callbacks or `ArrayAccess` methods)
146-
- Check PSR-4 compliance
147-
148-
The tree of used rules are listed in the `/docs/rules-list/custom.md` file in this repo.
149-
150-
### Notes & Configuration
151-
152-
#### Skip `Inpsyde.CodeQuality.ReturnTypeDeclaration.NoReturnType` via doc bloc
153-
154-
As of v0.9, when there's no return type declared for a function, but it has a docbloc like:
155-
`@return {$type}|null` and the function _actually_ contains both `null` and not-null return
156-
points **no** warning is shown.
157-
However, if min PHP version is set to 7.1 via php-compatibility `testVersion` config, the warning
158-
**is** shown, because in PHP 7.1 there's the availability for nullable return types.
159-
Also note that the warning **is** shown in case:
160-
- the `@return` docbloc declares more than one not-null types, e.g. `@return Foo|Bar|null`
161-
- the `@return` docbloc types contains "mixed", e.g. `@return mixed|null`.
162-
163-
164-
#### PSR-4 Configuration
165-
`Inpsyde.CodeQuality.Psr4` rule needs some configuration to check namespace and
166-
class file paths.
167-
Without configuration the only thing the sniff does is to check that class name and file name match.
168-
The needed configuration mimics the PSR-4 configuration in `composer.json`.
169-
Assuming a `composer.json` like:
170-
```json
171-
{
172-
"autoload": {
173-
"psr-4": {
174-
"Inpsyde\\Foo\\": "src/",
175-
"Inpsyde\\Foo\\Bar\\Baz\\": "baz/"
176-
}
177-
}
178-
}
179-
```
180-
the rule configuration should be:
181-
```xml
182-
<rule ref="Inpsyde.CodeQuality.Psr4">
183-
<properties>
184-
<property name="psr4" type="array" value="Inpsyde\Foo=>src,Inpsyde\Foo\Bar\Baz=>baz" />
185-
</properties>
186-
</rule>
187-
```
188-
Please note that when a PSR-4 configuration is given, *all* autoloadable entities (classes/interfaces/trait)
189-
are checked to be compliant.
190-
If there are entities in the sniffer target paths that are not PSR-4 compliant (e.g. loaded via classmap
191-
or not autoloaded at all) those should be excluded via `exclude` property, e.g.
192-
```xml
193-
<rule ref="Inpsyde.CodeQuality.Psr4">
194-
<properties>
195-
<property name="psr4" type="array" value="Inpsyde\SomePlugin=>src" />
196-
<property name="exclude" type="array" value="Inpsyde\ExcludeThis,Inpsyde\AndThis" />
197-
</properties>
198-
</rule>
199-
```
139+
Some custom rules are also in use. They are:
140+
141+
| Sniff name | Description | Has Config | Has Notes |
142+
|:-----------|:------------|:----------:|:---------:|
143+
| `ArgumentTypeDeclarationSniff`|Enforce argument type declaration, with few exception (e.g. hook callbacks or `ArrayAccess` methods)|||
144+
| `AssignmentInsideConditionSniff`|Ensure that any assignment inside conditions in wrapped in parenthesis|||
145+
| `DisallowShortOpenTagSniff`|Disallow short open PHP tag (short echo tag allowed).|||
146+
| `ElementNameMinimalLengthSniff`|Use minimum 3 chars for names (with a few exclusions)|✓||
147+
| `ForbiddenPublicPropertySniff`|No public class properties|||
148+
| `FunctionLengthSniff`|Max 50 lines per function/method, excluding blank lines and comments-only lines.|✓||
149+
| `HookClosureReturnSniff`|Ensure that actions callbacks do not return anything, while filter callbacks return something.|||
150+
| `LineLengthSniff`|Max 100 chars per line, excluding leading indent space and long string in WP translation functions|✓||
151+
| `NoAccessorsSniff`|Discourage usage of getters and setters.|||
152+
| `NoElseSniff`|Discourage usage of `else`.|||
153+
| `NoTopLevelDefineSniff`|Discourage usage of `define` where `const` is preferable.|||
154+
| `PropertyPerClassLimitSniff`|Discourage usage of more than 10 properties per class.|✓||
155+
| `Psr4Sniff`|Check PSR-4 compliance|✓||
156+
| `ReturnTypeDeclarationSniff`|Enforce return type declaration, with few exceptions (e.g. hook callbacks or `ArrayAccess` methods)||✓|
157+
158+
For **notes and configuration** see `/docs/rules-list/inpsyde-rules-configuration.md` file in this repo.
159+
160+
The tree of rules are listed in the `/docs/rules-list/custom.md` file in this repo.
200161

201162
-------------
202163

‎docs/inpsyde-rules-configuration.md

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Inpsyde Rules Configuration
2+
3+
## Inpsyde.CodeQuality.ElementNameMinimalLength
4+
5+
It is possible to configure the minimal length required to don't trigger any warning (by default 3).
6+
That is possible via `minLength` property, e.g.:
7+
8+
```xml
9+
<rule ref="Inpsyde.CodeQuality.ElementNameMinimalLengthSniff">
10+
<properties>
11+
<property name="minLength" value="5" />
12+
</properties>
13+
</rule>
14+
```
15+
16+
It is also possible to configure the whitelist of allowed names with less than 3 (or whatever
17+
the minimal length is configured to) characters.
18+
By default the whitelisted names are:
19+
- 'i'
20+
- 'id'
21+
- 'to'
22+
- 'up'
23+
- 'ok'
24+
- 'no'
25+
- 'go'
26+
- 'it'
27+
- 'db'
28+
but they can be configured via `allowedShortNames` config, e.g.:
29+
30+
```xml
31+
<rule ref="Inpsyde.CodeQuality.ElementNameMinimalLengthSniff">
32+
<properties>
33+
<property name="allowedShortNames" type="array" value="id,db,x,y" />
34+
</properties>
35+
</rule>
36+
```
37+
38+
39+
-----
40+
41+
42+
## Inpsyde.CodeQuality.FunctionLength
43+
44+
It is possible to configure the maximum allowed lines to don't trigger any warning (by default 50).
45+
That is possible via `maxLength` property, e.g.:
46+
47+
```xml
48+
<rule ref="Inpsyde.CodeQuality.FunctionLengthSniff">
49+
<properties>
50+
<property name="maxLength" value="20" />
51+
</properties>
52+
</rule>
53+
```
54+
55+
By default, in the counting are excluded:
56+
- white lines
57+
- comments
58+
- doc bloc _inside_ function block
59+
60+
It is possible to include any/all the lines of those kinds via 3 flags (by default all `true`):
61+
62+
- `ignoreBlankLines`
63+
- `ignoreComments`
64+
- `ignoreDocBlocks`
65+
66+
e.g.:
67+
68+
```xml
69+
<rule ref="Inpsyde.CodeQuality.FunctionLengthSniff">
70+
<properties>
71+
<property name="ignoreBlankLines" value="true" />
72+
<property name="ignoreDocBlocks" value="false" />
73+
<property name="ignoreComments" value="false" />
74+
</properties>
75+
</rule>
76+
```
77+
78+
-----
79+
80+
81+
## Inpsyde.CodeQuality.LineLength
82+
83+
It is possible to configure the maximum allowed characters per line to don't trigger any warning
84+
(by default 100).
85+
That is possible via `lineLimit` property, e.g.:
86+
87+
```xml
88+
<rule ref="Inpsyde.CodeQuality.LineLengthSniff">
89+
<properties>
90+
<property name="lineLimit" value="120" />
91+
</properties>
92+
</rule>
93+
```
94+
95+
-----
96+
97+
98+
## Inpsyde.CodeQuality.PropertyPerClassLimit
99+
100+
It is possible to configure the maximum allowed number of property per class to don't trigger any
101+
warning (by default 10).
102+
That is possible via `maxCount` property, e.g.:
103+
104+
```xml
105+
<rule ref="Inpsyde.CodeQuality.PropertyPerClassLimit">
106+
<properties>
107+
<property name="maxCount" value="120" />
108+
</properties>
109+
</rule>
110+
```
111+
112+
113+
## Inpsyde.CodeQuality.Psr4
114+
115+
`Inpsyde.CodeQuality.Psr4` rule needs some configuration to check namespace and
116+
class file paths.
117+
Without configuration the only thing the sniff does is to check that class name and file name match.
118+
The needed configuration mimics the PSR-4 configuration in `composer.json`.
119+
Assuming a `composer.json` like:
120+
121+
```json
122+
{
123+
"autoload": {
124+
"psr-4": {
125+
"Inpsyde\\Foo\\": "src/"
126+
}
127+
},
128+
"autoload-dev": {
129+
"psr-4": {
130+
"Inpsyde\\Foo\\Tests\\": "tests/php/"
131+
}
132+
}
133+
}
134+
```
135+
the rule configuration should be:
136+
137+
```xml
138+
<rule ref="Inpsyde.CodeQuality.Psr4">
139+
<properties>
140+
<property name="psr4" type="array" value="Inpsyde\Foo=>src,Inpsyde\Foo\Tests=>tests/php" />
141+
</properties>
142+
</rule>
143+
```
144+
145+
Please note that when a PSR-4 configuration is given, *all* autoloadable entities (classes/interfaces/trait)
146+
are checked to be compliant.
147+
If there are entities in the sniffer target paths that are not PSR-4 compliant (e.g. loaded via classmap
148+
or not autoloaded at all) those should be excluded via `exclude` property, e.g.:
149+
150+
```xml
151+
<rule ref="Inpsyde.CodeQuality.Psr4">
152+
<properties>
153+
<property name="psr4" type="array" value="Inpsyde\SomePlugin=>src" />
154+
<property name="exclude" type="array" value="Inpsyde\ExcludeThis,Inpsyde\AndThis" />
155+
</properties>
156+
</rule>
157+
```
158+
159+
Note that anything that *starts with* any of the values in the `exclude` array will be excluded.
160+
161+
E.g. by excluding `Inpsyde\ExcludeThis` things like `Inpsyde\ExcludeThis\Foo` and
162+
`Inpsyde\ExcludeThis\Bar\Baz` will be excluded as well.
163+
164+
To make sure what's excluded is a namespace, and not a class with same name, just use `\` as last
165+
character.
166+
167+
-----
168+
169+
170+
## Inpsyde.CodeQuality.ReturnTypeDeclaration
171+
172+
When there's no return type declared for a function, but it has a docbloc like:
173+
174+
```php
175+
/**
176+
* return {$type}|null`
177+
*/
178+
```
179+
and the function _actually_ contains both `null` and not-null return points **no** warning is shown.
180+
181+
However, if a minimum PHP version is set via [PHPCompatibility](https://github.com/wimg/PHPCompatibility)
182+
`testVersion` config, and it is **7.1 or higher**, the warning **is** shown, because in PHP 7.1
183+
there's the availability for nullable return types which should be used in that case.
184+
185+
Also note that the warning **is** shown in case:
186+
- the `@return` docbloc declares more than one not-null types, e.g. `@return Foo|Bar|null`
187+
- the `@return` docbloc types contains "mixed", e.g. `@return mixed|null`.
188+
189+
-----

0 commit comments

Comments
 (0)