Grumphp Config Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • New shared task: composer_validate_autoload (PR #124): The first change in this line to add a Laravel-relevant quality gate rather than pure backport housekeeping. Autoload drift (renamed/moved classes in app/, packages/, or modular src/ trees not reflected after composer dump-autoload) is a well-known Laravel failure mode that surfaces late — in CI test runs or, worse, in production class not found errors. Catching it as a pre-commit/CI task is directly aligned with how Laravel teams work.
  • GrumPHP-native, no new machinery: The task is an upstream phpro/grumphp v2.x task referenced by documentation link, so it inherits the existing execution model (parallel runner, git hooks, CI invocation). No new plugin API, no new runtime dependency, no additional config surface beyond a tasks: entry.
  • Small, single-purpose, documented change: Contrasted with the 10.2.8 assessment (driven by an undocumented backport, PR #112), this release has a stated changelog, a linked PR, and upstream documentation. The "undocumented change" risk that dominated the prior evaluation is materially reduced for this release.
  • Backward-compatible at the package level: Adding a task to shared config is additive; no existing task names or config keys are removed in the visible changelog.
  • PHP 8.5+ / Laravel 10+ compatibility unchanged: No version constraint changes are implied by the notes.

• Gaps:

  • Default-ON, not opt-in: The task is added to the shared GrumPHP task configuration, meaning every consumer of pluswerk/grumphp-config inherits it on the next upgrade without a config change. For Laravel projects with non-standard autoload setups (classmap-heavy legacy app/ code, generated proxies, multi-namespace modules), this converts an upgrade into a potentially failing upgrade.
  • Version-line divergence (material): The prior assessment was written against 10.2.8; this release is 11.2.0. The published notes cover only 11.1.1...11.2.0. The 10.x → 11.x step is a major bump whose contents (minimum PHP/GrumPHP versions, config key renames, task defaults) are not evidenced in the supplied data and must be reviewed before adoption.
  • Laravel-native task gap persists: Still no shared tasks for route:list, migrate:status, config:cache, artisan optimize, or pint. Custom tasks: entries remain required.
  • No performance or CI/CD work: Neither parallel-execution defaults nor vendor/ exclusion guidance is addressed; this release adds a Composer process to each run, marginally increasing the cost the prior assessment already flagged.
  • No Laravel-specific guidance on interaction with Composer scripts: Laravel's post-autoload-dump hook (@php artisan package:discover) is relevant if the task shells out to Composer without --no-scripts.

Integration Feasibility

• Composer integration: Still zero-friction (composer require --dev), but the major-line change means the previous pin (@10.2.8) is now stale. Pin explicitly (:11.2.0 or ^11.2) and upgrade on a branch with composer update --with-dependencies.
• GrumPHP integration: No extension or plugin required — the task is upstream-supported. Enable/disable via the standard tasks: block, and control ordering via metadata.priority if autoload validation should run before static analysis.
• CI/CD compatibility: Preserved (CI-agnostic), but the new task adds one Composer invocation per run. Measure wall-clock impact and place it in the parallel block rather than the serial block.
• Laravel-specific extensions: Unchanged — PHPStan still needs phpstan/extension-installer plus Laravel rules, Pint still needs to override PHP-CS-Fixer, Rector still needs Laravel rule sets. None of this is addressed by 11.2.0.
• Composer script side effects (open item): Confirm from the upstream task docs whether the autoload validation executes with --no-scripts. If not, Laravel's package:discover hook can fire during the check, which is undesirable in build stages lacking .env/APP_KEY.

Technical Risk

Key Questions

1. Scope of the major bump: What else changed between 10.2.8 and 11.2.0 beyond PR #124? Is the 11.x line a re-baseline (e.g., dropped older Laravel/PHP support, renamed config keys) or purely additive? Action: review compare/10.2.8...11.2.0 before any upgrade.
2. Task execution semantics: Does composer_validate_autoload run Composer with --no-scripts (and does it touch composer.lock)? If Laravel's package:discover hook fires, is that acceptable in our CI image?
3. Default-on policy: Do we accept the new task by default across all Laravel repos, or standardize an opt-out in our project template so upgrades stay non-breaking?
4. Placement: Does autoload validation belong in pre-commit (fast feedback, but adds Composer cost to every commit) or CI/pre-push only?
5. Monorepo scope: For repos with multiple composer.json roots (app + local packages), which root does the task validate? Do we need per-package task instances?
6. Static analysis strictness: Still unresolved from the prior assessment — do we baseline Laravel-specific PHPStan false positives?
7. Laravel-native tasks: Do we now invest in custom artisan-based tasks, given the package has again shipped no Laravel-specific tooling?
8. Upstream tracking: What is our cadence for reviewing andersundsehr/grumphp-config releases, given backports (PR #112) and shared-config additions (PR #124) both change behavior without requiring a config edit?

Integration Approach

Stack Fit

• Laravel Core Compatibility:
  • PHP 8.5+: Confirmed compatible; no constraint changes signalled by the notes — but re-verify against the 11.x branch requirements, which the notes do not state.
  • Composer 2: Now a first-class concern — the package validates autoload configuration, so Composer version and composer.json/composer.lock hygiene become part of the quality gate.
  • Artisan: Custom tasks still integrate via GrumPHP's execute/tasks; unchanged.
• Tooling Synergy:
  • PHPStan: Manual Laravel extension still required.
  • Pint: Still overrides PHP-CS-Fixer in grumphp.yml.
  • Rector: spatie/laravel-rector still required for Laravel rule sets.
  • Composer: New synergy — autoload validation complements composer validate and Laravel's package:discover by catching PSR-4/classmap drift earlier.
• CI/CD Systems: GitHub Actions / GitLab CI / CircleCI unchanged; add one Composer process to the pipeline budget.

Migration Path

1. Assessment Phase:
   • Review the full 10.2.8...11.2.0 changelog and confirm major-version implications (PHP/GrumPHP minimums, config keys, removed tasks).
   • Establish the autoload baseline in each target repo: composer dump-autoload -o must complete cleanly on main.
   • Audit grumphp.yml for TYPO3-specific rules to strip.
2. Pilot Installation:
   • Install in a non-production Laravel repo:

     composer require --dev pluswerk/grumphp-config:^11.2
     

   • Confirm the new task is present and note its runtime:

     vendor/bin/grumphp tasks | grep composer_validate_autoload
     time vendor/bin/grumphp run --tasks=composer_validate_autoload
     

   • Add an opt-out for repos with intentional classmap autoload:

     tasks:
       composer_validate_autoload:
         ignore_patterns: []
     

3. Incremental Adoption:
   • Phase 1: Upgrade the dependency line on one repo; validate only the new task in CI (no hook).
   • Phase 2: Add parallel: true and vendor/ exclusions; measure total run time vs. 10.2.8.
   • Phase 3: Enable pre-commit hooks selectively (autoload task pre-push; linters pre-commit).
   • Phase 4: Roll the pinned version and opt-out template across remaining Laravel repos.
4. Customization:
   • Extend phpstan.neon with Laravel rules via phpstan/extension-installer.
   • Add Laravel-specific tasks alongside the new one:

     tasks:
       composer_validate_autoload: ~
       phpunit: ~
       artisan:
         optimize: ~
         route:list: ~
     

5. Validation:
   • Compare grumphp run output between the 10.2.8 baseline branch and the 11.2.0 branch; any new failure outside composer_validate_autoload is an undocumented behavior change and should block rollout.

Compatibility

Sequencing

1. Pre-requisites:
   • Laravel project on PHP 8.5+ with a clean composer dump-autoload -o.
   • Confirmed reading of the 10.2.8...11.2.0 changelog.
2. Installation:
   • composer require --dev pluswerk/grumphp-config:^11.2 on a feature branch.
3. Configuration:
   • Remove TYPO3 rules; add Laravel tasks; set parallel: true; decide the composer_validate_autoload opt-out policy per project.
4. Testing:
   • Local: grumphp run — confirm exactly one new class of failure (autoload), nothing else.
   • CI: add with --parallel; measure delta in pipeline duration.
5. Monitoring:
   • Track autoload-validation failures in the first two weeks to distinguish genuine drift from config noise; baseline or opt out accordingly.

Operational Impact

Maintenance

• Config drift risk — High (unchanged): Each repo's overridden grumphp.yml diverges from the shared config. The 11.2.0 addition shows how the shared config grows: silently, from the consumer's perspective. Maintain a per-repo grumphp.yml diff review as part of the dependency-upgrade checklist.
• Version-line tracking — Medium: The pin must move from 10.2.8 to an 11.x line, and the 10.x assessment baseline is now historical. Record the target version and the reviewed changelog range in the repo.
• Upstream cadence — Medium: Two consecutive releases (10.2.8 backport, 11.2.0 shared-task addition) both changed behavior without requiring a consumer config edit. Establish a monthly review of andersundsehr/grumphp-config releases plus phpro/grumphp task documentation changes.
• Opt-out inventory — New, Low–Medium: Maintain a short list of repos with intentional non-standard autoload (classmap legacy code, Octane proxies, local packages) and the corresponding task disables, so future shared-config changes don't surprise them.

Support

• New failure class in the developer path: "Your commit/PR failed on composer_validate_autoload" will be unfamiliar to Laravel developers. Prepare a one-page runbook: what the task checks, the standard fix (composer dump-autoload -o, correct PSR-4 mapping, remove stale classmap entries), and how to request an opt-out.
• Composer-dependent support surface: Because the task shells out to Composer, failures can originate from Composer/DDEV/environment issues rather than code. Document the expected local and CI Composer versions.
• Escalation: Any failure other than autoload validation after the upgrade is a candidate package regression — capture grumphp run -vvv output and the composer.lock diff before filing upstream.

Scaling

• Runtime cost: Adds one Composer invocation per run. On small Laravel apps this is seconds; on large monorepos with heavy autoload (classmap over thousands of files) it can be tens of seconds. Put it in the parallel block and measure before enabling pre-commit.
• Pipeline capacity: For orgs running GrumPHP across many repos, budget the additive cost as a percentage increase in CI minutes and re-evaluate runner sizing if the parallel runner is already saturated.
• Monorepo scaling: Still unsupported as a first-class scenario, and the new task sharpens the problem — multiple composer.json roots may each need validation, which the shared config does not express. Defer broad rollout in monorepos until this is tested.

Failure Modes

Ramp-Up

• Effort — Low for the task itself, Medium for the version line: Enabling/opting out of composer_validate_autoload is a one-line config change. The real effort is validating the 10.x → 11.x major step and re-running the 10.2.8-era risk mitigations (Pint override, PHPStan extension, baseline files) against the new line.
• Audience: Any Laravel engineer can act on an autoload failure with the runbook; the upgrade itself should be owned by whoever holds the GrumPHP config in the platform/DevEx backlog.
• Time-to-value: Fast — a single pilot repo should surface autoload drift within the first week, which is exactly the class of bug this release targets. That makes 11.2.0 a reasonable forcing function for completing the previously deferred Laravel-specific configuration work, provided the major-version review comes first.