Duster Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Laravel-native: Built for Laravel, leveraging Laravel’s Pint (Laravel’s built-in PHP formatter) and integrating seamlessly with its ecosystem (e.g., Sail, GitHub Actions).
  • Modular Design: Orchestrates multiple tools (TLint, PHP_CodeSniffer, PHP CS Fixer, Pint) under a unified CLI, reducing tooling fragmentation.
  • Config-Driven: Supports granular customization via duster.json, aligning with Laravel’s preference for declarative configuration (e.g., .env, config/).
  • Opinionated but Extensible: Enforces Tighten’s standards by default but allows overrides (e.g., custom phpcs.xml, pint.json), catering to teams with specific needs.
  • Git-Aware: Supports --dirty flag for linting only uncommitted changes, integrating with Git workflows (e.g., pre-commit hooks).

• Weaknesses:

  • Tighten-Centric: Standards are opinionated (e.g., Tighten preset for PHP_CodeSniffer). Teams not aligned with Tighten’s conventions may need significant customization.
  • Toolchain Dependency: Relies on external tools (TLint, PHP_CodeSniffer, etc.), adding complexity if these tools are already managed separately.
  • Laravel-Specific: Limited utility for non-Laravel PHP projects (e.g., Symfony, custom PHP apps), despite using generic tools under the hood.

Integration Feasibility

• Laravel Projects:

  • High Feasibility: Ideal for Laravel monorepos or teams adopting Tighten’s standards. Works out-of-the-box with Laravel’s Pint and Sail.
  • CI/CD: Native GitHub Action support simplifies integration into CI pipelines (e.g., GitHub Actions, GitLab CI).
  • Local Dev: Husky hooks enable pre-commit linting/fixing, reducing merge conflicts and enforcing consistency early.

• Non-Laravel PHP Projects:

  • Medium Feasibility: Can be adapted but requires manual configuration (e.g., replacing Pint with PHP-CS-Fixer, adjusting file globs).
  • Overhead: May not justify adoption if the project already uses standalone tools (e.g., php-cs-fixer, psalm).

• Polyglot Repos:

  • Low Feasibility: Focused on PHP/Laravel; limited support for non-PHP files (e.g., JavaScript, TypeScript) unless extended via duster.json scripts.

Technical Risk

• Low Risk for Laravel Teams:

  • Minimal setup required for basic usage (composer require + ./vendor/bin/duster lint).
  • Well-documented with clear migration paths (e.g., publishing configs, customizing tools).
  • Active maintenance (releases every 3–6 months, 594 stars, MIT license).

• Moderate Risk for Customization:

  • Toolchain Conflicts: Overriding defaults (e.g., custom PHP_CodeSniffer rules) may introduce edge cases (e.g., rule collisions, tool version mismatches).
  • Performance: Parallel execution of tools (e.g., PHP CS Fixer) could strain CI resources if not tuned (e.g., processTimeout in duster.json).
  • Blade File Handling: Explicit exclusion of Blade files from PHPCS (v3.4.1) suggests potential quirks with template files.

• High Risk for Non-Laravel Adoption:

  • Assumes Pint and Laravel’s tooling ecosystem, which may not align with other frameworks.
  • Requires manual mapping of Laravel-specific configs (e.g., pint.json) to equivalent tools in other ecosystems.

Key Questions for TPM

1. Alignment with Standards:

   • Does the team adopt Tighten’s coding standards, or will heavy customization be required?
   • Are there existing tooling conflicts (e.g., custom PHPCS rules, alternative formatters)?

2. Toolchain Maturity:

   • Are TLint, PHP_CodeSniffer, and PHP CS Fixer already used in the project? If not, what’s the cost of adopting them?
   • What’s the team’s experience with Laravel Pint? Will Duster’s Pint customizations cause friction?

3. CI/CD Impact:

   • How will Duster integrate with existing CI pipelines? Will it replace or augment current linting/fixing steps?
   • What’s the expected runtime for duster fix in CI? Are there resource constraints (e.g., memory, timeouts)?

