Duster Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation:

   composer require tightenco/duster --dev
   

   • Ensures the package is available in your project's devDependencies.

2. First Run (Linting):

   ./vendor/bin/duster lint
   

   • Runs TLint, PHP_CodeSniffer, PHP CS Fixer, and Pint with Tighten’s default presets.
   • Checks for style violations without modifying files.

3. First Fix:

   ./vendor/bin/duster fix
   

   • Applies automatic fixes for Pint, PHP CS Fixer, and TLint (where possible).
   • Skips non-autofixable issues (e.g., PHP_CodeSniffer warnings).

4. Check Available Commands:

   ./vendor/bin/duster commands
   

   • Lists all available commands (e.g., lint, fix, github-actions, husky-hooks).

Where to Look First

• Configuration Files:

  • duster.json: Customize file inclusion/exclusion or add scripts (e.g., PHPStan).
  • tlint.json: TLint-specific rules (if extending defaults).
  • .phpcs.xml.dist: PHP_CodeSniffer rules (Tighten preset is pre-configured).
  • .php-cs-fixer.dist.php: PHP CS Fixer rules (includes Tighten’s CustomOrderedClassElementsFixer).
  • pint.json: Pint configuration (Laravel preset with Tighten tweaks).

• Style Guide:

  • Duster’s Style Guide (included in the package).
  • Explains rules for class ordering, naming conventions, and Laravel-specific patterns.

• GitHub Action:

  • Publish pre-configured workflows with:

    ./vendor/bin/duster github-actions
    

  • Integrates with CI pipelines to enforce standards on every push.

First Use Case: Onboarding a New Developer

1. Set Up Local Hooks (optional but recommended):

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

   • Adds pre-commit hooks to run duster lint on staged changes.

2. Run a Full Check:

   ./vendor/bin/duster lint --dirty
   

   • Focuses only on uncommitted changes (faster feedback loop).

3. Fix Issues:

   ./vendor/bin/duster fix --dirty
   

   • Automatically resolves fixable issues (e.g., indentation, class ordering).

Implementation Patterns

Daily Workflow Integration

1. Pre-Commit Hooks (Local Development)

• Pattern: Run Duster on staged changes before committing.

• Implementation:

  ./vendor/bin/duster husky-hooks
  

  • Publishes Husky hooks to trigger duster lint --dirty on git add.

• Why:

  • Catches style issues early without slowing down full-project checks.
  • Reduces merge conflicts from inconsistent code.

• Customization:

  • Modify duster.json to exclude test files or include scripts/:

    {
      "exclude": ["tests/**"],
      "include": ["scripts/**"]
    }
    

2. CI Pipeline (GitHub Actions)

• Pattern: Enforce standards on every push/PR.

• Implementation:

  ./vendor/bin/duster github-actions
  

  • Publishes a pre-configured workflow (/.github/workflows/duster.yml).

• Example Workflow:

  name: Duster Fix
  on: [push, pull_request]
  jobs:
    fix:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - run: composer install --dev
        - run: ./vendor/bin/duster fix
        - run: git config --global user.name "Duster Bot"
        - run: git config --global user.email "duster@example.com"
        - run: git add .
        - run: git commit -m "Apply Duster fixes" || echo "No changes to commit"
        - run: git push
  

• Why:

  • Ensures all code meets standards before merging.
  • Automatically commits fixes (avoid manual steps).

• Gotcha:

  • Workflows that commit may trigger other workflows. Use workflow_run to chain jobs:

    on:
      workflow_run:
        workflows: ["Duster Fix"]
        types: [completed]
    

3. Selective Tool Execution

• Pattern: Run specific tools for targeted checks.
• Implementation:

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

  • Skips PHP_CodeSniffer/PHP CS Fixer (useful for performance).
• Use Cases:
  • TLint: Focus on Laravel-specific issues (e.g., route naming).
  • Pint: Quick syntax fixes (fastest tool).
  • PHPStan: Add to duster.json for static analysis:

    {
      "scripts": {
        "lint": {
          "phpstan": ["./vendor/bin/phpstan", "analyse"]
        }
      }
    }
    

4. Custom Scripts

• Pattern: Extend Duster with additional tools.
• Implementation:
  • Add to duster.json:

    {
      "scripts": {
        "lint": {
          "infection": ["./vendor/bin/infection", "--threads=4", "--show-mutations"]
        },
        "fix": {
          "pint": ["./vendor/bin/pint"]
        }
      }
    }
    

  • Run with:

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

• Why:
  • Centralizes multi-tool workflows (e.g., testing + linting).
  • Reuses Duster’s file filtering and error handling.

Integration Tips

1. Containerized Environments (Sail/Lando)

• Pattern: Run Duster inside containers.
• Implementation:

  ./vendor/bin/sail bin duster lint
  

  • Uses Sail’s PHP binary to avoid local setup.
• Alternative:

  ./vendor/bin/duster --env=sail lint
  

2. Partial Fixes

• Pattern: Fix only specific files.
• Implementation:

  ./vendor/bin/duster fix app/Http/Controllers/
  

  • Targets a directory (uses glob patterns).

3. Dry Runs

• Pattern: Preview changes without applying.
• Implementation:

  ./vendor/bin/duster lint --dirty --dry-run
  

  • Shows what would be fixed (useful for PR reviews).

4. Parallel Execution

• Pattern: Speed up linting with parallel tools.
• Implementation:
  • PHP CS Fixer supports parallel runs (enabled by default in v3.1+).
  • Combine with --using to control order:

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

Gotchas and Tips

Pitfalls

1. Blade File Exclusions:

   • Gotcha: PHP_CodeSniffer may incorrectly flag Blade files.
   • Fix: Exclude Blade files in .phpcs.xml.dist:

     <arg name="exclude" value="resources/views"/>
     

   • Note: Duster v3.4.1+ manually excludes Blade files, but custom configs may override this.

2. TLint Fix Failures:

   • Gotcha: duster fix may fail if TLint finds non-fixable issues.
   • Fix: Use --using="pint,php-cs-fixer" to skip TLint fixes:

     ./vendor/bin/duster fix --using="pint,php-cs-fixer"
     

3. Git Hook Conflicts:

   • Gotcha: Husky hooks may conflict with other tools (e.g., laravel-pint).
   • Fix: Use npx husky add .husky/pre-commit "..." to merge hooks manually.

4. Performance with Large Codebases:

   • Gotcha: Full linting can be slow (e.g., 10k+ files).
   • Fix:
     • Use --dirty for local work.
     • Exclude heavy directories (e.g., vendor/, storage/) in duster.json:

       {
         "exclude": ["vendor/**", "storage/**"]
       }
       

5. Custom Config Overrides:

   • Gotcha: Custom .php-cs-fixer.dist.php may break Duster’s defaults.
   • Fix: Extend Duster’s config instead of replacing:

     return (new PhpCsFixer\Config())
         ->set