Duster Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Laravel-native: Built for Laravel, leveraging Laravel’s Pint, TLint, PHP_CodeSniffer, and PHP CS Fixer with Tighten’s opinionated presets. Aligns with Laravel’s ecosystem and tooling.
  • Modular Design: Integrates multiple tools (Pint, TLint, PHPCS, PHP CS Fixer) in a configurable pipeline, allowing selective inclusion/exclusion of tools via --using flag.
  • Extensible: Supports custom scripts (e.g., PHPStan) via duster.json, enabling integration with additional tools without forking the package.
  • Git-Aware: --dirty flag restricts operations to uncommitted changes, reducing noise in CI/CD pipelines.
  • Container-Friendly: Explicit support for Laravel Sail, DDEV, Lando, and Warden, reducing friction in containerized environments.

• Potential Misalignments:

  • Opinionated Standards: Enforces Tighten’s presets (e.g., Tighten PHPCS ruleset, custom Pint/PHP CS Fixer rules). Teams with divergent coding standards may need to override defaults, increasing maintenance overhead.
  • Tooling Dependencies: Relies on external tools (Pint, TLint, etc.), which may introduce version conflicts or require additional setup (e.g., PHPStan).
  • CI/CD Complexity: GitHub Actions workflows that commit changes (e.g., duster fix) may disrupt other workflows, requiring careful sequencing (as noted in the docs).

Integration Feasibility

• Laravel Projects:
  • Seamless: Designed for Laravel, with native support for Sail and Pint. Minimal boilerplate required beyond composer require.
  • Preconfigured: Provides starter configs for PHPCS, Pint, and PHP CS Fixer, reducing setup time.
• Non-Laravel PHP Projects:
  • Partial Fit: Can be used for PHP projects, but lacks Laravel-specific optimizations (e.g., Blade template handling). Requires manual configuration for non-Laravel files/directories.
• Monorepos:
  • Challenging: Glob patterns may need adjustment to avoid scanning unrelated projects. duster.json can mitigate this, but testing is required.
• Legacy Codebases:
  • High Risk: Strict linting/fixing may break existing code. Recommend running in --dirty mode first or phasing adoption incrementally.

Technical Risk

Key Questions for TPM

1. Standards Alignment:
   • Does the team’s existing codebase adhere to Tighten’s presets (e.g., PSR1 + Tighten rules)? If not, what’s the effort to customize?
2. Tooling Stack:
   • Are Pint, TLint, PHPCS, and PHP CS Fixer already in use? If not, what’s the cost to adopt them?
3. CI/CD Impact:
   • How will duster fix (which commits changes) interact with existing workflows? Will it require workflow sequencing?
4. Performance:
   • What’s the expected codebase size? Will parallelization or --dirty mode be sufficient, or are optimizations needed?
5. Maintenance:
   • Who will own updates to tool versions (e.g., Pint, PHPCS)? Will this package be forked or kept upstream?
6. Local Development:
   • Should Husky hooks or GitHub Actions be prioritized for local enforcement? What’s the trade-off between speed and coverage?

Integration Approach

Stack Fit

• Primary Use Case: Laravel applications using PHP 8.1+ (Duster v3.x requires Laravel Zero 11, which supports PHP 8.1+).
• Tooling Compatibility:
  • Native: Pint, TLint, PHPCS, PHP CS Fixer (with Tighten presets).
  • Extensible: Supports custom scripts (e.g., PHPStan, Pest) via duster.json.
  • Containerized: Optimized for Sail, DDEV, Lando, and Warden.
• Non-Laravel PHP:
  • Possible but requires manual configuration (e.g., excluding Laravel-specific files like Blade templates).

Migration Path

1. Assessment Phase:
   • Audit existing codebase against Tighten’s standards using duster lint --dirty to identify gaps.
   • Customize duster.json to exclude non-PHP files/directories (e.g., vendor/, node_modules/).
2. Pilot Phase:
   • Integrate duster fix in a feature branch, focusing on new code or low-risk areas.
   • Test locally with Husky hooks or in CI with GitHub Actions.
3. Full Adoption:
   • Roll out duster fix to main branch, phasing in tool-by-tool (e.g., start with Pint, then PHPCS).
   • Update CI/CD to run duster lint on PRs and duster fix on protected branches (with approval gates).
4. Optimization:
   • Adjust processTimeout in duster.json if scripts time out.
   • Parallelize PHP CS Fixer for large codebases.

Compatibility

Sequencing

1. Pre-requisites:
   • Install dependencies: composer require tightenco/duster --dev.
   • Publish configs: ./vendor/bin/duster github-actions or ./vendor/bin/duster husky-hooks.
2. Core Integration:
   • Add duster lint to CI linting stage (e.g., GitHub Actions pull_request).
   • Add duster fix to CI/CD merge stage (e.g., push to main), with approval gates.
3. Local Enforcement:
   • Enable Husky hooks for pre-commit checks (if using Git).
4. Extensibility:
   • Add custom scripts (e.g., PHPStan) to duster.json post-adoption.
5. Monitoring:
   • Track CI/CD failure rates and adjust timeouts/rules as needed.

Operational Impact

Maintenance

• Pros:
  • Centralized Configs: Single duster.json file manages tooling, reducing duplication.
  • Upstream Updates: Tighten maintains the package; updates to Pint/PHPCS/TLint are handled via Composer.
  • Isolated Tools: Custom scripts can be added/removed without affecting core tools.
• Cons:
  • Dependency Management: Requires monitoring for Pint/PHPCS/TLint updates (e.g., breaking changes in PHP CS Fixer).
  • Customization Drift: Overriding defaults (e.g., PHPCS rules) may diverge from upstream, increasing maintenance.
• Ownership:
  • Assign a team member to review tooling updates and test major versions (e.g., Pint 1.0 → 2.0).

Support

• Developer Experience:
  • Pros:
    • Clear error messages with tool-specific output (e.g., PHPCS line numbers).
    • --dirty mode reduces noise for large teams.
  • Cons:
    • Complex error chains (e.g., PHPCS → Pint → TLint) may obscure root causes.
    • GitHub