Duster Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation:

   composer require tightenco/duster --dev
   

   This installs Duster as a dev dependency, ensuring it’s only used in development environments.

2. First Run:

   ./vendor/bin/duster lint
   

   This runs all configured linters (TLint, PHP_CodeSniffer, Pint, and PHP CS Fixer) against your project to check for style violations.

3. Fix Issues:

   ./vendor/bin/duster fix
   

   Automatically applies fixable style violations (where supported by the tools).

4. Check Only Modified Files (Git-aware):

   ./vendor/bin/duster lint --dirty
   

   Focuses linting on uncommitted changes, speeding up local development workflows.

Where to Look First

• duster.json: Customize file inclusion/exclusion and add custom scripts.
• Tool-Specific Configs:
  • tlint.json (TLint)
  • .phpcs.xml.dist (PHP_CodeSniffer)
  • .php-cs-fixer.dist.php (PHP CS Fixer)
  • pint.json (Pint)
• GitHub Actions: Use the tighten/duster-action for CI integration.

First Use Case: Onboarding a New Developer

Run ./vendor/bin/duster lint in the project root to enforce consistent code standards immediately. Pair with Git hooks (e.g., Husky) to prevent commits with violations:

./vendor/bin/duster husky-hooks

Implementation Patterns

Core Workflows

1. Local Development:

   • Pre-commit Hooks: Use duster husky-hooks to block commits with style issues.

     ./vendor/bin/duster husky-hooks --env=sail  # For Laravel Sail
     

   • CI Pipeline: Integrate duster lint in GitHub Actions to fail builds on violations.

     - name: Lint Code
       uses: tighten/duster-action@v1
       with:
         command: lint
     

2. Team Onboarding:

   • Publish Duster’s standard configs (e.g., .php-cs-fixer.dist.php) to the project root.
   • Document the style guide for new hires.

3. Custom Toolchains:

   • Extend duster.json to include additional tools (e.g., PHPStan):

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

   • Run custom tools alongside Duster:

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

Integration Tips

• Laravel Sail: Use the Sail wrapper to avoid PHP environment issues:

  ./vendor/bin/sail bin duster lint
  

• Parallel Execution: PHP CS Fixer supports parallel runs (v3.1+). Enable via:

  ./vendor/bin/duster fix --parallel
  

• Exclusion Strategies: Exclude test fixtures or generated files in duster.json:

  {
    "exclude": ["tests/fixtures", "storage/framework/**"]
  }
  

Gotchas and Tips

Pitfalls

1. Blade File Handling:

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

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

   • Fix: Updated in v3.4.1 to auto-exclude Blade files.

2. TLint Fix Failures:

   • TLint’s fix command fails if linting finds issues (v3.0+). Use --allow-fix-on-error to bypass:

     ./vendor/bin/duster fix --allow-fix-on-error
     

3. Git Hook Conflicts:

   • Husky hooks may conflict with other tools (e.g., Laravel Valet). Use --env to target specific environments:

     ./vendor/bin/duster husky-hooks --env=ddev
     

4. Tool Version Mismatches:

   • Duster pins tool versions (e.g., PHP CS Fixer). Upgrade tools manually if breaking changes occur:

     composer require friendsofphp/php-cs-fixer --dev
     

Debugging

• Verbose Output: Use --verbose to debug tool execution:

  ./vendor/bin/duster lint --verbose
  

• Dry Runs: Test configs without modifying files:

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

• Tool-Specific Logs: Redirect output to files for analysis:

  ./vendor/bin/duster lint --using="tlint" > tlint.log
  

Extension Points

1. Custom Scripts: Add scripts to duster.json for tool-agnostic workflows (e.g., security scans):

   {
     "scripts": {
       "lint": {
         "security-check": ["./vendor/bin/roave-security-check", "check"]
       }
     }
   }
   

2. Tool Ordering: Override default execution order with --using:

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

3. Environment Variables: Pass env vars to custom scripts:

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

Configuration Quirks

• Default Excludes: Duster excludes common files (e.g., vendor/, node_modules/). Override in duster.json:

  {
    "exclude": ["!vendor/bin/duster"]  # Re-include Duster itself
  }
  

• PHPStan Integration: PHPStan isn’t included by default. Add it to scripts in duster.json and install it:

  composer require --dev phpstan/phpstan
  

Pro Tips

• Atomic Commits: Use duster lint --dirty before committing to ensure only relevant files are checked.
• CI Optimization: Cache tool dependencies (e.g., PHP CS Fixer) in GitHub Actions to speed up runs:

  - uses: actions/cache@v3
    with:
      path: ~/.config/composer/vendor
      key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
  

• Style Guide Alignment: Reference the Duster style guide when discussing PRs to align on expectations.