Grumphp Config Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Backward-compatible backport (PR #112): The release notes indicate a backport of changes from a newer branch to the 10.x line, suggesting stability and minimal disruption to existing Laravel integrations. This aligns with Laravel’s preference for incremental updates.
  • TYPO3-agnostic core preserved: No evidence of TYPO3-specific changes in the release notes, meaning Laravel-specific customizations (e.g., stripping TYPO3 rules) remain viable.
  • PHP 8.5+ and Laravel 10+ compatibility: No version conflicts introduced; the backport likely maintains compatibility with the existing Laravel stack.
  • Minimal risk of breaking changes: Backports typically focus on bug fixes or minor improvements, reducing the likelihood of disrupting Laravel’s workflows (e.g., phpunit, pint, or artisan tasks).

• Gaps:

  • No Laravel-specific enhancements: The release notes do not mention new features or Laravel-specific improvements (e.g., added tasks for route:list or migrate:status). The original gaps (e.g., missing Laravel-native tooling overlap) persist.
  • Undocumented changes: Without a detailed changelog or PR description for #112, it’s unclear if the backport introduces subtle behavioral shifts (e.g., stricter PHPStan rules or modified task execution).
  • No mention of performance or CI/CD optimizations: The release does not address the "performance overhead" risk identified earlier (e.g., parallel execution or vendor/ exclusions).

Integration Feasibility

• Composer integration: Unchanged; remains zero-friction (composer require --dev).
• CI/CD compatibility: No new constraints; GrumPHP’s CI-agnostic nature is preserved.
• Laravel-specific extensions:
  • PHPStan/Rector/Pint: No updates to Laravel-specific tooling overlap. Custom overrides (e.g., replacing PHP-CS-Fixer with Pint) are still required.
  • Artisan tasks: No new built-in support for Laravel’s schedule:run or migration validation.

Technical Risk

Key Questions

1. Undocumented backport impact:
   • Does PR #112 introduce stricter rules (e.g., PHPStan level changes) or new task behaviors that could affect Laravel’s workflows?
   • Action: Run the package in a Laravel test repo and compare outputs with 10.2.7.
2. Laravel vs. TYPO3 balance:
   • Should we proactively remove TYPO3 rules in grumphp.yml to avoid future conflicts, even if the backport doesn’t introduce new ones?
3. Static analysis strictness:
   • Should we baseline Laravel-specific false positives (e.g., dynamic properties in Eloquent) using phpstan-baseline.neon?
4. CI/CD gating:
   • Should GrumPHP fail CI pipelines for Laravel-specific violations (e.g., route misconfigurations) or only warn?
5. Custom tasks:
   • Should we add Laravel-specific tasks (e.g., artisan optimize, route:list) via GrumPHP’s tasks section, even if not included in this release?
6. Local dev experience:
   • Should GrumPHP run in pre-commit hooks for Laravel teams, or is CI-only sufficient to avoid local performance issues?
7. Maintenance:
   • How will we track future backports (e.g., PR #112) to ensure they don’t introduce Laravel-breaking changes?

Integration Approach

Stack Fit

• Laravel Core Compatibility:
  • PHP 8.5+: Confirmed compatible; no version conflicts in release notes.
  • Composer: Dev-only dependency; no runtime impact.
  • Artisan: Custom tasks can still be integrated via GrumPHP’s execute command.
• Tooling Synergy:
  • PHPStan: Requires manual extension for Laravel rules (phpstan/extension-installer).
  • Pint: Override PHP-CS-Fixer in grumphp.yml to avoid duplication.
  • Rector: Use spatie/laravel-rector for Laravel-specific rules.
• CI/CD Systems:
  • GitHub Actions/GitLab CI/CircleCI: Unchanged; GrumPHP remains CI-agnostic.

Migration Path

1. Assessment Phase:
   • Compare 10.2.7 vs. 10.2.8: Test in a Laravel staging repo to detect undocumented changes (e.g., stricter rules).
   • Audit existing grumphp.yml for TYPO3 rules to remove.
2. Pilot Installation:
   • Install in a non-production Laravel repo:

     composer require --dev pluswerk/grumphp-config@10.2.8
     

   • Override grumphp.yml to:
     • Remove TYPO3-specific rules.
     • Add Laravel tasks (e.g., phpunit, artisan optimize).
3. Incremental Adoption:
   • Phase 1: Add GrumPHP to CI (e.g., GitHub Actions) with --parallel for performance.
   • Phase 2: Enable pre-commit hooks (optional) after local performance testing.
   • Phase 3: Replace existing tools (e.g., swap PHP-CS-Fixer for Pint).
4. Customization:
   • Extend phpstan.neon with Laravel rules:

     includes:
       - vendor/phpstan/extension-installer/src/PhpStan/ExtensionInstaller/Neon/LaravelNeonLoader.php
     

   • Add Laravel-specific tasks:

     tasks:
       phpunit: ~
       artisan:
         config:cache
         route:list
     

Compatibility

Sequencing

1. Pre-requisites:
   • Laravel project with PHP 8.5+.
   • Existing composer.json (dev dependencies will be added).
2. Installation:
   • Run composer require --dev pluswerk/grumphp-config@10.2.8.
3. Configuration:
   • Override grumphp.yml to:
     • Remove TYPO3-specific rules.
     • Add Laravel tasks (e.g., phpunit, artisan optimize).
     • Configure parallel execution (parallel: true).
4. Testing:
   • Local: Run grumphp run to catch undocumented strictness changes.
   • CI: Add to pipeline with --parallel and exclude vendor/.
5. Monitoring:
   • Track false positives in phpstan.neon and baseline them.

Operational Impact

Maintenance

• Config Drift Risk:
  • High: Custom `grum