Grumphp Bom Task Laravel Package

Technical Evaluation

Architecture Fit

• Minimalist and Targeted (Unchanged): The package remains a GrumPHP task extension for UTF-8 BOM-free files, keeping its non-invasive nature and alignment with pre-commit/pre-push static analysis in PHP/Laravel ecosystems.
• Major Line Change — 10.x → 11.x: The new release is tagged 11.1.1, moving off the 10.x branch that the previous assessment was based on. A major version bump is a signal to validate, even though the visible change is hygiene-oriented.
• Nature of the Change: The 11.1.1 notes ([TASK] remove unused imports by default, plus a Rector follow-up) describe internal code hygiene of the package itself — dead import removal in its own source and Rector configuration. This is not a change to BOM detection semantics, file-type coverage, or the grumphp.yml contract.
• Laravel Synergy (Unchanged): Still supports Laravel-relevant file types (.env, composer.json, Blade templates) and enforces UTF-8 encoding standards, complementing Laravel's PSR-12 and configuration reliability.

Integration Feasibility

• Low-Coupling Design (Unchanged): The task remains self-contained and configurable via grumphp.yml, requiring no changes to Laravel's core or third-party libraries beyond GrumPHP.
• Behavioral Compatibility: No functional changes identified in the release notes, so task output and configuration surface should be identical to 10.x. This is the primary reason the release is low-risk despite the major version number.
• Version Support Must Be Re-Confirmed: The previous assessment asserted GrumPHP v0.16–v2.x and PHP 7.3+ support. A major bump is the conventional point at which maintainers drop legacy GrumPHP/PHP versions. Treat prior compatibility claims as unverified for 11.x until the composer.json constraints and CHANGELOG are checked.
• PHP 8.5: The 10.x branch already carried the PHP 8.5 fixes per the prior assessment; confirm the same fixes are present in 11.1.1 (expected, but not stated in these notes).
• No Breaking Changes to Consumer Contract: No deprecations, removals, or configuration changes are mentioned. Rector-related commits affect contributor tooling, not runtime behavior.
• Ramp-Up Bonus: The Rector/unused-import work slightly improves the package's own code quality, marginally reducing audit and review friction for teams with strict static analysis requirements on vendored dev dependencies.

Technical Risk

• Unverified Major-Version Delta (New): The 11.0.0 release notes were not provided, only 11.1.1. The breaking change that justified the major bump may live in 11.0.0. Mitigation: read the CHANGELOG or diff composer.json between 10.2.8 and 11.1.1 before adopting.
• False Positives/Negatives (Unchanged): The package still detects but does not auto-fix BOMs, requiring exclusion rules or whitelisting.
• Performance (Unchanged): No performance-related modifications in this release.
• License Conflict (Unchanged): Still LGPL-3.0, requiring legal review if used in proprietary projects.
• GrumPHP Ecosystem Risk (Unchanged): Monitor GrumPHP's roadmap for potential deprecations of task extensions.
• Support Horizon (Watch Item): Staying on 10.2.8 may become unsupported sooner once 11.x is the active line. Confirm whether the 10.x branch still receives security/maintenance backports.

Key Questions

1. What changed in 11.0.0? — New, highest priority: the major bump is unexplained by the 11.1.1 notes. Request the CHANGELOG entry and minimum PHP/GrumPHP constraints.
2. Does 11.x still support the GrumPHP version we run? — Revised: previously "unchanged"; now must be verified against composer.json.
3. Does 11.x still support our PHP version? — Revised: validate the floor has not moved above the project's runtime, especially for projects still on PHP 8.1.
4. Is GrumPHP already integrated into the Laravel project? — Unchanged: if not, assess adoption effort first.
5. Are BOM-related issues a documented pain point? — Unchanged: evaluate ROI against other quality tools.
6. How will false positives be handled? — Unchanged: plan for exclusion lists or manual overrides.
7. Should BOMs be auto-removed? — Unchanged: requires a custom solution if desired.
8. Does the project's license allow LGPL-3.0 dependencies? — Unchanged: verify compatibility.
9. How will this integrate with existing CI/CD? — Unchanged: decide between local/pre-commit or CI-only enforcement.

Integration Approach

Stack Fit

• Laravel + GrumPHP Synergy (Unchanged): Remains a seamless addition to existing GrumPHP workflows in Laravel.
• CI/CD Alignment (Unchanged): Still ideal for GitHub Actions/GitLab CI static analysis stages; no workflow changes implied.
• Local Development (Unchanged): Works with Laravel's pre-commit hooks (e.g., husky).
• Toolchain Assumption to Re-Validate: If 11.x raised the GrumPHP floor, projects pinned to GrumPHP 0.16–1.x may need a GrumPHP upgrade first. This is the only stack-level sequencing change introduced by this release.

