Duster Laravel Package

Product Decisions This Supports

The core decision it de-risks: do we adopt an opinionated code-style baseline, and if so whose? Duster is a thin orchestration wrapper that bundles four established tools (Pint, TLint, PHP_CodeSniffer, PHP CS Fixer) behind one lint / fix command and one published set of standards (pint.json, .php-cs-fixer.dist.php, .phpcs.xml.dist, style guide). It converts a recurring, unbounded committee debate into a 30-minute install decision.

Build vs. buy

• Buy signal: the wrapper itself is trivial; the durable value is the maintenance of the wrapper — Pint version alignment, PHPCS path/cwd handling, glob handling, PHP version support drops (v2.0.0 dropped PHP 8.0), and dependency bumps (releases show repeated Guzzle/PHPCS updates). That churn is the real cost Duster absorbs for you.
• Build signal: if your house style materially diverges from Tighten's preset, you are buying an opinion you'll spend the next year configuring around. In that case, use Duster as a reference implementation — copy the bundled standards files into your repo, wrap your own binaries, and keep your ruleset as the source of truth. You get the ergonomics without adopting a vendor's identity as your standard.

Use cases worth estimating and instrumenting

• Onboarding: new engineers get a working, defensible format in one command instead of a wiki page.
• Legacy remediation: duster fix --dirty lets you burn down style debt incrementally on touched files only, rather than an unreviewable mega-commit.
• CI gating: duster lint as a required check; the companion GitHub Action (and duster github-actions stub publishing) removes pipeline scaffolding work.
• Toolchain consolidation: --using="phpstan,tlint,pint" and the scripts block in duster.json let you pull adjacent checks (e.g., static analysis) into the same gate without a second orchestration layer.
• Containerized dev parity: --env=ddev|warden|lando|sail means local and CI invoke the same toolchain — removes a whole class of "works on my machine" format diffs.

What it explicitly does not decide — keep these separate on the roadmap: static analysis depth, security/dependency auditing, test coverage thresholds, architecture/layering enforcement. The biggest product risk here is organizational conflation: "we run Duster, so we have quality gates." Duster is formatter/lint hygiene, not correctness.

When to Consider This Package

Adopt when all of these hold

• Stack is PHP + Laravel (Pint's ruleset is Laravel-shaped); PHP 8.1+ realistically, given 8.0 was dropped at v2.0.0.
• You have no house style yet, or an existing one close enough to Tighten's that deviation is the exception, not the rule.
• Team size/cadence makes an opinionated default strictly cheaper than a committee-authored ruleset.
• A require --dev dependency is acceptable and dev-only risk tolerance exists.
• You can actually wire it into a gate (GitHub Actions and Husky stubs are published; if neither fits your CI, you're buying half the value).

Tells that you need this now: PRs dominated by whitespace/import-order/class-element-order nits; repeated reviewer debates on the same trivialities; inconsistent env() usage across services.

Look elsewhere when

• Stack is non-Laravel PHP, or a polyglot monorepo where one PHP-only formatter is a partial answer.
• You already run a mature, deliberately authored PHP CS Fixer / PHPCS ruleset — Duster will compete with it, and you'll end up maintaining config in two places.
• You need static analysis enforced in the same tool, not merely scriptable alongside it.
• You require pinned, auditable, or vendored tool versions and can't take transitive bumps.
• Branch protection forbids automated commits — the GitHub Action's fix mode commits to your repo, which cancels in-flight workflows and does not trigger new ones; you must chain downstream jobs via workflow_run. This is an ops-design decision, not a footnote.
• Procurement/culture rejects adopting a vendor-branded standard (the name is literally "Tighten's standard").

Risks to carry explicitly

• Opinionated preset drift: Tighten-specific rules (custom class-element ordering, env() ban with tests excluded) mean every deviation becomes duster.json plus per-tool config sprawl — config surface grows faster than the value.
• Adoption signal is thin: zero dependents on the tracked index, no stars data, maturity limited to README + releases, no support SLA. Mitigation: it's dev-only, the removal cost is composer remove + a CI step swap, and the most portable asset (the standards files) can be snapshotted into your repo.
• Release cadence is dependency-driven, not roadmap-driven: plan for routine version bumps in your maintenance budget, and pin in CI so an upstream bump doesn't break the build on a Friday.

How to Pitch It (Stakeholders)

Executives (60 seconds). One dev-only dependency that ends the "how should our Laravel code look" debate and gives every engineer and every pipeline the same two commands: duster lint and duster fix. The cost is a dev dependency and roughly a day of rollout; the return is reviewer hours back, smaller and more reviewable diffs, and faster onboarding. It does not replace security scanning or static analysis — it removes the noise that hides them.

Engineering leadership. Standardizes four tools behind one command, one config file, and one published standard, with first-class support for containerized environments (Sail, ddev, warden, lando) so local and CI agree. --dirty enables incremental cleanup instead of a legacy-repo big bang. duster.json scripts lets us fold in PHPStan later without re-platforming. Cost of reversal is low and bounded.

Engineering team. Install: composer require tightenco/duster --dev. Daily loop: ./vendor/bin/duster fix --dirty before commit, lint before push. Configure includes/excludes and extra scripts in duster.json; select or reorder tools with --using. Publish GitHub Actions or Husky hooks with the built-in commands. If you disagree with a rule, propose a config change — not a per-PR exception.

How we'll know it worked (proposed success metrics). Share of PR review comments that are style-only (target: → 0); PR review turnaround time; CI lint stage duration; time-to-first-merged-PR for new hires; count of style-only bot commits (a rising count hints the local hook isn't doing its job).

Rollout sequence. Pilot on one repo in lint-only / report mode → promote the resulting duster.json plus standards files as the org baseline → flip to fix mode with workflow_run chaining → add Husky hooks and fix --dirty locally → layer PHPStan in via scripts.lint. Exit criteria: standards configs snapshot into each repo, so removal is a dependency delete plus a CI step swap.