Skip to content

Commit

Permalink
Merge pull request #742 from andrewnicols/phpcs_updates
Browse files Browse the repository at this point in the history 
Updates for phpcs documentation
  • Loading branch information
@ilyatregubov
ilyatregubov authored Sep 18, 2023
2 parents 7164174 + 15ca009 commit 5664a7e
Showing 1 changed file with 50 additions and 43 deletions.
93 changes: 50 additions & 43 deletions general/development/tools/phpcs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,22 +9,25 @@ sidebar_position: 1

import { Since } from '@site/src/components';

## Overview
[PHPCodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) is a tool used to analyse PHP code using a set of rules. In many cases these rules can be used to automatically fix the errors they identify.

This document describes the various code sniffing tools that Moodle recommends, their purpose, and their usage.
Moodle has two sets of published rule-sets intended to meet the [Moodle Coding Style](../policies/codingstyle/index.md), and identify any parts of the code do not conform to this style. These are:

[PHPCodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) is a tool used to analyse PHP code using a set of rules. In many cases these rules can be used to automatically fix the errors they identify.
- `moodle` - The standard ruleset which meets all variants of the coding style
- `moodle-extra` - The extended standard which includes recommended best practices

Moodle has published a ruleset intended to meet the [Moodle Coding Style](../policies/codingstyle/index.md), and identify any parts of the code do not conform to this style.
We recommend use of the `moodle-extra` standard, particularly when writing new code.

## Installation

It is recommend that both the phpcs scripts, and the Moodle ruleset, are installed globally using Composer:
The recommended method of installation is via the global composer command:

```console
composer global require moodlehq/moodle-cs
```

This ensures that you have a single copy of the standard used for all code.

### Configuration

<Since versions={["4.1.0", "4.0.1", "3.11.7"]} issueNumber="MDL-74511" />
Expand All @@ -33,9 +36,23 @@ A PHPCS configuration is included in the Moodle codebase and ensures that the co

This can be further extended by generating an additional configuration to ignore all third-party libraries using the `grunt ignorefiles` command. See [grunt](./nodejs.md#grunt) for further information on using Grunt.

#### Community plugins, and older Moodle versions
If you would like to make use of the `moodle-extra` standard then you should create a `.phpcs.xml` file with the following content:

If you are developing your own plugin outside of the main Moodle directory, or you are working with an older version of Moodle, the easiest way to configure phpcs to use the Moodle ruleset is by creating a local `phpcs.xml.dist` configuration at the root directory of your repository with the following content:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<ruleset name="MoodleCore">
<rule ref="./phpcs.xml"/>
<rule ref="moodle-extra"/>
</ruleset>
```

This will extend the standard configuration, and apply the extra standard on top of it.

#### Moodle 3.10 and earlier

The easiest way to have PHP CodeSniffer pick up your preferred style is via a local configuration file.

You can create a file named `.phpcs.xml` with the following contents:

```xml
<?xml version="1.0" encoding="UTF-8"?>
Expand All @@ -44,48 +61,42 @@ If you are developing your own plugin outside of the main Moodle directory, or y
</ruleset>
```

If you do not wish to include this file in your repository, or you are using an older version of Moodle, then you should add this to your local gitignore files. On a Unix-like system this can be achieved with:
If you wish to use the `moodle-extra` coding style, then you can use the following content:

```console
echo phpcs.xml.dist >> .git/info/exclude
```xml
<?xml version="1.0" encoding="UTF-8"?>
<ruleset name="MoodleCore">
<rule ref="moodle-extra"/>
</ruleset>
```

:::info

The `.git/info/exclude` file is a per-repository version of the `.gitignore` file. Whilst `.gitignore` is tracked within the Moodle codebase and a version is shipped with Moodle, the `.git/info/exclude` file is local to your git clone.

See the [gitignore](https://git-scm.com/docs/gitignore) documentation for more information on the gitignore feature.
Third-party library code will not be ignored with these versions of Moodle.

:::

#### System-side default standard

Although not recommended, you can configure the Moodle ruleset as the system-wide default for phpcs:

```php
phpcs --config-set default_standard moodle
```

:::important Not recommended
:::tip Ignoring the file with Git

This approach is **not recommended** and is only preserved for reference.
We recommend configuring your code checkout to ignore the `.phpcs.xml` file by adding a local ignore record to `.git/info/exclude`

:::

## Moodle plugin

Moodle includes a copy of the PHPCodeSniffer package, and the Moodle ruleset, as part of the [`moodle-local_codechecker`](https://github.com/moodlehq/moodle-local_codechecker) Moodle plugin. This makes the code checker available via a web-based interface for checking the syntax of a given file or folder.
#### Community plugins, and older Moodle versions

One way to install this plugin is using `git clone`:
If you are developing your own plugin outside of the main Moodle directory, or you are working with an older version of Moodle, the easiest way to configure phpcs to use the Moodle ruleset is by creating a local `phpcs.xml.dist` configuration at the root directory of your repository with the following content:

```console
git clone https://github.com/moodlehq/moodle-local_codechecker.git local/codechecker
```xml
<?xml version="1.0" encoding="UTF-8"?>
<ruleset name="MoodleCore">
<rule ref="moodle"/>
</ruleset>
```

It is recommended that you add the plugin to your _local_ git ignore:
If you do not wish to include this file in your repository, or you are using an older version of Moodle, then you should add this to your local gitignore files. On a Unix-like system this can be achieved with:

```console
echo local/codechecker >> .git/info/exclude
echo phpcs.xml.dist >> .git/info/exclude
```

:::info
Expand All @@ -96,23 +107,19 @@ See the [gitignore](https://git-scm.com/docs/gitignore) documentation for more i

:::

:::note

If you are not installing the moodle ruleset globally, and are instead using the [`local_codechecker`](https://github.com/moodlehq/moodle-local_codechecker) plugin, then you _must_ also use the version of phpcs distributed in the plugin.

This is located at `local/codechecker/phpcs/bin/phpcs`.
#### System-side default standard

:::
Although not recommended, you can configure the Moodle ruleset as the system-wide default for phpcs:

Once installed a new codechecker option will appear in the Site administration -> Development page.
```php
phpcs --config-set default_standard moodle
```

This page allows for the code in a specified directory to be checked, for example if you wanted to check the code for the `shortanswer` question type you would enter
:::important Not recommended

```
/question/type/shortanswer
```
This approach is **not recommended** and is only preserved for reference.

You would then be presented with a list of the count of files processed and any warnings or errors.
:::

## Editor integrations

Expand Down

0 comments on commit 5664a7e

Please sign in to comment.