Php Scoper Laravel Package

Getting Started

Minimal Steps for Laravel Developers

1. Installation:

   composer require --dev humbug/php-scoper
   

   Or globally:

   composer global require humbug/php-scoper
   

2. First Use Case:

   • Run in your Laravel project root:

     vendor/bin/php-scoper add-prefix
     

   • This generates a build/ directory with prefixed namespaces (default: ScopingPrefix\).

3. Where to Look First:

   • Configuration: php-scoper.json (auto-generated or manually created).
   • Debugging: Use vendor/bin/php-scoper inspect path/to/file.php to test changes.
   • Laravel-Specific: Check the Laravel support section in the docs.

Implementation Patterns

Workflows for Laravel Projects

1. PHAR Integration:

   • Use php-scoper to prefix Laravel code + dependencies before building a PHAR (e.g., for CLI tools or standalone scripts).
   • Example workflow:

     composer install --no-dev --prefer-dist
     vendor/bin/php-scoper add-prefix --output-dir=build --prefix=App\\Scoped\
     composer dump-autoload --working-dir=build --classmap-authoritative
     

2. Isolated Testing:

   • Test scoped code in build/ before PHAR creation:

     php build/artisan tinker  # Test Laravel commands
     

3. CI/CD Automation:

   • Add to composer.json scripts:

     "scripts": {
       "scope": "php-scoper add-prefix --output-dir=build --prefix=App\\Scoped\\",
       "scope:test": "composer scope && composer dump-autoload --working-dir=build && php build/artisan test"
     }
     

   • Run with:

     composer scope:test
     

4. Laravel-Specific Adjustments:

   • Exclude Laravel Core: Add to php-scoper.json:

     "exclude": {
       "namespaces": ["Illuminate\\", "Laravel\\"]
     }
     

   • Expose Facades: Use expose to avoid breaking facade calls:

     "expose": {
       "namespaces": ["App\\Providers\\RouteServiceProvider"],
       "classes": ["App\\Http\\Kernel"]
     }
     

5. Patchers for Laravel:

   • Customize dynamic behavior (e.g., config_path()) via patchers:

     // config/php-scoper.php
     return [
       'patchers' => [
         'App\\Patcher\\ConfigPathPatcher',
       ],
     ];
     

Gotchas and Tips

Pitfalls

1. Autoloader Conflicts:

   • Always run composer dump-autoload in the build/ directory after scoping.
   • Use --classmap-authoritative to avoid missing classes.

2. Dynamic Symbols:

   • Laravel’s config(), app(), and route() helpers may break. Use patchers or exclude them:

     "exclude": {
       "symbols": ["config", "app", "route"]
     }
     

3. Service Providers:

   • Scoped providers may fail if they rely on global state. Test thoroughly:

     php build/artisan package:discover
     

4. Heredoc/Nowdoc:

   • Hardcoded namespaces in strings (e.g., <<<HTML\n<?php namespace Foo;) will fail. Use patchers or exclude files.

5. Composer Plugins:

   • Disable plugins during scoping if they modify files dynamically:

     composer install --no-plugins
     

Debugging Tips

1. Inspect Files:

   vendor/bin/php-scoper inspect app/Http/Controllers/UserController.php
   

2. Check Exposed Symbols:

   • Verify exposed classes/functions in build/vendor/composer/autoload_namespaces.php.

3. Laravel-Specific Debugging:

   • If facades fail, ensure they’re exposed:

     "expose": {
       "classes": ["App\\Providers\\AppServiceProvider"]
     }
     

4. PHAR Testing:

   • Extract the PHAR to test scoped code:

     $phar = new Phar('app.phar');
     $phar->extractTo('phar-test');
     

Extension Points

1. Custom Patchers:

   • Create patchers for Laravel-specific logic (e.g., config_path()):

     // src/Patcher/ConfigPathPatcher.php
     namespace App\Patcher;
     use Humbug\PhpScoper\Patcher\PatcherInterface;
     class ConfigPathPatcher implements PatcherInterface { ... }
     

   • Register in php-scoper.json:

     "patchers": ["App\\Patcher\\ConfigPathPatcher"]
     

2. Exclusion Rules:

   • Exclude Laravel’s bootstrap/ or vendor/ selectively:

     "exclude": {
       "paths": ["bootstrap/cache/*", "vendor/laravel/*"]
     }
     

3. Prefix Strategy:

   • Use dynamic prefixes (e.g., App\\Scoped\\{branch-name}\\) in CI:

     vendor/bin/php-scoper add-prefix --prefix="App\\Scoped\\${CI_COMMIT_REF_NAME}\\"
     

Laravel-Specific Quirks

1. Facades:

   • Scoped facades (e.g., App\\Scoped\\Http\\Kernel) won’t work unless exposed. Use aliases in config/app.php:

     'aliases' => [
       'App' => App\Scoped\Facades\App::class,
     ],
     

2. Service Container:

   • Bind scoped classes explicitly:

     $this->app->bind('App\\Scoped\\Http\\Kernel', function () {
         return new \App\Scoped\Http\Kernel(app());
     });
     

3. Artisan Commands:

   • Ensure commands are in exposed namespaces or use patchers to rewrite Artisan::command().

4. Testing:

   • Mock scoped classes in tests:

     $this->partialMockBuilder(\App\Scoped\SomeClass::class)
          ->disableOriginalConstructor();