Laravel Pint (laravel/pint)

Laravel Pint

https://github.com/laravel/pint
Admin
Laravel Pint is an opinionated PHP code style fixer for minimalists.

Tokens:4,333
Snippets:45
Trust Score:9.5
Update:2 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# Laravel Pint

Laravel Pint is an opinionated PHP code style fixer for minimalists built on top of PHP-CS-Fixer. It provides a zero-configuration approach to ensuring your PHP code follows consistent style conventions, with the Laravel coding style as the default preset. Pint automatically detects and fixes code style violations across your entire project, supporting multiple industry-standard presets including PSR-12, PER, and Symfony.

The tool integrates seamlessly into development workflows through CLI commands, CI/CD pipelines, and editor integrations. It supports parallel processing for faster execution on large codebases, stdin input for real-time editor formatting, and multiple output formats (JSON, XML, checkstyle, JUnit, GitLab) for integration with various tooling. Configuration is handled through a simple `pint.json` file that allows customizing presets, rules, and file exclusions without complex setup.

## Installation

Install Laravel Pint as a development dependency using Composer.

```bash
# Install Pint in your project
composer require laravel/pint --dev

# Or install globally
composer global require laravel/pint
```

## Basic Usage

Run Pint to fix code style issues in your project.

```bash
# Fix all PHP files in current directory (uses Laravel preset by default)
./vendor/bin/pint

# Fix specific file or directory
./vendor/bin/pint app/Models/User.php
./vendor/bin/pint app/Http/Controllers

# Fix multiple paths
./vendor/bin/pint app/Models app/Http/Controllers
```

## Test Mode (Dry Run)

Check for code style issues without modifying files.

```bash
# Check for issues without fixing (exit code 1 if issues found)
./vendor/bin/pint --test

# Stop on first error found
./vendor/bin/pint --bail

# Fix files but return exit code 1 if changes were made (useful for CI)
./vendor/bin/pint --repair
```

## Preset Selection

Choose from built-in presets for different coding standards.

```bash
# Use Laravel preset (default)
./vendor/bin/pint --preset laravel

# Use PSR-12 preset
./vendor/bin/pint --preset psr12

# Use PER (PHP Evolving Recommendation) preset
./vendor/bin/pint --preset per

# Use Symfony preset
./vendor/bin/pint --preset symfony

# Use empty preset (no rules, only custom rules from pint.json)
./vendor/bin/pint --preset empty
```

## Configuration File (pint.json)

Create a `pint.json` file in your project root to customize Pint's behavior.

```json
{
    "preset": "laravel",
    "exclude": [
        "tests/Fixtures",
        "legacy"
    ],
    "notName": [
        "*-generated.php"
    ],
    "notPath": [
        "path/to/excluded-file.php"
    ],
    "rules": {
        "array_syntax": {
            "syntax": "short"
        },
        "binary_operator_spaces": {
            "default": "single_space"
        },
        "blank_line_before_statement": {
            "statements": ["return", "throw"]
        },
        "concat_space": {
            "spacing": "one"
        },
        "declare_strict_types": true,
        "final_class": true,
        "ordered_imports": {
            "sort_algorithm": "alpha"
        },
        "single_quote": true
    }
}
```

## Configuration Inheritance

Extend a base configuration file to share settings across projects.

```json
{
    "extend": "./base.json",
    "preset": "laravel",
    "rules": {
        "declare_strict_types": true,
        "final_class": true
    }
}
```

Base configuration file (`base.json`):

```json
{
    "preset": "psr12",
    "rules": {
        "array_push": true,
        "date_time_immutable": true,
        "fully_qualified_strict_types": true,
        "global_namespace_import": {
            "import_classes": true,
            "import_constants": true
        }
    }
}
```

## Git Integration (Diff Mode)

Only fix files that have changed since branching from a specific branch.

```bash
# Fix files changed since branching from main
./vendor/bin/pint --diff main

# Fix files changed since branching from master
./vendor/bin/pint --diff master

# Fix files changed since branching from remote branch
./vendor/bin/pint --diff origin/main
```

## Dirty Mode

Only fix files with uncommitted changes in Git.

```bash
# Fix only files with uncommitted changes
./vendor/bin/pint --dirty
```

## Stdin Input (Editor Integration)

Format code from stdin for real-time editor integration.

```bash
# Format code from stdin (use - as path placeholder)
echo '<?php $array = array("a","b");' | ./vendor/bin/pint -

# Format with file context (respects exclusion rules for that path)
echo '<?php $array = array("a","b");' | ./vendor/bin/pint - --stdin-filename=app/Models/User.php

# Using only stdin-filename option
echo '<?php $array = array("a","b");' | ./vendor/bin/pint --stdin-filename=app/Models/Example.php
```

Example transformation:

```php
// Input
<?php
$array = array("a","b");
if($condition==true){
    echo "test";
}

// Output (Laravel preset)
<?php

$array = ['a', 'b'];
if ($condition == true) {
    echo 'test';
}
```

## Output Formats

Specify output format for CI/CD integration.

```bash
# JSON output
./vendor/bin/pint --test --format json

# XML output
./vendor/bin/pint --test --format xml

# Checkstyle format (for Jenkins, etc.)
./vendor/bin/pint --test --format checkstyle

# JUnit format (for test runners)
./vendor/bin/pint --test --format junit

# GitLab Code Quality format
./vendor/bin/pint --test --format gitlab

# Agent format (for Claude Code / OpenCode integration)
./vendor/bin/pint --test --format agent
```

