You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/index.md
+66-93Lines changed: 66 additions & 93 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,88 +9,82 @@ seo:
9
9
type: Organisation
10
10
---
11
11
12
-
Features
13
-
-------------------------------------------
12
+
## Features
14
13
15
-
[PHPCSUtils](https://github.com/PHPCSStandards/PHPCSUtils) is a set of utilities to aid developers of sniffs for [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) (or "PHPCS" for short).
14
+
[PHPCSUtils][phpcsutils-repo] is a set of utilities to aid developers of sniffs for [PHP_CodeSniffer] (or "PHPCS" for short).
16
15
17
16
This package offers the following features:
18
17
19
18
<divid="feature-list">
20
19
21
-
### Use the latest version of PHP_CodeSniffer native utility functions.
20
+
### An ever-growing number of utility functions for use with PHP_CodeSniffer
22
21
23
-
Normally to use the latest version of PHP_CodeSniffer native utility functions, you would have to raise the minimum requirements of your external PHPCS standard.
22
+
Whether you need to split an `array` into the individual items, are trying to determine which variables are being assigned to in a `list()` or are figuring out whether a function has a DocBlock, PHPCSUtils has got you covered!
24
23
25
-
Now you won't have to anymore. This package allows you to use the latest version of those utility functions in all PHP_CodeSniffer versions from PHPCS 2.6.0 and up.
24
+
Includes improved versions of the PHPCS native utility functions and plenty of new utility functions.
26
25
27
-
### Several abstract sniff classes which your sniffs can extend.
26
+
These functions are compatible with PHPCS 3.7.1 up to PHPCS `master`.
28
27
29
-
These classes take most of the heavy lifting away for some frequently occurring sniff types.
30
-
31
-
### A collection of static properties and methods for often-used token groups.
28
+
### A collection of static properties and methods for often-used token groups
32
29
33
30
Collections of related tokens often-used and needed for sniffs.
34
31
These are additional "token groups" to compliment the ones available through the PHPCS native `PHP_CodeSniffer\Util\Tokens` class.
35
32
36
-
### An ever-growing number of utility functions for use with PHP_CodeSniffer.
37
-
38
-
Whether you need to split an `array` into the individual items, are trying to determine which variables are being assigned to in a `list()` or are figuring out whether a function has a DocBlock, PHPCSUtils has got you covered!
33
+
### Several abstract sniff classes which your sniffs can extend
39
34
40
-
Includes improved versions of the PHPCS native utility functions and plenty of new utility functions.
41
-
42
-
These functions are, of course, compatible with PHPCS 2.6.0 up to PHPCS `master`.
35
+
These classes take most of the heavy lifting away for some frequently occurring sniff types.
43
36
44
37
### Test utilities
45
38
46
39
An abstract `UtilityMethodTestCase` class to support testing of your utility methods written for PHP_CodeSniffer.
47
-
Compatible with both PHPCS 2.x as well as 3.x. Supports PHPUnit 4.x up to 9.x.
40
+
Supports PHPUnit 4.x up to 9.x.
48
41
49
-
### Backward compatibility layer
42
+
### Use the latest version of PHP_CodeSniffer native utility functions
50
43
51
-
A `PHPCS23Utils` standard which allows sniffs to work in both PHPCS 2.x and 3.x, as well as a few helper functions for external standards which still want to support both PHP_CodeSniffer 2.x as well as 3.x.
44
+
Normally to use the latest version of PHP_CodeSniffer native utility functions, you would have to raise the minimum requirements of your external PHPCS standard.
45
+
46
+
Now you won't have to anymore. This package allows you to use the latest version of those utility functions in all PHP_CodeSniffer versions from PHPCS 3.7.1 and up.
52
47
53
48
### Fully documented
54
49
55
-
To see detailed information about all the available abstract sniffs, utility functions and PHPCS helper functions, have a read through the [extensive documentation](https://phpcsutils.com/).
50
+
To see detailed information about all the available abstract sniffs, utility functions and PHPCS helper functions, have a read through the [extensive documentation][phpcsutils-web].
56
51
57
52
</div>
58
53
59
-
Minimum Requirements
60
-
-------------------------------------------
54
+
55
+
## Minimum Requirements
61
56
62
57
* PHP 5.4 or higher.
63
-
*[PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) 2.6.0+, 3.1.0+ (with the exception of PHPCS 3.5.3).
58
+
*[PHP_CodeSniffer] 3.7.1+.
64
59
* Recommended PHP extensions for optimal functionality:
65
60
- PCRE with Unicode support (normally enabled by default)
66
61
67
62
68
-
Integrating PHPCSUtils in your external PHPCS standard
69
-
-------------------------------------------
63
+
## Integrating PHPCSUtils in your external PHPCS standard
70
64
71
-
### Composer-based with a minimum PHPCS requirement of PHPCS 3.1.0
65
+
### Composer-based
72
66
73
-
If your external PHP_CodeSniffer standard only supports Composer-based installs and has a minimum PHPCS requirement of PHP_CodeSniffer 3.1.0, integrating PHPCSUtils is pretty straight forward.
67
+
If your external PHP_CodeSniffer standard only supports Composer-based installs, integrating PHPCSUtils is pretty straight forward.
74
68
75
69
Run the following from the root of your external PHPCS standard's project:
No further action needed. You can start using all the utility functions, abstract sniff classes and other features of PHPCSUtils straight away.
82
76
83
-
> :information_source: The PHPCSUtils package includes the [Composer PHPCS plugin](https://github.com/PHPCSStandards/composer-installer).
77
+
> :information_source: The PHPCSUtils package includes the [Composer PHPCS plugin].
84
78
>
85
79
> This plugin will automatically register PHPCSUtils (and your own external standard) with PHP_CodeSniffer, so you and your users don't have to worry about this anymore.
86
80
>
87
81
> :warning: Note: if your end-user installation instructions include instructions on adding a Composer PHPCS plugin or on manually registering your standard with PHPCS using the `--config-set installed_paths` command, you can remove those instructions as they are no longer needed.
88
82
>
89
83
> :information_source: As of Composer 2.2, Composer will [ask for permission](https://blog.packagist.com/composer-2-2/#more-secure-plugin-execution) to allow the Composer PHPCS plugin to execute code. For the plugin to be functional, permission needs to be granted.
90
84
> This can be done ahead of time by instructing your users to run the following command before installing your standard:
@@ -101,104 +95,83 @@ If you have your own unit test suite to test your sniffs, make sure to load the
101
95
If you intend to use the test utilities provided in the `PHPCSUtils/TestUtils` directory, make sure you also load the `vendor/phpcsstandards/phpcsutils/phpcsutils-autoload.php` file in your PHPUnit bootstrap file.
102
96
103
97
104
-
### Composer-based with a minimum PHPCS requirement of PHPCS 2.6.0
105
-
106
-
Follow the above instructions for use with PHPCS 3.x.
107
-
108
-
In addition to that, add the following to the `ruleset.xml` file of your standard(s):
109
-
```xml
110
-
<!-- Make the utility functions available in PHPCS 2.x -->
111
-
<rule ref="PHPCS23Utils"/>
112
-
```
113
-
114
-
> :information_source: The `PHPCS23Utils` "standard" does not add any real sniffs, it only makes sure that the Utility functions will work in PHPCS 2.x as well.
115
-
116
-
#### Running your unit tests
98
+
## Frequently Asked Questions
117
99
118
-
If your standard supports both PHPCS 2.x as well as 3.x, you are bound to already have a PHPUnit `bootstrap.php` file in place.
100
+
<divclass="faq">
119
101
120
-
To allow the unit tests to find the relevant files for PHPCSUtils, make sure that the bootstrap loads both the Composer `vendor/autoload.php` file, as well as the `vendor/phpcsstandards/phpcsutils/phpcsutils-autoload.php` file.
121
-
122
-
123
-
124
-
Frequently Asked Questions
125
-
-------
126
-
127
-
<divid="faq">
128
-
129
-
#### Q: How does this all work without an external standard needing to register an autoloader?
102
+
### Q: How does this all work without an external standard needing to register an autoloader?
130
103
131
104
A: As PHPCSUtils is registered with PHPCS as an external standard and PHPCSUtils complies with the naming requirements of PHPCS, the PHPCS native autoloader will automatically take care of loading the classes used from PHPCSUtils.
132
105
133
-
#### Q: What does the `PHPCS23Utils` standard do?
134
-
135
-
A: All the `PHPCS23Utils` standard does is load the `phpcsutils-autoload.php` file.
136
-
137
-
PHPCS 3.x uses namespaces, while PHPCS 2.x does not. The `phpcsutils-autoload.php` file creates `class_alias`-es for the most commonly used PHPCS classes, including all PHPCS classes used by PHPCSUtils. That way, both your external standard as well as PHPCSUtils can refer to the PHPCS 3.x class names and the code will still work in PHPCS 2.x.
138
-
139
-
#### Q: Why is PHP_CodeSniffer 3.5.3 not supported?
140
-
141
-
A: The backfill for PHP 7.4 numeric literals with underscores in PHP_CodeSniffer 3.5.3 is broken and there is no way to reliably provide support for anything to do with numbers or `T_STRING` tokens when using PHP_CodeSniffer 3.5.3 as the tokens returned by the tokenizer are unpredictable and unreliable.
142
-
143
-
The backfill was fixed in PHP_CodeSniffer 3.5.4.
144
-
145
-
#### Q: Any other problematic PHPCS versions?
146
-
147
-
A: Well, the arrow function backfill which was added in PHPCS 3.5.3 is still causing problems. In a very limited set of circumstances, it will even hang the Tokenizer. A fix for [one particular such problem](https://github.com/squizlabs/php_codesniffer/issues/2926) has been committed to `master`, but is not (yet) in a released version. It is expected to be released in PHP_CodeSniffer 3.5.6.
148
-
149
-
As the Tokenizer hanging is a problem unrelated to PHPCSUtils and not something which can be mitigated from within PHPCSUtils in any conceivable way, PHPCSUtils won't block installation in combination with PHPCS 3.5.4 and 3.5.5.
150
-
151
-
There are several other issues which can not be worked around, like scope closers being set incorrectly and throwing the scope setting off for the rest of the file, so not withstanding that PHPCSUtils can work around a lot of issues, it is still highly recommended to advise your end-users to always use the latest version of PHPCS for the most reliable results.
152
-
153
-
#### Q: Does using PHPCSUtils have any effect on the PHPCS native sniffs?
106
+
### Q: Does using PHPCSUtils have any effect on the PHPCS native sniffs?
154
107
155
108
A: No. PHPCSUtils will only work for those sniffs which explicitly use the PHPCSUtils functionality.
156
109
157
110
If your standard includes both PHPCS native sniffs as well as your own sniffs, your own sniffs can benefit from the back-compat layer offered by PHPCSUtils, as well as from the additional utility functions. However, the PHPCS native sniffs will not receive those benefits, as PHPCS itself does not use PHPCSUtils.
158
111
159
-
####Q: Do the utilities work with javascript/CSS files?
112
+
### Q: Do the utilities work with javascript/CSS files?
160
113
161
-
A: JS/CSS support will be removed from PHP_CodeSniffer in PHPCS 4.x.
162
-
While at this time, some of the utilies_may_ work with JS/CSS files, PHPCSUtils does not offer formal support for JS/CSS sniffing with PHP_CodeSniffer and will stop any existing support once PHPCS 4.x has been released.
114
+
A: JS/CSS support will be removed from `PHP_CodeSniffer` in PHPCS 4.x.
115
+
While at this time, some of the utilities_may_ work with JS/CSS files, PHPCSUtils does not offer formal support for JS/CSS sniffing with `PHP_CodeSniffer` and will stop any existing support once PHPCS 4.x has been released.
163
116
164
-
####Q: Are all file encodings supported?
117
+
### Q: Are all file encodings supported?
165
118
166
119
A: No. The UTF-8 file encoding is the only officially supported encoding. Support for other encodings may incidentally work, but is not officially supported.
167
120
168
121
> **It is recommended to advise your users to save their files as UTF-8 encoded for the best results.**
169
122
170
-
PHP_CodeSniffer 3.x will default to UTF-8 as the expected file encoding.
171
-
If your standard supports PHP_CodeSniffer 2.x, it is recommended to set the expected encoding in the ruleset to `utf-8`, like so: `<arg name="encoding" value="utf-8"/>` or to advise users to use the CLI option `--encoding=utf-8`.
123
+
Note: `PHP_CodeSniffer` 3.x defaults to UTF-8 as the expected file encoding.
124
+
125
+
</div>
126
+
172
127
128
+
## Potential Support Questions from your End-Users
173
129
174
-
Potential Support Questions from your End-Users
175
-
-------
130
+
<divclass="faq">
176
131
177
-
####Q: A user reports a fatal "class not found" error for a class from PHPCSUtils.
132
+
### Q: A user reports a fatal "class not found" error for a class from PHPCSUtils
178
133
179
134
1. Check that the version of PHPCSUtils the user has installed complies with the minimum version of PHPCSUtils your standard requires. If not, they will need to upgrade.
180
135
2. If the version is correct, this indicates that the end-user does not have PHPCSUtils installed and/or registered with PHP_CodeSniffer.
181
136
- Please review your standard's installation instructions to make sure that PHPCSUtils will be installed when those are followed.
182
137
- Inform the user to install PHPCSUtils and register it with PHP_CodeSniffer.
183
138
139
+
---
140
+
184
141
> :bulb:**Pro-tip**: if you want to prevent the fatal error and show a _friendlier_ error message instead, add `<rule ref="PHPCSUtils"/>` to your standard's `ruleset.xml` file.
185
142
>
186
-
> With that in place, PHP_CodeSniffer will show a _"ERROR: the "PHPCSUtils" coding standard is not installed."_ message if PHPCSUtils is missing as soon as the ruleset loading is finished.
143
+
> With that in place, `PHP_CodeSniffer` will show a _"ERROR: the "PHPCSUtils" coding standard is not installed."_ message if PHPCSUtils is missing as soon as the ruleset loading is finished.
144
+
145
+
---
187
146
188
147
> :bulb:**Pro-tip**: provide upgrade instructions for your end-users. For Composer-based installs, those should look like this:
0 commit comments