Php Scoper Laravel Package

Technical Evaluation

Architecture Fit

• PHAR Isolation: php-scoper is a critical fit for Laravel-based PHAR deployments (e.g., CLI tools, standalone executables, or microservices). It resolves namespace collisions between bundled dependencies and host environments by prefixing all namespaces, ensuring compatibility with realpath() and other PHAR-specific edge cases.
• Laravel-Specific Needs: While Laravel itself isn’t PHAR-native, this tool enables:
  • Vendor Isolation: Bundling Laravel apps with dependencies (e.g., for SaaS embeds or headless APIs) without conflicts.
  • Multi-Tenant PHARs: Running multiple Laravel-based PHARs in the same process (e.g., serverless functions).
  • Legacy Compatibility: Retrofitting monolithic Laravel apps into isolated components.
• Alternatives: No native Laravel solution exists for this problem; alternatives like box-project/box require manual scoping configuration, whereas php-scoper automates it.

Integration Feasibility

• Laravel Ecosystem:
  • Composer Integration: Seamless with Laravel’s composer.json (supports --working-dir for scoped builds).
  • Artisan Hooks: Can be integrated into Laravel’s build pipeline (e.g., post-autoload-dump).
  • Service Providers: Prefixed classes can be auto-registered via AppServiceProvider with aliases.
• PHAR-Specific:
  • Box Compatibility: Works with Box via its PHP-Scoper integration.
  • Manual PHARs: Supports Phar::extractTo() for debugging scoped code.
• Limitations:
  • Dynamic Symbols: Fails on runtime-generated classes (e.g., eval(), create_function()). Mitigation: Exclude symbols via config.
  • Heredoc/Nowdoc: May break if containing unscoped namespaces. Workaround: Use patchers or exclude files.
  • Composer Plugins: May conflict if plugins rely on global namespace state. Test with --no-plugins.

Technical Risk

Key Questions for TPM

1. Use Case Clarity:
   • Is the goal PHAR deployment, multi-app isolation, or vendor lock-in?
   • Example: A Laravel-based CLI tool vs. a SaaS embed with shared hosting.
2. Dependency Strategy:
   • Will scoped PHARs use locked composer.lock or floating versions?
   • Impact: Floating versions risk runtime collisions; locked versions add build complexity.
3. CI/CD Integration:
   • Should scoping run in build pipelines (e.g., GitHub Actions) or developer machines?
   • Example: Add a php-scoper step to Laravel’s deploy.php (Deployer).
4. Debugging Workflow:
   • How will teams inspect scoped code? (e.g., php-scoper inspect vs. PHAR extraction).
5. Laravel-Specific Edge Cases:
   • Does the app use dynamic class loading (e.g., app()->make() with unresolved interfaces)?
   • Are there custom autoloaders (e.g., Psr4 with non-standard paths)?
6. PHP 8.1+ Enum Usage:
   • Does the app define enums that implement interfaces (e.g., BackedEnum/custom contracts)?
   • Impact: Earlier versions could mis-scope these; >= 0.18.20 is now the safe floor.

Integration Approach

Stack Fit

• Primary Stack:
  • PHP 8.0+: Required for full feature support (e.g., enums, attributes). Apps using enums that implement interfaces should pin php-scoper >= 0.18.20.
  • Laravel 8+: Compatible with modern Composer autoloading (PSR-4).
  • Box/PHAR: For deployment; php-scoper is agnostic to the PHAR tool.
• Secondary Stack:
  • Symfony/Bridge: Works with Symfony components (tested in Laravel).
  • WordPress: Limited support (see docs).

Migration Path

1. Assessment Phase:
   • Run php-scoper inspect on critical files to identify excluded/exposed symbols.
   • Example: Exclude wp_* functions if using WordPress plugins.
2. Pilot Build:
   • Scope a non-production Laravel app with:

     composer install --no-dev --prefer-dist
     php-scoper add-prefix --output-dir=build --prefix=LaravelScoped
     composer dump-autoload --working-dir=build
     

   • Test with ./build/vendor/bin/laravel (if CLI-based).
3. CI/CD Integration:
   • Add to Laravel’s composer.json scripts:

     "scripts": {
       "post-autoload-dump": [
         "@php-scoper",
         "php-scoper add-prefix --output-dir=build --prefix=LaravelScoped --force"
       ],
       "php-scoper": "composer dump-autoload --working-dir=build --classmap-authoritative"
     }
     

   • Use GitHub Actions for PHAR builds:

     - name: Scope and Build PHAR
       run: |
         composer install --no-dev
         php-scoper add-prefix --output-dir=build
         box compile --debug
     

4. Production Rollout:
   • Deploy scoped PHARs with versioned composer.lock.
   • Monitor for namespace resolution errors (e.g., Class 'LaravelScoped\Illuminate\Support\Facades\Log' not found).

Compatibility

Sequencing

1. Pre-Scoping:
   • Run composer install --no-dev to exclude dev dependencies.
   • Configure .php-scoper.php for:
     • Excluded symbols (e.g., ['wp_*']).
     • Exposed namespaces (e.g., ['Illuminate\Support\Facades']).
2. Scoping:
   • Execute php-scoper add-prefix with --force in CI.
3. Post-Scoping:
   • Dump autoloader in build/ directory.
   • Test scoped code with ./build/vendor/bin/laravel.
4. PHAR Build:
   • Use Box or manual Phar::create() with scoped files.

Operational Impact

Maintenance

• Configuration Drift:
  • Risk: .php-scoper.php may fall out of sync with dependency changes.
  • Mitigation: Version-control the config and add it to CI validation.
• Dependency Updates:
  • New Laravel versions may introduce unscoped symbols (e.g., new facades).
  • Mitigation: Automated testing of scoped builds post-update.
• Tooling Updates:
  • php-scoper releases may introduce breaking changes (e.g., PHP 8.1+ features).
  • Mitigation: Pin version in composer.json or use PHAR install. Minimum recommended floor is 0.18.20 for apps using enums-with-interfaces (bugfix in this release) and to benefit from the stabilised PhpStormStubs constraint.

Support

• Debugging Workflow:
  • Scoped Code: Use php-scoper inspect to debug individual files.
  • PHAR Issues: Extract with Phar::extractTo() and compare against build/ directory.
  • Namespace Errors: Check composer dump-autoload --optimize output.
• Common Issues:
  • Class Not Found: Likely missing use statement or excluded symbol.
  • Method Not Found: Dynamic calls (e.g., call_user_func()) may need patchers.
  • PHAR Permissions: Ensure Phar::canBeOverwritten() is handled.
  • Enum Interface Not Found: Upgrade to >= 0.18.20; pre-fix, interfaces implemented by enums were not correctly prefixed.
• Support Matrix:

  Issue Type	Resolution Path
  Namespace mismatch	Re-run php-scoper add-prefix --force and verify .php-scoper.php exclusions.