## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require --dev laravel/pint

Pint is automatically added to your project's dev dependencies.

First Run:
```
php artisan pint
```
This formats all PHP files in your project using Laravel's default preset.
Key Commands:
- Format a specific file:
```
php artisan pint app/Models/User.php
```
- Check for dirty files (modified since last format):
```
php artisan pint --dirty
```
- Dry run (show changes without applying):
```
php artisan pint --dry-run
```
Configuration: Create a pint.json file in your project root to customize rules:
```
{
  "preset": "laravel",
  "rules": {
    "phpdoc_align": false
  }
}
```

Implementation Patterns

Daily Workflow

Pre-Commit Hook: Integrate Pint with Git hooks to auto-format code before commits:
```
php artisan pint --dirty
```
Add to .git/hooks/pre-commit:
```
#!/bin/sh
php artisan pint --dirty || exit 1
```

CI/CD Pipeline: Use Pint in CI to enforce consistency:

# .github/workflows/pint.yml
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: composer install
      - run: php artisan pint --test

Custom Presets: Extend the default Laravel preset in pint.json:

{
  "preset": "laravel",
  "rules": {
    "fully_qualified_strict_types": true,
    "phpdoc_type_annotations_only": true
  }
}

Parallel Processing: Speed up formatting for large codebases:
```
php artisan pint --parallel
```
Or set max processes:
```
php artisan pint --parallel=4
```
IDE Integration:
- VS Code: Use the "Format Document" command (Pint integrates via php-cs-fixer).
- PHPStorm: Configure "Reformat Code" to use Pint via php artisan pint.

Advanced Patterns

Conditional Formatting: Use --diff to show changes without applying:
```
php artisan pint --diff
```
Combine with --exit-status for CI checks:
```
php artisan pint --diff --with-exit-status
```
Stdin Support: Pipe code directly to Pint for one-off formatting:
```
echo "<?php echo 'Hello';" | php artisan pint --stdin
```
Agent Mode: Auto-detect IDE environments (e.g., Claude Code/OpenCode):
```
php artisan pint --agent
```

Base Configuration: Extend from a base config file:

// pint.json
{
  "extends": "vendor/package/pint.json"
}

Test Coverage: Use --test to verify formatting works as expected:
```
php artisan pint --test
```

Gotchas and Tips

Common Pitfalls

Parallel Mode Issues:
- Windows: Ensure --parallel works by using full paths or relative paths.
- Verbose Mode: Combine with --verbose to debug:
```
php artisan pint --parallel --verbose
```

Config Overrides:

Command-line flags override pint.json:

php artisan pint --no-config --rules='{"cast_spaces": false}'

Caching Quirks:
- Cache files (~/.cache/pint) may cause stale results. Clear with:
```
php artisan pint --no-cache
```
- Custom cache paths:
```
php artisan pint --cache-file=/custom/path/cache
```
Rule Conflicts:
- Disable conflicting rules explicitly (e.g., yoda_style may clash with ternary operators):
```
{
  "rules": {
    "yoda_style": false
  }
}
```
PHP Version Support:
- Pint supports PHP 8.1+. For PHP 8.5+, use:
```
php artisan pint --php-version=8.5
```

Debugging Tips

Dry Runs: Always test with --dry-run before applying changes:
```
php artisan pint --dry-run --diff
```
Verbose Output: Use --verbose to diagnose issues:
```
php artisan pint --verbose
```
Exit Status: Leverage --with-exit-status in CI to fail builds on errors:
```
php artisan pint --with-exit-status
```
Rule-Specific Debugging: Isolate problematic rules by disabling them one by one in pint.json.
Windows Paths: Use forward slashes or escape backslashes in paths:
```
php artisan pint "C:\\path\\to\\file.php"
```

Extension Points

Custom Rules: Add PHP-CS-Fixer rules to pint.json:

{
  "rules": {
    "@Symfony": true,
    "no_unused_imports": true
  }
}

Preset Management: Create reusable presets in pint.json:

{
  "presets": ["laravel", "custom-preset"],
  "rules": {
    "custom-preset": {
      "line_ending": "\n"
    }
  }
}

Hooks: Extend Pint’s behavior via Laravel service providers or console commands.
Parallel Tuning: Adjust max processes for large projects:
```
php artisan pint --parallel=8
```
IDE-Specific Tweaks: Configure IDEs to ignore Pint’s cache files (e.g., ~/.cache/pint).

---

Pint Laravel Package