Migration Path

1. Prerequisite Check: Verify GrumPHP is installed and its version satisfies the 11.x constraint in composer.json.
2. Read the 11.0.0 Notes: Confirm the reason for the major bump before touching the lockfile. If 11.0.0 dropped a GrumPHP or PHP version you depend on, stay on 10.2.8 and plan the platform upgrade separately.
3. Install the Task (version reference updated):

   composer require --dev pluswerk/[email protected]
   

   Pin explicitly so the major-line transition is deliberate rather than incidental.
4. Configure grumphp.yml: No change required — no new configuration options were introduced.
5. Test Locally: Run the task against a repo containing at least one known BOM file to confirm behavior is identical to 10.x before removing the old pin.
6. Integrate with CI: No pipeline edits needed — the task invocation is unchanged; only the resolved dependency version moves.
7. Optional: Auto-Removal: Unchanged — still requires a separate pre-commit script.

Compatibility

• GrumPHP Versions: Previously stated v0.16–v2.x; now unverified for 11.x. Treat as a hard gate — check composer.json before upgrading.
• PHP Versions: Previously stated PHP 7.3+ / 8.1+ recommended; now unverified for 11.x. Laravel 10+ projects on PHP 8.1+ are expected to be fine, but confirm the floor.
• File Encoding: Unchanged — assumes UTF-8; may misbehave with non-UTF-8 files.
• Lockfile Impact: Because 11.x is a new major line, dependency resolution may shift transitive dev dependencies. Expect a larger composer.lock diff than a patch release.

Sequencing

1. Phase 0 (New): Compatibility Gate: Read 11.0.0 notes, check composer.json constraints, confirm GrumPHP/PHP support. Decide "upgrade to 11.x" vs. "stay on 10.2.8."
2. Phase 1: Local Validation: Roll out to one backend team / one repository first; confirm BOM detection output is byte-identical to 10.x.
3. Phase 2: CI Enforcement: No structural change — the existing blocking check simply resolves to 11.1.1.
4. Phase 3: Fleet Rollout: Promote across remaining repos once the pilot confirms no behavioral drift.
5. Phase 4: Documentation: Update the README/pinned-version reference from 10.2.8 to 11.1.1 and note the required GrumPHP floor.

Operational Impact

Maintenance

• Low Effort, Higher Confidence: The 11.1.1 change is code hygiene (unused imports removed, Rector config tidied), so no new maintenance burden is expected. Existing grumphp.yml files remain valid.
• Pin to 11.1.1: Update the recommendation — the prior guidance to pin 10.2.8 is superseded for teams that pass the compatibility gate.
• Branch Support Question: Confirm whether 10.x still receives maintenance; if it does not, deferring the upgrade becomes a growing risk rather than a safe default.

Support

• No Changes to Channels: Support requirements and escalation paths are unchanged; GrumPHP community/documentation remains the primary source.
• Issue Triage Note: With a major release in the wild, expect a mix of 10.x-era and 11.x-era issue reports. Record the exact package version in any bug report.
• Community/Commercial: No shift in support model.

Scaling

• Negligible Impact: Performance remains <1s in CI for typical Laravel repos; no scaling changes introduced.
• Large Codebases (Unchanged): May still require exclusion lists for large vendor/ or node_modules/ directories.

Failure Modes

• Dependency Resolution Failure (New): The most likely failure at upgrade is Composer refusing to install 11.1.1 due to a GrumPHP or PHP constraint mismatch. Symptom: install error, not a task error. Resolution: stay on 10.2.8 or upgrade the platform first.
• Silent Behavioral Drift (Low Probability): If 11.0.0 altered file-scanning or path handling, false negatives could appear without obvious errors. Mitigate by testing against a known BOM-fixture repo during the pilot.
• False Positives (Unchanged): May block merges if exclusions are misconfigured.
• GrumPHP Failure (Unchanged): If GrumPHP itself fails, this task does not execute. Monitor GrumPHP logs.
• Encoding Issues (Unchanged): Files with invalid UTF-8 or mixed encodings may behave unexpectedly. Test edge cases.

Ramp-Up

• Developer Training: Unchanged — familiarity with GrumPHP and grumphp.yml is the only prerequisite.
• Onboarding Time: Minimal; configuration is unchanged between 10.x and 11.x.
• Added Up-Front Step: Teams now need one compatibility review pass before the upgrade, which is a short but non-zero TPM/eng task. Budget roughly half a day for the CHANGELOG review, constraint check, and pilot run for the first repository; subsequent repos are copy-paste.