Skip to content

Commit 35d344c

Browse files
committed
📚 Add Readme with installation and usage instructions
Add badges, installation instructions, information on the ruleset and how to use it, a contributing section and license information to the Readme.
1 parent 3315305 commit 35d344c

File tree

1 file changed

+98
-0
lines changed

1 file changed

+98
-0
lines changed

README.md

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
PHPCSDevCS for developers of PHP_CodeSniffer sniffs
2+
=====================================================
3+
4+
[![Latest Stable Version](https://poser.pugx.org/phpcsstandards/phpcsdevcs/v/stable)](https://packagist.org/packages/phpcsstandards/phpcsdevcs)
5+
[![Release Date of the Latest Version](https://img.shields.io/github/release-date/PHPCSStandards/PHPCSDevCS.svg?maxAge=1800)](https://github.com/PHPCSStandards/PHPCSDevCS/releases)
6+
:construction:
7+
[![Latest Unstable Version](https://img.shields.io/badge/unstable-dev--master-e68718.svg?maxAge=2419200)](https://packagist.org/packages/phpcsstandards/phpcsdevcs#dev-master)
8+
[![Travis Build Status](https://travis-ci.com/PHPCSStandards/PHPCSDevCS.svg?branch=master)](https://travis-ci.com/PHPCSStandards/PHPCSDevCS)
9+
[![Last Commit to Unstable](https://img.shields.io/github/last-commit/PHPCSStandards/PHPCSDevCS/master.svg)](https://github.com/PHPCSStandards/PHPCSDevCS/commits/master)
10+
11+
[![Minimum PHP Version](https://img.shields.io/packagist/php-v/phpcsstandards/phpcsdevcs.svg?maxAge=3600)](https://packagist.org/packages/phpcsstandards/phpcsdevcs)
12+
[![License: LGPLv3](https://poser.pugx.org/phpcsstandards/phpcsdevcs/license)](https://github.com/PHPCSStandards/PHPCSDevCS/blob/master/LICENSE)
13+
![Awesome](https://img.shields.io/badge/awesome%3F-yes!-brightgreen.svg)
14+
15+
16+
This is an external ruleset for [PHP CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) intended for use by sniff developers.
17+
18+
* [Installation](#installation)
19+
+ [Composer Project-based Installation](#composer-project-based-installation)
20+
+ [Composer Global Installation](#composer-global-installation)
21+
* [PHPCSDev ruleset for sniff repos](#phpcsdev-ruleset-for-sniff-repos)
22+
+ [Using the ruleset from the command line](#using-the-ruleset-from-the-command-line)
23+
+ [Using the ruleset from within a project based ruleset](#using-the-ruleset-from-within-a-project-based-ruleset)
24+
* [Contributing](#contributing)
25+
* [License](#license)
26+
27+
28+
Installation
29+
-------------------------------------------
30+
31+
### Composer Project-based Installation
32+
33+
Run the following from the root of your project:
34+
```bash
35+
composer require --dev phpcsstandards/phpcsdevcs:"^1.0"
36+
```
37+
38+
### Composer Global Installation
39+
40+
If you work on several different sniff repos, you may want to install this toolset globally:
41+
```bash
42+
composer global require --dev phpcsstandards/phpcsdevcs:"^1.0"
43+
```
44+
45+
Composer will automatically install dependencies and register the PHPCSDev and other external standards with PHP_CodeSniffer using the [DealerDirect Composer PHPCS plugin](https://github.com/Dealerdirect/phpcodesniffer-composer-installer/).
46+
47+
48+
PHPCSDev ruleset for sniff repos
49+
------------------------------
50+
51+
Once this project is installed, you will see a new `PHPCSDev` ruleset in the list of installed standards when you run `phpcs -i`.
52+
53+
**Important: This ruleset currently requires PHP_CodeSniffer >= `3.5.0+`.**
54+
55+
> As sniffs developers will mostly work with the latest version of PHP_CodeSniffer, this shouldn't cause any problems.
56+
>
57+
> Similarly, the CS check in automated CI runs should normally be run on a high PHPCS version for the best results.
58+
59+
The `PHPCSDev` standard can be used by sniff developers to check the code style of their sniff repo code.
60+
61+
Often, sniff repos will use the code style of the standard they are adding. However, not all sniff repos are actually about code style.
62+
63+
So for those repos which need a basic standard which will still keep their code-base consistent, this standard should be useful.
64+
65+
The standard checks your code against the following:
66+
* Compliance with [PSR-12](https://www.php-fig.org/psr/psr-12/), with a few exceptions.
67+
* Use of camelCase variable and function names.
68+
* Use of normalized arrays.
69+
* All files, classes, functions and properties are documented with a docblock and contain the minimally needed information.
70+
* A number of arbitrary additional code style and QA checks.
71+
* PHP cross-version compatibility, while allowing for the tokens back-filled by PHPCS itself.
72+
Note: for optimal results, the project custom ruleset should set the `testVersion` config variable.
73+
This is not done by default as config variables are currently [difficult](https://github.com/squizlabs/PHP_CodeSniffer/issues/2197) [to overrule](https://github.com/squizlabs/PHP_CodeSniffer/issues/1821).
74+
75+
The ruleset can be used like any other ruleset and specific sniffs and settings can be added to or overruled from a custom project based ruleset.
76+
77+
### Using the ruleset from the command line
78+
```bash
79+
phpcs . --standard=PHPCSDev
80+
```
81+
82+
### Using the ruleset from within a project based ruleset
83+
84+
Add the following line to your project's `phpcs.xml.dist` file:
85+
```xml
86+
<rule ref="PHPCSDev"/>
87+
```
88+
89+
90+
Contributing
91+
-------
92+
Contributions to this project are welcome. Just clone the repo, branch off from `master`, make your changes, commit them and send in a pull request.
93+
94+
If unsure whether the changes you are proposing would be welcome, open an issue first to discuss your proposal.
95+
96+
License
97+
-------
98+
This code is released under the GNU Lesser General Public License (LGPLv3). For more information, visit http://www.gnu.org/copyleft/lesser.html

0 commit comments

Comments
 (0)