Skip to content

Commit 69618c8

Browse files
mrewersmrewers
committed
docs: add a readme and license
1 parent 5968235 commit 69618c8

File tree

5 files changed

+162
-1
lines changed

5 files changed

+162
-1
lines changed

‎CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Change Log
2+
3+
**All notable changes to this project will be documented in this file.**
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6+
7+
## [Unreleased](https://github.com/IIP-Design/wp-elasticsearch-feeder/compare/1.0.0...HEAD)
8+
9+
## [v1.0.0](https://github.com/IIP-Design/wp-elasticsearch-feeder/releases/tag/1.0.0) (2022-03-31 - Initial Release)
10+
11+
**Added:**
12+
13+
- Base ruleset modelled on the WordPress coding standards but excluding WordPress specific rules
14+
- WordPress ruleset that extends and modifies the default WordPress coding standards
15+
- Documentation on installation and basic usage

‎GPA-Lab/ruleset.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<?xml version="1.0"?>
22
<ruleset
3-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
43
name="GPA Lab Standard"
4+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
55
xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/squizlabs/PHP_CodeSniffer/master/phpcs.xsd"
66
>
77

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2022 U.S. Department of State, Bureau of Global Public Affairs, Digital Lab
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# GPA Lab PHP Code Standards
2+
3+
This collection of PHP CodeSniffer rules helps ensure consistency across PHP projects developed and managed by the GPA Lab. It helps to maintain a high level of code quality and standardizes the team's approach to PHP projects.
4+
5+
The repository contains two ruleset:
6+
7+
- [GPA Lab Standard](#general-projects) - Base rules applicable to any PHP project
8+
- [GPA Lab WordPress](#wordpress-projects) - An extension of the WordPress Coding Standards ruleset for use when developing WordPress plugins/themes
9+
10+
## Rulesets
11+
12+
### General Projects
13+
14+
The GPA Lab Standard ruleset is a general set of rule applicable to any PHP project. In order to utilize these standards, you will need to install the following dependencies into your project:
15+
16+
- `gpalab/coding-standards` - The ruleset defined in this repository.
17+
- `squizlabs/php_codesniffer` - A tool that conducts static code analysis in order to identify and fix problems.
18+
- `dealerdirect/phpcodesniffer-composer-installer` - A Composer plugin that handles the registration of standards with PHP CodeSniffer.
19+
20+
The recommended way to install these dependencies is to add them to the development requirements listed in your project's `composer.json` file. The result will look something like this:
21+
22+
```json
23+
{
24+
"name": "my-project",
25+
"require-dev": {
26+
"gpalab/coding-standards": "v1.0.0",
27+
"squizlabs/php_codesniffer": "^3.6.2",
28+
"dealerdirect/phpcodesniffer-composer-installer": "^v0.7.1"
29+
}
30+
}
31+
```
32+
33+
With this done, run `composer install` to install the dependencies to your project.
34+
35+
Once installed, you will need to identify which ruleset PHP Code Sniffer should utilize. The easiest way to do so is by adding a PHP Code Sniffer configuration file such as `.phpcs.xml` to the root of your project. In this file, use the `rule` tag to reference the GPA Lab standard ruleset using the key `GPA-Lab`. The result will look something like this:
36+
37+
```xml
38+
<?xml version="1.0"?>
39+
<ruleset name="My Project">
40+
41+
<!-- List of files/directories to check. -->
42+
<file>*.php</file>
43+
44+
<!-- Exclude vendor files from testing. -->
45+
<exclude-pattern>*/vendor</exclude-pattern>
46+
47+
<!-- Load the Standard GPA Lab ruleset -->
48+
<rule ref="GPA-Lab" />
49+
50+
</ruleset>
51+
```
52+
53+
### WordPress Projects
54+
55+
This repository also contains a ruleset for use with WordPress projects (such as plugins and themes). In addition to the PHP best practice and style rules in the standard ruleset, this ruleset includes Wordpress-specific rules and best practices.
56+
57+
The process for installing the WordPress ruleset is largely the same. However, since we are extending the WordPress ruleset, you will also need to install the following peer dependencies: `php-compatibility`, `phpcompatibility-wp`, and `wp-coding-standards/wpcs`. The resulting composer.json file will look like this:
58+
59+
```json
60+
{
61+
"name": "my-wordpress-project",
62+
"require-dev": {
63+
"gpalab/coding-standards": "v1.0.0",
64+
"squizlabs/php_codesniffer": "^3.6.2",
65+
"dealerdirect/phpcodesniffer-composer-installer": "^v0.7.1",
66+
"phpcompatibility/php-compatibility": "*",
67+
"phpcompatibility/phpcompatibility-wp": "^2.1.3",
68+
"wp-coding-standards/wpcs": "^2.3.0"
69+
}
70+
}
71+
```
72+
73+
Your PHP Code Sniffer configuration file will look the same, except that you should use the `GPA-Lab-WordPress` reference key rather than the `GPA-Lab` key.
74+
75+
```xml
76+
<?xml version="1.0"?>
77+
<ruleset name="My WordPress Project">
78+
79+
<!-- List of files/directories to check. -->
80+
<file>*.php</file>
81+
82+
<!-- Exclude vendor files from testing. -->
83+
<exclude-pattern>*/vendor</exclude-pattern>
84+
85+
<!-- Load the Standard GPA Lab ruleset -->
86+
<rule ref="GPA-Lab-WordPress" />
87+
88+
</ruleset>
89+
```
90+
91+
## Usage
92+
93+
### CI
94+
95+
Often times, the easiest way to run PHP Code Sniffer in a continuous integration context is by adding an NPM script to execute the test. For example:
96+
97+
```json
98+
"lint:PHP": "./vendor/bin/phpcs -n",
99+
```
100+
101+
This script requires that PHP Code Sniffer is installed into the project's vendor directory, so make sure that you run `composer install` or `composer update` before executing this command.
102+
103+
_Note:_ The `-n` flag indicates that warnings should be omitted.
104+
105+
### VSCode
106+
107+
There are a number of ways to integrate PHP Code Sniffer into your local IDE. For VSCode, we have found that the combination of these two extensions works best:
108+
109+
- [PHP Intelephense](https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client)
110+
- [PHP Sniffer & Beautifier](https://marketplace.visualstudio.com/items?itemName=ValeryanM.vscode-phpsab)
111+
112+
## Thanks
113+
114+
This project owes a huge debt to the [WordPress Coding Standards](https://github.com/WordPress/WordPress-Coding-Standards) project, which provided both inspiration and a sane set of defaults on which we were able to build.

‎composer.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,17 @@
22
"name": "gpalab/coding-standards",
33
"type": "phpcodesniffer-standard",
44
"description": "PHP_CodeSniffer rules (sniffs) to enforce GPA Lab coding conventions",
5+
"license": "MIT",
6+
"authors": [
7+
{
8+
"name": "U.S. Department of State, Bureau of Global Public Affairs Digital Lab",
9+
"email": "[email protected]"
10+
},
11+
{
12+
"name": "Marek Rewers",
13+
"role": "Developer"
14+
}
15+
],
516
"keywords": [
617
"phpcs",
718
"standards",

0 commit comments

Comments
 (0)