Duster Laravel Package

Getting Started

Run composer require tightenco/duster --dev to install. The first use case is integrating Tighten's standardized linting into your workflow:

# Run a full lint check (TLint, PHP_CodeSniffer, PHP CS Fixer, Pint)
./vendor/bin/duster lint

# Fix all auto-fixable issues
./vendor/bin/duster fix

Key files to check first:

• duster.json (custom includes/excludes)
• .php-cs-fixer.dist.php (CS Fixer rules)
• pint.json (Pint configuration)
• tlint.json (TLint configuration)
• .phpcs.xml.dist (PHP_CodeSniffer rules)

Implementation Patterns

Daily Workflow Integration

# Pre-commit hook (via Husky)
./vendor/bin/duster lint --dirty  # Only check modified files

# CI Pipeline
./vendor/bin/duster lint --fail-on-error  # Fail build on lint errors

Custom Tool Integration

// duster.json
{
  "scripts": {
    "lint": {
      "phpstan": ["./vendor/bin/phpstan", "analyse", "--level=5"]
    }
  }
}

Run with:

./vendor/bin/duster lint --using="phpstan,tlint,pint"

Environment-Specific Setup

# For Laravel Sail
./vendor/bin/sail bin duster lint

# For DDEV
./vendor/bin/duster husky-hooks --env=ddev

GitHub Actions Integration

# .github/workflows/duster.yml
name: Duster
on: [push, pull_request]

jobs:
  duster:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: tighten/duster-action@v1

Gotchas and Tips

Common Pitfalls

1. Blade File Exclusions: Duster v3.4.1+ automatically excludes Blade files from PHPCS, but verify your .phpcs.xml.dist isn't forcing Blade checks.

2. TLint Fix Behavior: TLint's fix command now fails if linting errors exist (v3.0.0+). Use tlint fix --allow-fail if needed.

3. Parallel Processing: PHP CS Fixer runs in parallel by default (v3.1.0+), which may impact CI performance. Add --parallel flag explicitly if needed.

4. Default Excludes: Duster excludes tests/, node_modules/, and vendor/ by default. Custom excludes in duster.json won't expand these patterns.

Debugging Tips

• Verbose Output: Use --verbose flag for detailed tool execution logs.
• Tool Isolation: Run individual tools directly to diagnose issues:

  ./vendor/bin/tlint
  ./vendor/bin/phpcs
  ./vendor/bin/pint
  

• Timeout Handling: Increase processTimeout in duster.json if scripts hang (default: 60s).

Extension Points

1. Custom Rules: Override Tighten presets by modifying:

   • .php-cs-fixer.dist.php (CS Fixer)
   • pint.json (Pint)
   • tlint.json (TLint)
   • .phpcs.xml.dist (PHP_CodeSniffer)

2. Script Hooks: Add custom scripts to duster.json:

   {
     "scripts": {
       "lint": {
         "custom-lint": ["php", "scripts/custom-lint.php"]
       },
       "fix": {
         "custom-fix": ["php", "scripts/custom-fix.php"]
       }
     }
   }
   

3. Tool Order: Control execution order with --using flag:

   ./vendor/bin/duster lint --using="pint,phpstan,tlint"
   

Configuration Quirks

• PHPStan Integration: Requires explicit configuration in duster.json (not auto-detected).
• Pest Support: Pest.php files are excluded by default (v2.7.2+).
• Side Effects: Tests are excluded from PSR1.Files.SideEffects (v3.0.3+).

Performance Optimization

• Use --dirty flag for pre-commit hooks to limit file scanning.
• For large codebases, run tools sequentially:

  ./vendor/bin/duster lint --using="pint,tlint" --no-parallel