Example JSON output:

```json
{
    "files": [
        {
            "name": "app/Models/User.php",
            "appliedFixers": [
                "array_syntax",
                "single_quote",
                "trailing_comma_in_multiline"
            ],
            "diff": "--- Original\n+++ New\n..."
        }
    ],
    "time": {
        "total": 0.123
    },
    "memory": 12.5
}
```

## Output to File

Save formatted output to a file while displaying pretty output in terminal.

```bash
# Save checkstyle XML to file, show pretty output in terminal
./vendor/bin/pint --test --output-format checkstyle --output-to-file report.xml

# Save JSON to file, show XML in terminal
./vendor/bin/pint --test --format xml --output-format json --output-to-file report.json

# Save JUnit to file for CI pipeline
./vendor/bin/pint --test --output-format junit --output-to-file test-results.xml
```

## Parallel Processing

Enable parallel execution for faster processing on large codebases.

```bash
# Run in parallel mode (experimental)
./vendor/bin/pint --parallel

# Run in parallel with specific number of processes
./vendor/bin/pint --parallel --max-processes 4
```

## Cache Configuration

Configure caching for improved performance on subsequent runs.

```bash
# Specify custom cache file location
./vendor/bin/pint --cache-file .pint.cache
```

In `pint.json`:

```json
{
    "preset": "laravel",
    "cache-file": ".pint.cache"
}
```

## Ignore Configuration File

Run Pint without loading any configuration file.

```bash
# Ignore pint.json and use only CLI options
./vendor/bin/pint --no-config --preset psr12
```

## Custom Configuration Path

Specify a custom configuration file path.

```bash
# Use configuration from specific path
./vendor/bin/pint --config /path/to/custom-pint.json

# Use remote configuration (HTTP/HTTPS)
./vendor/bin/pint --config https://example.com/pint.json
```

## File Finder Configuration

Configure which files to include or exclude in `pint.json`.

```json
{
    "preset": "laravel",
    "exclude": [
        "bootstrap/cache",
        "build",
        "node_modules",
        "storage",
        "vendor",
        "tests/Fixtures"
    ],
    "notName": [
        "_ide_helper*.php",
        ".phpstorm.meta.php",
        "*.blade.php"
    ],
    "notPath": [
        "legacy/*",
        "generated/*"
    ]
}
```

## Laravel Preset Rules Overview

The Laravel preset includes comprehensive styling rules.

```php
// Laravel preset applies these transformations:

// Array syntax: long to short
array("a", "b") → ['a', 'b']

// String quotes: double to single (when no interpolation)
"hello" → 'hello'

// Concatenation: no spaces around dots
$a . $b → $a.$b

// Yoda conditions: disabled (natural order)
if (true === $condition) → if ($condition === true)

// Not operator: space after
!$condition → ! $condition

// Increment style: postfix
++$i → $i++

// PHPUnit: snake_case test methods
public function testMyMethod() → public function test_my_method()

// Imports: alphabetically sorted
use B; use A; → use A; use B;

// Trailing commas in multiline arrays
[
    'a',
    'b'  // no comma
] → [
    'a',
    'b', // trailing comma
]

// Braces position
class Foo {  → class Foo
                 {

function bar() {  → function bar()
                      {
```

## CI/CD Integration Example

GitHub Actions workflow for code style checking.

```yaml
# .github/workflows/pint.yml
name: Code Style

on: [push, pull_request]

jobs:
  pint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'

      - name: Install Dependencies
        run: composer install --no-progress --prefer-dist

      - name: Run Pint
        run: ./vendor/bin/pint --test
```

## Pre-commit Hook Example

Set up a Git pre-commit hook to run Pint automatically.

```bash
#!/bin/sh
# .git/hooks/pre-commit

# Get list of staged PHP files
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.php$')

if [ -z "$STAGED_FILES" ]; then
    exit 0
fi

# Run Pint on staged files only
echo "Running Laravel Pint..."
./vendor/bin/pint --dirty --test

if [ $? -ne 0 ]; then
    echo "Pint found code style issues. Run './vendor/bin/pint --dirty' to fix them."
    exit 1
fi

exit 0
```

## Composer Scripts Integration

Add Pint commands to `composer.json` scripts.

```json
{
    "scripts": {
        "lint": "./vendor/bin/pint --test",
        "lint:fix": "./vendor/bin/pint",
        "lint:diff": "./vendor/bin/pint --diff main",
        "lint:dirty": "./vendor/bin/pint --dirty"
    }
}
```

Usage:

```bash
composer lint      # Check for issues
composer lint:fix  # Fix all issues
composer lint:diff # Fix changes since main branch
```

## Summary

Laravel Pint serves as an essential tool for PHP developers seeking consistent code formatting with minimal configuration overhead. Its primary use cases include local development formatting, CI/CD pipeline integration for code style enforcement, and real-time editor formatting through stdin support. The tool excels in Laravel projects where the default preset aligns perfectly with framework conventions, but equally supports teams following PSR-12, PER, or Symfony standards through simple preset switching.

Integration patterns typically involve combining Pint with Git hooks for pre-commit validation, CI workflows for pull request checks, and editor plugins for format-on-save functionality. The `--test` and `--repair` flags provide flexibility for different pipeline requirements, while output formats like checkstyle, JUnit, and GitLab enable seamless integration with existing code quality dashboards. For large codebases, the experimental parallel processing mode and caching features significantly improve execution times, making Pint practical for projects of any scale.