Haiku Laravel Package

Technical Evaluation

Package: realodix/haiku — an opinionated PHP-CS-Fixer preset/ruleset for Laravel codebases, distributing custom lint rules (detection) and fixer rules (auto-correction) via a Composer dev dependency.

Architecture fit: Consumes PHP-CS-Fixer's rule API and plugs in as a config-level dependency, not a runtime service provider. It sits entirely in the developer toolchain (local pre-commit, CI static-analysis stage). No coupling to application code, containers, or framework bootstrapping — a low-blast-radius integration appropriate for any Laravel/PHP repo already using PHP-CS-Fixer.

Integration feasibility: Straightforward. Add as require-dev, reference the preset in .php-cs-fixer.dist.php, run in CI. No migrations, no schema, no config services. The only real integration surface is the rule-name strings in the project's fixer config — which is precisely where this release introduces risk.

Technical risk — v1.13.32 specifics:

1. Feature removal in a patch release (highest concern). [fixer] remove "removeUnnecessaryWildcard" deletes a fixer rule. Any project config that names this rule explicitly — in ->setRules(), a rules array, or a custom preset extension — will hard-fail on upgrade with an unknown-rule error, breaking CI and local composer install on a fresh clone. Shipping a removal under 1.13.31 → 1.13.32 violates semver expectations for patch releases and means a permissive ^1.13 constraint silently absorbs a breaking change.
2. Two new lint rules (bad cosmetic rule separator, wrong domain separator) expand the detection surface. New detections are non-breaking for the library but are potentially breaking for consuming pipelines: previously green branches may go red on the next dependency refresh with zero code changes. Whether these are autofixable determines whether the impact is "one fix run" or "manual remediation across the codebase."
3. Improved exception-rule check — directionally positive (fewer false positives or better coverage), but undirected: could equally introduce new findings. Needs a dry-run diff to characterise.
4. Low inherent risk — four changes, no runtime code, no security surface, no production dependency.

Key questions for the maintainer / to resolve before rollout:

• Is the removeUnnecessaryWildcard removal intentional and permanent, or a deprecation with a follow-up alias? Was it documented as breaking anywhere other than the changelog line?
• Do the two new lint rules ship with fixers, or are they report-only? Are they in the default preset or opt-in?
• Does this release require a minimum PHP-CS-Fixer version bump that we must coordinate?
• Why a patch bump for a removal — should we expect retroactive semver correction?

Integration Approach

Stack fit: Dev-dependency only (require-dev); must never enter production autoload or the deploy artifact. Fits any Laravel/PHP repo using PHP-CS-Fixer 3.x. No interaction with PHP/Laravel version constraints beyond the underlying fixer's own requirements.

Migration path:

1. Pin the current known-good version exactly (e.g. 1.13.31) in composer.json to stop silent absorption of future patch-level removals — this is the single highest-value action.
2. On a scratch branch, bump to 1.13.32 and grep the repo for removeUnnecessaryWildcard across .php-cs-fixer.php, .php-cs-fixer.dist.php, composer.json scripts, and any shared internal preset packages. Remove or replace the reference before running.
3. Execute php-cs-fixer fix --dry-run --diff to enumerate findings from the two new lint rules. Measure the violation count and cluster by directory to size remediation.
4. If autofixable, apply the fixer in an isolated "style-only" commit and merge fast to keep the diff reviewable. If report-only, either remediate or explicitly exclude the new rules in config until scheduled.

Compatibility: Backward-incompatible for configs referencing the removed rule; forward-compatible otherwise. No PHP version, framework, or database compatibility concerns. No impact on other dependencies.

Sequencing: Independent of any application release train — it can ship on its own cadence. Recommended order: (a) pin to last-good, (b) assess removed-rule usage, (c) dry-run diff for sizing, (d) upgrade + fix commit in the same PR, (e) unblock CI. Budget: roughly half a day for a mid-size repo, dominated by reviewing the style diff rather than the upgrade itself.

Operational Impact

Maintenance: Ongoing cost is near-zero when the preset is used as-is; cost rises sharply wherever the team overrides individual rules by name, since those overrides are the fragile surface exposed by this release. Recommend an internal "style config" convention: consume the preset wholesale, pin exactly, and record any rule exclusion with a reason and a review date.

Support: No vendor support path; upstream is a small open-source project, so response to semver questions is best-effort. Internal ownership should sit with the platform/tooling engineer who owns CI, not with feature teams. Escalation for "CI is red and nobody changed code" should route directly to that owner.

Scaling: Effectively constant — lint runs scale with repo size and file count, not with traffic. Very large monorepos may see meaningful CI minutes on full-repo dry runs; mitigate with changed-files-only or path-scoped runs. No runtime or capacity considerations whatsoever.

Failure modes:

• Hard fail: unknown rule name in config after upgrade → CI and fresh-clone composer install/fix both break. Highest severity, easily detected, fast to fix.
• Silent red CI: new lint rules fire on untouched code → blocked PRs, developer confusion, pressure to bypass lint. Detect via dry-run before merge.
• Config drift: teams disable a rule locally to unblock, the exclusion propagates, and the standard quietly erodes. Mitigate by centralising the config and reviewing exclusions.
• Supply-chain: unpinned patch upgrades import unannounced breaking changes — the exact scenario demonstrated here.

Ramp-up: Very low. An engineer familiar with PHP-CS-Fixer is productive in under an hour; unfamiliar developers need only the two commands (fix, fix --dry-run) and the convention that style failures are auto-resolvable. The genuine learning is organisational, not technical: treat style-tool upgrades as dependency upgrades with a dry-run gate, not as free patch bumps.

TPM recommendation: Adopt the upgrade, but gate it on the config-reference grep and dry-run diff, and immediately tighten the version constraint. Raise the patch-level feature removal upstream as a semver concern — the outcome of that conversation determines whether this repo can ever use caret ranges for this package again.