4. Developer Experience:

   • Should Duster be mandatory (e.g., via Husky) or optional (e.g., local dev only)?
   • How will teams handle false positives/negatives in Tighten’s presets?

5. Long-Term Viability:

   • Is Tighten’s maintenance of Duster sustainable? Are there alternatives (e.g., Laravel’s built-in tools, custom scripts)?
   • How will Duster evolve with Laravel’s Pint or PHP tooling changes (e.g., PHP 8.3+ features)?

Integration Approach

Stack Fit

• Primary Fit:

  • Laravel Monorepos: Ideal for teams using Laravel, Sail, and GitHub Actions. Leverages native tooling (Pint) and CI integrations.
  • PHP-Centric Teams: Suitable for projects already using TLint, PHP_CodeSniffer, or PHP CS Fixer, offering a unified interface.

• Secondary Fit:

  • Hybrid PHP Projects: Can integrate with non-Laravel PHP codebases but requires manual configuration (e.g., replacing Pint, adjusting file globs).
  • Polyglot Repos: Limited value unless extended via duster.json scripts (e.g., adding JavaScript linters).

• Non-Fit:

  • Non-PHP Projects: No direct utility.
  • Teams with Strong Existing Tooling: If the team already has mature linting/fixing pipelines, Duster may add unnecessary complexity.

Migration Path

1. Assessment Phase:

   • Audit existing linting/fixing tools (e.g., php-cs-fixer, psalm, eslint).
   • Compare Tighten’s standards with current conventions (e.g., PSR-12, custom rules).
   • Identify conflicts (e.g., overlapping PHPCS rules, Pint vs. PHP CS Fixer).

2. Pilot Integration:

   • Install Duster in a dev branch: composer require tightenco/duster --dev.
   • Run ./vendor/bin/duster lint to evaluate output. Fix critical issues manually first.
   • Test ./vendor/bin/duster fix on a subset of files (e.g., app/ directory).

3. Configuration Alignment:

   • Publish Duster configs:

     ./vendor/bin/duster github-actions  # For CI
     ./vendor/bin/duster husky-hooks     # For local dev
     

   • Customize duster.json to:
     • Include/exclude directories (e.g., tests, vendor).
     • Add custom scripts (e.g., phpstan, pest).
     • Adjust tool order or exclusions (e.g., Blade files).

4. Toolchain Migration:

   • Replace standalone tools with Duster where applicable:
     • Replace ./vendor/bin/php-cs-fixer fix with ./vendor/bin/duster fix.
     • Replace ./vendor/bin/pint with Duster’s Pint integration.
   • Update CI pipelines to use the GitHub Action or direct CLI calls.

5. Gradual Rollout:

   • Enforce Duster in CI first (e.g., block PRs with linting errors).
   • Add Husky hooks for local enforcement (optional).
   • Phase out legacy tooling post-migration.

Compatibility

• Laravel Versions:

  • Compatible with Laravel 8+ (Pint is Laravel 8+). Test with the target Laravel version.
  • Sail support is built-in (v1.x tested; verify compatibility with Sail v2+ if used).

• PHP Versions:

  • Requires PHP 8.0+ (check composer.json constraints). Test with the project’s PHP version.

• Tool Dependencies:

  • TLint: Requires Node.js (for tlint CLI). Version compatibility may vary.
  • PHP_CodeSniffer: Must match the Tighten standard (v3.x tested).
  • PHP CS Fixer: Uses custom rules; ensure version aligns with Duster’s (e.g., v3.x).
  • Pint: Laravel’s Pint (v1.x). Conflicts possible if custom Pint configs exist.

• Git Integration:

  • Assumes Git for --dirty flag. Works with Git 2.0+. Test with the project’s Git setup.

Sequencing

1. Pre-Migration:

   • Backup existing configs (e.g., .php-cs-fixer.dist.php, pint.json).
   • Document current linting/fixing workflows.

2. Core Integration:

   • Install Duster and publish configs.
   • Run duster lint and duster fix in a staging environment