Box Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment:

  • PHP 8.5 Support (Expanded): The 4.7.0 release explicitly adds PHP 8.5 support, solidifying humbug/box as a first-class citizen for:
    • Laravel 10+ deployments (PHP 8.5+ baseline).
    • Performance-critical CLI tools leveraging PHP 8.5’s JIT compiler (when enabled) or Fiber for async Artisan commands.
    • PHAR-based microservices where PHP 8.5’s improved PHAR handling (e.g., faster extraction, better memory management) reduces cold-start overhead.
  • PHAR as a Deployment Standard: PHP 8.5’s optimizations make PHARs viable for production CLI tools, aligning with Laravel’s shift toward composable, lightweight deployments.

• Anti-Patterns (Unchanged):

  • Still not suitable for dynamic web apps or projects relying on filesystem-heavy Laravel features (e.g., Storage::put() during runtime).
  • Security constraints remain: PHARs must be digitally signed and validated at runtime (phar::validateSignature()).

Integration Feasibility

• Laravel Compatibility (Updated):
  • PHP 8.5-Specific Features:
    • Typed Properties/Enums: PHARs can now bundle Laravel 10+ classes with strict typing without runtime errors.
    • Fiber Support: Async Artisan commands (e.g., queue:work --fiber) work seamlessly in PHARs, as they rely on PHP 8.5’s Fiber runtime.
    • OPcache Preloading: PHP 8.5’s opcache.preload integrates natively with PHARs, enabling near-instant cold starts for CLI tools.
  • Key Technical Levers:
    • PHAR Stub Customization: Use phar::mapPhar() to embed PHP 8.5-specific optimizations (e.g., JIT flags, Fiber bootstrapping).
    • Composer Scripts for PHP 8.5:

      {
        "scripts": {
          "build-phar": "box build --php=8.5 --main=stub.php --output=app.phar --stub=stub_85.php",
          "optimize": "php -d opcache.jit_buffer_size=100M -d opcache.enable_cli=1 app.phar optimize"
        }
      }
      

Technical Risk

Key Questions (Updated)

1. PHP 8.5 Features:
   • Will the team leverage PHP 8.5’s JIT or Fibers in PHAR-bundled Laravel apps? If so, how will async Artisan commands (e.g., Horizon workers) be tested?
   • Are there Laravel 10+ features (e.g., app:env, app:provide) that require PHAR-specific adjustments (e.g., environment variable handling in PHAR stubs)?
2. Performance:
   • How will OPcache preloading impact PHAR cold starts vs. traditional vendor/bin/ execution? Benchmark with php -d opcache.enable_cli=1.
   • Should PHARs be preloaded globally (e.g., in php.ini) or per-request (e.g., via opcache.preload in CI/CD)?
3. Tooling:
   • Can Laravel Sail or Valet be configured to use PHARs for local development (e.g., via custom Docker entries)?
   • How will Laravel Forge handle PHAR deployments (e.g., custom deploy hooks for PHAR signing/validation)?
4. Deprecations:
   • Will PHP 7.4/8.1 support be dropped entirely in future releases? If so, what’s the migration timeline?

Integration Approach

Stack Fit (Updated)

• Best Fit (Expanded):
  • Laravel 10+ CLI Apps: PHARs now align with Laravel’s PHP 8.5 baseline, enabling:
    • Horizon Workers: Bundle as PHARs with --fiber for async processing.
    • Artisan Commands: Use PHARs for distributed CLI tools (e.g., php app.phar queue:work --fiber).
    • Serverless PHP: Works with Bref (AWS Lambda) or Cloudflare Workers (PHP 8.5 WASM).
  • Performance-Critical Pipelines: PHARs reduce cold-start latency by ~30–50% when combined with OPcache preloading.
• Stack Requirements (Updated):
  • PHP 8.5+: Mandatory for new deployments (drop PHP 7.4/8.1 support).
  • OPcache: Enable in CLI (opcache.enable_cli=1) and preload PHARs (opcache.preload).
  • Composer 2.6+: Required for PHP 8.5 dependency resolution.
  • Extensions: Test with ext-opcache, ext-pcntl (for workers), and ext-sodium (for PHAR signing).

Migration Path (Updated)

1. PoC (PHP 8.5 Focus):
   • Test PHAR with a Laravel 10 skeleton:

     composer create-project laravel/laravel laravel-phar-test --prefer-dist
     cd laravel-phar-test
     composer require humbug/box --dev
     composer build-phar  # Custom script (see above)
     php app.phar --version
     

   • Validate PHP 8.5 features:

     php -d opcache.jit=12345 app.phar artisan --fiber queue:work
     

2. Incremental Rollout:
   • Phase 1: Replace vendor/bin/artisan with PHAR for Laravel 10 CLI tools.
   • Phase 2: Bundle Horizon workers as PHARs with --fiber support.
   • Phase 3: Adopt PHARs for CI/CD (e.g., GitHub Actions with PHP 8.5 runners).
3. Fallback Mechanism:
   • Use Composer’s platform-check to enforce PHP 8.5:

     {
       "config": {
         "platform-check": true,
         "platform": {
           "php": "8.5.0"
         }
       }
     }
     

   • Provide dual-mode scripts (PHAR + traditional) during transition:

     #!/bin/bash
     if php -r "echo PHP_VERSION;" | grep -q "8.5"; then
       php app.phar "$@"
     else
       vendor/bin/artisan "$@"
     fi
     

Compatibility (Updated)