Php Backport Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: The package addresses a specific, niche problem—backporting PHP 7.2+ features to PHP 7.0 for legacy systems (Alpha/Beta/Gamma dependency chain). This is a validated technical debt mitigation strategy for monolithic or constrained environments where migration is infeasible.
• Laravel Compatibility: Laravel itself is PHP 7.2+ dependent, but this package could be leveraged for:
  • Legacy Laravel plugins (e.g., packages targeting PHP 7.0).
  • Custom backporting of Laravel core features (e.g., if a legacy app requires Laravel 5.8 but needs PHP 8.0+ syntax).
• Limitation: Not a general-purpose tool—requires manual configuration per project and assumes PHP 7.0+ compatibility in the backported output.

Integration Feasibility

• Core Dependency: Relies on nikic/php-parser (mature, battle-tested) for AST manipulation.
• Laravel-Specific Risks:
  • Laravel’s framework-specific syntax (e.g., collect(), Str::, Facades) may not backport cleanly without custom rules.
  • Service Provider/Container changes (e.g., PHP 8.0 named arguments) could break legacy code.
• Tooling Overhead: Requires:
  • Docker setup (for testing; may conflict with Laravel’s Valet/Sail).
  • Custom backport.php per project (not plug-and-play).

Technical Risk

Key Questions for a TPM

1. Scope:
   • Is this for Laravel packages or custom Laravel apps? (Packages may need stricter validation.)
   • Which specific PHP 7.2+ features are critical to backport? (e.g., array_key_first(), match(), attributes?)
2. Process:
   • How will _bp branches be synced with master? (Automated? Manual?)
   • Who owns conflict resolution and testing of backported code?
3. Tooling:
   • Can nikic/php-parser be extended to handle Laravel’s syntax? (e.g., Blade templates, Eloquent methods).
   • Should we fork the package to add Laravel support, or contribute upstream?
4. Long-Term Viability:
   • What’s the exit strategy if Alpha eventually upgrades to PHP 7.2+?
   • How will this scale if multiple Laravel projects need backporting?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • Pros: Works for PHP-based Laravel packages or legacy Laravel apps constrained to PHP 7.0.
  • Cons: Not suitable for:
    • Backporting Laravel core (e.g., making Laravel 9 work on PHP 7.0).
    • Non-PHP components (e.g., JavaScript, Blade views—though Blade could be preprocessed).
• Alternatives Considered:
  • Polyfills (e.g., php-compat): More limited but less invasive.
  • Custom Transpilers: Overkill for this use case.
  • Dockerized PHP 7.0: Avoids backporting but doesn’t solve dependency issues.

Migration Path

1. Assessment Phase:
   • Audit Laravel project/package for PHP 7.2+ dependencies (e.g., array_merge with spread operator, nullsafe).
   • Identify critical features to backport (prioritize based on Alpha’s usage).
2. Setup:
   • Add dansan/php-backport to composer.json (--dev).
   • Configure backport.php with:

     $client
         ->setDirsToPort([__DIR__.'/app', __DIR__.'/src'])
         ->addComposerJsonReplacement('/"laravel\/framework": "[^"]+"/', '"laravel/framework": "v7.0.0"')
         ->execute();
     

3. Workflow Integration:
   • Git Hooks: Auto-create _bp branches on master merges.
   • CI Pipeline:
     • Run backport script on _bp branch pushes.
     • Test against PHP 7.0 before allowing merges to Alpha.
   • Documentation: Add a BACKPORTING.md with:
     • Step-by-step for contributors.
     • List of known limitations (e.g., "Type hints in Blade are not backported").

Compatibility

• PHP 7.0 Target: Ensure backported code avoids:
  • Removed functions (e.g., create_function, call_user_method).
  • Deprecated features (e.g., mysql_* functions).
• Laravel-Specific:
  • Service Container: Backport app()->bind() syntax if using PHP 7.2+ features.
  • Collections: Replace collect()->when() with if blocks.
  • Facades: Ensure static calls work (PHP 7.0 lacks ::class constants in some cases).
• Testing:
  • Use PHPUnit with php:7.0 Docker image.
  • Add a phpstan-baseline for backported code.

Sequencing

1. Phase 1: Pilot with a non-critical Laravel package.
2. Phase 2: Integrate into Alpha’s dependency chain (Beta → Gamma).
3. Phase 3: Automate _bp branch management (e.g., GitHub Actions).
4. Phase 4: Deprecate _bp branches as Alpha upgrades.

Operational Impact

Maintenance

• Ongoing Effort:
  • Backport Script Updates: Modify backport.php as new PHP 7.2+ features are added to master.
  • Dependency Hell: _bp branches may diverge from master; require manual syncs.
• Tooling Maintenance:
  • Monitor nikic/php-parser for breaking changes.
  • Update Docker images if PHP 7.0 support is dropped upstream.

Support

• Debugging Complexity:

  • Issues may stem from backported code vs. original master. Requires:
    • Clear branch naming (master_bp vs. master).
    • Annotated commits (e.g., "Backported array_key_first() to array_search()").
  • Support Matrix:

    Environment	PHP Version	Backported?	Notes
    Alpha (prod)	7.0	Yes	Uses _bp branches.
    Beta (dev)	7.2+	No	master branch.
    Gamma (CI)	7.0/7.2+	Conditional	Test both branches.

• Community Risks:

  • Contributors may unintentionally merge to master instead of _bp.
  • Upstream Laravel packages may drop PHP 7.0 support, breaking _bp branches.

Scaling

• Multi-Project Scaling:
  • Centralized Backport Rules: Share backport.php templates across projects.
  • Automated Branch Management: Use GitHub API to auto-create _bp branches.
• Performance:
  • Backporting large codebases (e.g., Laravel core) may be slow. Optimize with:
    • Incremental parsing (only changed files).
    • Caching AST results (if using a custom visitor).
• Team Scaling:
  • Requires dedicated "backport engineers" to manage _bp branches.
  • Onboarding Cost: New devs must understand the dual-branch workflow.

Failure Modes