Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/district09/php_package_qa-drupal

District09 QA for PHP
https://github.com/district09/php_package_qa-drupal

d09check22 web

Last synced: about 2 months ago
JSON representation

District09 QA for PHP

Awesome Lists containing this project

README

        

# Quality Assurance - Drupal

This package provides a set of Quality Assurance tools and configuration files
for Drupal websites and extensions (modules, themes or profiles).

[![Build Status Master][travis-badge]][travis-link]
[![Maintainability][codeclimate-maint-badge]][codeclimate-maint-link]
[![License][license-badge]][license-link]

## Requirements

* [Composer](https://getcomposer.org)

## Versions

The versions support different PHP & Drupal versions:

* Until 1.4.x : PHP 7.3 or 7.4 & Drupal 8.8+ or 9+.
* From 1.5.x : PHP 7.4 & Drupal 9.1 or higher.
* From 1.7.X : PHP 7.4, 8.X & DRUPAL 9.3 or higher.
* From 3.0.x : PHP 8.3, DRUPAL 10.3 or higher.

## Installation

The installation depends on the type of project: website or Drupal module.

### Drupal website

Add the `grumphp` entry to the `extra` section of your `composer.json`.

```json
"grumphp": {
"config-default-path": "vendor/digipolisgent/qa-drupal/configs/grumphp-site.yml"
}
```

Add the qa-drupal package as dev requirement:

```bash
composer require --dev digipolisgent/qa-drupal:^1.5
```

### Drupal module

Add the `grumphp` entry to the `extra` section of your `composer.json`.

```json
"grumphp": {
"config-default-path": "vendor/digipolisgent/qa-drupal/configs/grumphp-extension.yml"
}
```

Add the qa-drupal package as dev requirement:

```bash
composer require --dev digipolisgent/qa-drupal:^1.5
```

## Configuration

### General

If required you can extend or override the provided configuration file of a
task. Simply create the matching configuration file in the root of your project.

For example, to override the provided `phpcs.xml` file you can either create a
`phpcs.xml` or `phpcs.local.xml` file.

Note that the `.local.` files should only be used for changes that shouldn't be
committed. Exclude them in `.gitignore`:

```gitignore
/*.local.*
```

Yaml and Neon files will extend (merged into) the provided configuration file by
default. Create a `.env` or `.env.local` file and add following contents to
change this behaviour:

```
[FILENAME]_SKIP_[TYPE]=1
```

Wherein `[FILENAME]` matches the configuration filename and `[TYPE]` is either:

- `LOCAL` to skip for example your `phpstan.local.neon` file.
- `PROJECT` to skip for example your `phpstan.neon` file.
- `PACKAGE_TYPE` to skip for example the provided `phpstan-extension.neon` or
`phpstan-site.neon` file.
- `PACKAGE_GLOBAL` to skip for example the provided `phpstan.neon` file.

Other file types cannot be merged and will just override all other less specific
files.

### PHPStan in deprecations only mode

Create a `phpstan.neon` file and add following contents to ignore everything
except deprecations:

```
parameters:
customRulesetUsed: true
ignoreErrors:
- '#^(?:(?!deprecated).)*$#'
```

### Ignore automatically created config files

Some GrumPHP tasks require a config file. These are automatically creacted, from
the examples within vendor/qa-drupal/config or by the project specific files
within your website or drupal module root directory. The generated files are
also stored in the same website/module root. You can recognize these files by
the `.qa-drupal.` suffix.

**These files should not be committed!** Add them to the `.gitignore` file:

```gitignore
/*.qa-drupal.*
```

### Ignore PHPUnit build files

When the PHPUnit task runs, coverage report files are stored into the `build`
directory located in the root of your website/project. Add this file to the
`.gitignore` file:

```gitignore
/build
/.phpunit.result.cache
```

### Run PHPUnit locally without coverage

Running PHPUnit with coverage report is time-consuming. You can locally speed up
PHPUnit by copying the generated `phpunit.qa-drupal.xml` file to
`phpunit.local.xml` and remove the `` section from it.

## Run GrumPHP

GrumPHP will automatically run all tasks on the changed code on git commit and
push.

You can run all tasks at once:

```bash
vendor/bin/grumphp
```

Or you can run one or more specific tasks manually by running:

```bash
vendor/bin/grumphp --tasks phpcs,phpmd
vendor/bin/grumphp --tasks phpunit
```

## PHPStorm

PHPStorm requires config files for PHP_CodeSniffer, PHP Mess Detector & PhpUnit.
Run the grumphp command at least once (successfully) to generate these files.

The files will be created as:

- `phpcs.qa-drupal.xml` : PHP_CodeSniffer config file.
- `phpmd.qa-drupal.xml` : PHP Mess Detector config file.
- `phpunit.qa-drupal.xml` : PHPUnit config file.

Configure the paths to these files in PHPStorm:

* Editor > Inspections > PHP > Quality tools > PHP Mess Detector validation
Add `phpmd.qa-drupal.xml` to the "Custom rulesets".
* Editor > Inspections > PHP > Quality tools > PHP_CodeSniffer validation
Set "Coding Standard" to "Custom" and set the path to `phpcs.qa-drupal.xml`.
* Languages & Frameworks > PHP > Test Frameworks > Test Runner
Set "Default configuration file" to `phpunit.qa-drupal.xml`.

## CodeClimate

Update the `.codeclimate.yml` file within your project.

Make sure that you use the CodeClimate specific phpcs config file:

```yaml
prepare:
fetch:
- url: "https://raw.githubusercontent.com/digipolisgent/php_package_qa-drupal/1.x/configs/phpcs-codeclimate.xml"
path: ".phpcs.xml"
```

Make sure that you use the beta channel for the PHPCodeSniffer plugin:

```yaml
plugins:
phpcodesniffer:
enabled: true
channel: beta
config:
standard: ".phpcs.xml"
```

### PHP compatibility

In order to check php compatibility you can use the phpcs `PHPCompatibility` sniff:

```bash
php vendor/bin/phpcs -p --ignore="*/vendor/*" --extensions=php,inc,module,install,theme --runtime-set testVersion 8.1 --standard=PHPCompatibility ./web/modules/contrib
```

[license-badge]: https://img.shields.io/packagist/l/digipolisgent/qa-drupal
[license-link]: LICENSE.md

[travis-badge]: https://api.travis-ci.com/district09/php_package_qa-drupal.svg?branch=develop "Travis build develop"
[travis-link]: https://travis-ci.com/github/district09/php_package_qa-drupal/branches

[codeclimate-maint-badge]: https://api.codeclimate.com/v1/badges/d3d6d20fbc6efb09337e/maintainability
[codeclimate-maint-link]: https://codeclimate.com/github/district09/php_package_qa-drupal/maintainability