Php Styler Laravel Package

Product Decisions This Supports

• Adopt an opinionated ("Black/Prettier-style") formatter vs. an incremental fixer. PHP-Styler reformats files from scratch rather than patching rule violations one at a time. That's a policy choice, not a tooling choice: it ends formatting debates permanently, but it also means your team loses all hand-crafted alignment and layout on day one. This package only makes sense if the org has decided determinism beats expressiveness.
• Whether to spend engineering time on code-standard debates at all. With a zero-dependency, MIT-licensed, single-command formatter, the marginal cost of "just pick a format and move on" drops to near zero. This is a lever for reducing review-cycle time and PR noise.
• Standardizing multiple repos or a monorepo split. The declarative Format object (PHP code returning a Config) is versionable and diffable, which supports a "one format definition, many repos" rollout — attractive for platform teams who want a shared php-styler.php in a base template.
• Enforcing formatting as a CI gate. The check command returns exit code 1 on drift, so it fits a build-pipeline decision: format-check on PR, apply in a pre-commit hook or a scheduled bot commit.
• Migration sequencing and blame hygiene. The .git-blame-ignore-revs workflow explicitly supports a real product decision: "we accept one large, disposable reformat commit." That's a planning item (freeze window, comms, git blame config per developer) more than an engineering item.
• Choosing between "close enough" and "certified" compliance. The vendor formats (Percs30Format, SymfonyFormat, DoctrineFormat) approximate popular standards. If a decision hinges on auditable PSR-12/PER compliance, this package is not the answer regardless of how good the output looks.
• Build vs. buy is effectively settled — it's free and dependency-light — but the true cost is migration churn and lock-in to a 0.x configuration API, not licensing.

When to Consider This Package

Consider it when:

• The codebase is greenfield or internal, small-to-mid size, with low concurrent-merge pressure — the blast radius of a full reformat is containable.
• The team is philosophically aligned with opinionated formatters and has explicitly agreed that machine layout wins over human layout (accept that aligned = and -> chains get flattened).
• You are on PHP 8.4+ and comfortable on the bleeding edge. Note the internal inconsistency: the README introduction still says PHP 8.1 while the 0.17.0 changelog mandates 8.4 — treat documentation as drifting and verify against the code, not the prose.
• You want a single, fast, dependency-free CLI in CI with no extension requirements (parallel workers via proc_open, portable to Windows), and you value a config that lives in php-styler.php as first-class PHP rather than YAML/XML.
• You can pin an exact version and own the upgrade work. This is a 0.x package whose last minor release was a ground-up rewrite with multiple breaking changes.

Look elsewhere when:

• You are a standard Laravel application. Laravel Pint already ships with the framework, wraps the category-leading PHP CS Fixer, and is zero-config. Choosing PHP-Styler here means paying integration and maintenance cost for a strictly smaller ecosystem.
• You need certifiable adherence to PSR-12/PER Coding Style, IDE/editor integration, pre-commit hook ecosystem support, or rule-by-rule suppressions — PHP CS Fixer and PHP_CodeSniffer own that terrain.
• Your PHP floor is below 8.4, or you maintain packages supporting multiple PHP versions.
• You have a large, actively-branched codebase where a repo-wide reformat would strand open PRs and poison git blame for months.
• You rely on horizontal alignment in arrays, constants, or chained assignments — the tool intentionally de-aligns it.
• You need vendor support, SLAs, or a bus-factor guarantee: 42 stars, 0 dependents, and a single maintainer. The author's standing in the PHP community (Aura/Solar lineage, ADR advocacy) is meaningful social proof, but it is not a support contract.

How to Pitch It (Stakeholders)

Executive framing: A free, MIT-licensed, self-contained PHP formatter that removes formatting from code review entirely. No new runtime dependency, no licensing cost, no PHP extensions, runs in parallel. The pitch is cycle time and onboarding, not features — reviewers stop commenting on whitespace, and new engineers get a machine-enforced house style on their first commit.

Engineering framing: An opinionated reformatter in the Black/Prettier mold, built on PHP's native PhpToken lexer with a clean six-stage pipeline (parse → token rules → assemble → split → line rules → render). Customization is declarative — Format objects composing styles, rules, and parseAs — so house style is a reviewable PHP file rather than a pile of overrides. Ships PlainFormat and DeclarationFormat plus vendor approximations, supports automatic line-length splitting with prioritized split points and an @php-styler-expansive escape hatch, and offers preview/diff/check so the change is auditable before it lands.

The honest caveat to lead with, not bury: it completely discards existing formatting. Landing it means one big reformat commit, a .git-blame-ignore-revs entry, a coordinated freeze, and a pinned version while the project is pre-1.0. Recommend a time-boxed trial on a single non-critical package first — run diff on one directory, measure how much churn is stylistic vs. semantic, and only then decide whether the determinism payoff justifies the transition cost. If the trial shows heavy diff noise on code we care about, the correct product decision is to stay on Pint/PHP CS Fixer and revisit at 1.0.