431 lines
9.1 KiB
Markdown
431 lines
9.1 KiB
Markdown
# Laravel Pint
|
||
|
||
* Introduction
|
||
* Installation
|
||
* Running Pint
|
||
* Configuring Pint
|
||
* Presets
|
||
* Rules
|
||
* Excluding Files / Folders
|
||
* Continuous Integration
|
||
* GitHub Actions
|
||
|
||
## Introduction
|
||
|
||
[Laravel Pint](https://github.com/laravel/pint) is an opinionated PHP code
|
||
style fixer for minimalists. Pint is built on top of [PHP CS
|
||
Fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer) and makes it simple to
|
||
ensure that your code style stays clean and consistent.
|
||
|
||
Pint is automatically installed with all new Laravel applications so you may
|
||
start using it immediately. By default, Pint does not require any
|
||
configuration and will fix code style issues in your code by following the
|
||
opinionated coding style of Laravel.
|
||
|
||
## Installation
|
||
|
||
Pint is included in recent releases of the Laravel framework, so installation
|
||
is typically unnecessary. However, for older applications, you may install
|
||
Laravel Pint via Composer:
|
||
|
||
|
||
|
||
1composer require laravel/pint --dev
|
||
|
||
|
||
composer require laravel/pint --dev
|
||
|
||
## Running Pint
|
||
|
||
You can instruct Pint to fix code style issues by invoking the `pint` binary
|
||
that is available in your project's `vendor/bin` directory:
|
||
|
||
|
||
|
||
1./vendor/bin/pint
|
||
|
||
|
||
./vendor/bin/pint
|
||
|
||
If you would like Pint to run in parallel mode (experimental) for improved
|
||
performance, you may use the `--parallel` option:
|
||
|
||
|
||
|
||
1./vendor/bin/pint --parallel
|
||
|
||
|
||
./vendor/bin/pint --parallel
|
||
|
||
Parallel mode also allows you to specify the maximum number of processes to
|
||
run via the `--max-processes` option. If this option is not provided, Pint
|
||
will use every available core on your machine:
|
||
|
||
|
||
|
||
1./vendor/bin/pint --parallel --max-processes=4
|
||
|
||
|
||
./vendor/bin/pint --parallel --max-processes=4
|
||
|
||
You may also run Pint on specific files or directories:
|
||
|
||
|
||
|
||
1./vendor/bin/pint app/Models
|
||
|
||
2
|
||
|
||
3./vendor/bin/pint app/Models/User.php
|
||
|
||
|
||
./vendor/bin/pint app/Models
|
||
|
||
./vendor/bin/pint app/Models/User.php
|
||
|
||
Pint will display a thorough list of all of the files that it updates. You can
|
||
view even more detail about Pint's changes by providing the `-v` option when
|
||
invoking Pint:
|
||
|
||
|
||
|
||
1./vendor/bin/pint -v
|
||
|
||
|
||
./vendor/bin/pint -v
|
||
|
||
If you would like Pint to simply inspect your code for style errors without
|
||
actually changing the files, you may use the `--test` option. Pint will return
|
||
a non-zero exit code if any code style errors are found:
|
||
|
||
|
||
|
||
1./vendor/bin/pint --test
|
||
|
||
|
||
./vendor/bin/pint --test
|
||
|
||
If you would like Pint to only modify the files that differ from the provided
|
||
branch according to Git, you may use the `--diff=[branch]` option. This can be
|
||
effectively used in your CI environment (like GitHub actions) to save time by
|
||
only inspecting new or modified files:
|
||
|
||
|
||
|
||
1./vendor/bin/pint --diff=main
|
||
|
||
|
||
./vendor/bin/pint --diff=main
|
||
|
||
If you would like Pint to only modify the files that have uncommitted changes
|
||
according to Git, you may use the `--dirty` option:
|
||
|
||
|
||
|
||
1./vendor/bin/pint --dirty
|
||
|
||
|
||
./vendor/bin/pint --dirty
|
||
|
||
If you would like Pint to fix any files with code style errors but also exit
|
||
with a non-zero exit code if any errors were fixed, you may use the `--repair`
|
||
option:
|
||
|
||
|
||
|
||
1./vendor/bin/pint --repair
|
||
|
||
|
||
./vendor/bin/pint --repair
|
||
|
||
## Configuring Pint
|
||
|
||
As previously mentioned, Pint does not require any configuration. However, if
|
||
you wish to customize the presets, rules, or inspected folders, you may do so
|
||
by creating a `pint.json` file in your project's root directory:
|
||
|
||
|
||
|
||
1{
|
||
|
||
2 "preset": "laravel"
|
||
|
||
3}
|
||
|
||
|
||
{
|
||
"preset": "laravel"
|
||
}
|
||
|
||
In addition, if you wish to use a `pint.json` from a specific directory, you
|
||
may provide the `--config` option when invoking Pint:
|
||
|
||
|
||
|
||
1./vendor/bin/pint --config vendor/my-company/coding-style/pint.json
|
||
|
||
|
||
./vendor/bin/pint --config vendor/my-company/coding-style/pint.json
|
||
|
||
### Presets
|
||
|
||
Presets define a set of rules that can be used to fix code style issues in
|
||
your code. By default, Pint uses the `laravel` preset, which fixes issues by
|
||
following the opinionated coding style of Laravel. However, you may specify a
|
||
different preset by providing the `--preset` option to Pint:
|
||
|
||
|
||
|
||
1./vendor/bin/pint --preset psr12
|
||
|
||
|
||
./vendor/bin/pint --preset psr12
|
||
|
||
If you wish, you may also set the preset in your project's `pint.json` file:
|
||
|
||
|
||
|
||
1{
|
||
|
||
2 "preset": "psr12"
|
||
|
||
3}
|
||
|
||
|
||
{
|
||
"preset": "psr12"
|
||
}
|
||
|
||
Pint's currently supported presets are: `laravel`, `per`, `psr12`, `symfony`,
|
||
and `empty`.
|
||
|
||
### Rules
|
||
|
||
Rules are style guidelines that Pint will use to fix code style issues in your
|
||
code. As mentioned above, presets are predefined groups of rules that should
|
||
be perfect for most PHP projects, so you typically will not need to worry
|
||
about the individual rules they contain.
|
||
|
||
However, if you wish, you may enable or disable specific rules in your
|
||
`pint.json` file or use the `empty` preset and define the rules from scratch:
|
||
|
||
|
||
|
||
1{
|
||
|
||
2 "preset": "laravel",
|
||
|
||
3 "rules": {
|
||
|
||
4 "simplified_null_return": true,
|
||
|
||
5 "array_indentation": false,
|
||
|
||
6 "new_with_parentheses": {
|
||
|
||
7 "anonymous_class": true,
|
||
|
||
8 "named_class": true
|
||
|
||
9 }
|
||
|
||
10 }
|
||
|
||
11}
|
||
|
||
|
||
{
|
||
"preset": "laravel",
|
||
"rules": {
|
||
"simplified_null_return": true,
|
||
"array_indentation": false,
|
||
"new_with_parentheses": {
|
||
"anonymous_class": true,
|
||
"named_class": true
|
||
}
|
||
}
|
||
}
|
||
|
||
Pint is built on top of [PHP CS Fixer](https://github.com/FriendsOfPHP/PHP-CS-
|
||
Fixer). Therefore, you may use any of its rules to fix code style issues in
|
||
your project: [PHP CS Fixer Configurator](https://mlocati.github.io/php-cs-
|
||
fixer-configurator).
|
||
|
||
### Excluding Files / Folders
|
||
|
||
By default, Pint will inspect all `.php` files in your project except those in
|
||
the `vendor` directory. If you wish to exclude more folders, you may do so
|
||
using the `exclude` configuration option:
|
||
|
||
|
||
|
||
1{
|
||
|
||
2 "exclude": [
|
||
|
||
3 "my-specific/folder"
|
||
|
||
4 ]
|
||
|
||
5}
|
||
|
||
|
||
{
|
||
"exclude": [
|
||
"my-specific/folder"
|
||
]
|
||
}
|
||
|
||
If you wish to exclude all files that contain a given name pattern, you may do
|
||
so using the `notName` configuration option:
|
||
|
||
|
||
|
||
1{
|
||
|
||
2 "notName": [
|
||
|
||
3 "*-my-file.php"
|
||
|
||
4 ]
|
||
|
||
5}
|
||
|
||
|
||
{
|
||
"notName": [
|
||
"*-my-file.php"
|
||
]
|
||
}
|
||
|
||
If you would like to exclude a file by providing an exact path to the file,
|
||
you may do so using the `notPath` configuration option:
|
||
|
||
|
||
|
||
1{
|
||
|
||
2 "notPath": [
|
||
|
||
3 "path/to/excluded-file.php"
|
||
|
||
4 ]
|
||
|
||
5}
|
||
|
||
|
||
{
|
||
"notPath": [
|
||
"path/to/excluded-file.php"
|
||
]
|
||
}
|
||
|
||
## Continuous Integration
|
||
|
||
### GitHub Actions
|
||
|
||
To automate linting your project with Laravel Pint, you can configure [GitHub
|
||
Actions](https://github.com/features/actions) to run Pint whenever new code is
|
||
pushed to GitHub. First, be sure to grant "Read and write permissions" to
|
||
workflows within GitHub at **Settings > Actions > General > Workflow
|
||
permissions**. Then, create a `.github/workflows/lint.yml` file with the
|
||
following content:
|
||
|
||
|
||
|
||
1name: Fix Code Style
|
||
|
||
2
|
||
|
||
3on: [push]
|
||
|
||
4
|
||
|
||
5jobs:
|
||
|
||
6 lint:
|
||
|
||
7 runs-on: ubuntu-latest
|
||
|
||
8 strategy:
|
||
|
||
9 fail-fast: true
|
||
|
||
10 matrix:
|
||
|
||
11 php: [8.4]
|
||
|
||
12
|
||
|
||
13 steps:
|
||
|
||
14 - name: Checkout code
|
||
|
||
15 uses: actions/checkout@v4
|
||
|
||
16
|
||
|
||
17 - name: Setup PHP
|
||
|
||
18 uses: shivammathur/setup-php@v2
|
||
|
||
19 with:
|
||
|
||
20 php-version: ${{ matrix.php }}
|
||
|
||
21 extensions: json, dom, curl, libxml, mbstring
|
||
|
||
22 coverage: none
|
||
|
||
23
|
||
|
||
24 - name: Install Pint
|
||
|
||
25 run: composer global require laravel/pint
|
||
|
||
26
|
||
|
||
27 - name: Run Pint
|
||
|
||
28 run: pint
|
||
|
||
29
|
||
|
||
30 - name: Commit linted files
|
||
|
||
31 uses: stefanzweifel/git-auto-commit-action@v5
|
||
|
||
|
||
name: Fix Code Style
|
||
|
||
on: [push]
|
||
|
||
jobs:
|
||
lint:
|
||
runs-on: ubuntu-latest
|
||
strategy:
|
||
fail-fast: true
|
||
matrix:
|
||
php: [8.4]
|
||
|
||
steps:
|
||
- name: Checkout code
|
||
uses: actions/checkout@v4
|
||
|
||
- name: Setup PHP
|
||
uses: shivammathur/setup-php@v2
|
||
with:
|
||
php-version: ${{ matrix.php }}
|
||
extensions: json, dom, curl, libxml, mbstring
|
||
coverage: none
|
||
|
||
- name: Install Pint
|
||
run: composer global require laravel/pint
|
||
|
||
- name: Run Pint
|
||
run: pint
|
||
|
||
- name: Commit linted files
|
||
uses: stefanzweifel/git-auto-commit-action@v5
|
||
|