Weave Code
Php Scoper Laravel Package
humbug/php-scoper
PHP-Scoper moves any body of code, including all vendor dependencies, into a new distinct namespace. This prevents conflicts when building PHARs that bundle their own dependencies and interact with other PHP projects.
🔨 Prefixes all PHP namespaces in a file/directory to isolate the code bundled in PHARs.
Frequently asked questions about Php Scoper
- What is humbug/php-scoper used for in Laravel projects?
- It prefixes all PHP namespaces in a codebase, including vendor dependencies, into a distinct namespace. In Laravel projects it is mainly used when building PHARs or standalone executables that bundle their own dependencies, so they do not collide with the host application or other PHARs. It also helps isolate monolithic Laravel components or multi-tenant PHAR deployments running in the same process. It does not change Laravel itself; it scopes the code you choose to bundle.
- How do I install php-scoper in a Laravel application?
- Install it as a development dependency with Composer, for example composer require --dev humbug/php-scoper, then run it via vendor/bin/php-scoper. The package also documents Phive, Docker, and GitHub installation options if you prefer not to add it to the app's Composer dependencies. For CI builds, keep it in the build toolchain rather than production dependencies. After installation, create a scoper configuration file and point it at the directories you want to prefix.
- Does php-scoper support Laravel 8, 9, 10, and 11?
- php-scoper is framework-agnostic and works with Laravel 8+ projects that use modern Composer PSR-4 autoloading. It requires PHP 8.0+ for full feature support such as enums and attributes. Laravel itself is not PHAR-native, so the tool scopes the Laravel code and vendor dependencies you explicitly include in the build. If your app uses enums that implement interfaces, pin php-scoper to 0.18.20 or newer.
- How do I configure php-scoper to prefix namespaces for a Laravel PHAR build?
- Create a php-scoper configuration file that sets the prefix, PHP version, output directory, finders, and any excluded symbols or files. Point the finder at your Laravel app and vendor directories that should be bundled, and exclude symbols that must remain global, such as runtime-generated classes or host-provided functions. Use patchers for edge cases like heredoc or nowdoc blocks that contain unscoped namespaces. Then run php-scoper add-prefix and build the PHAR from the scoped output directory.
- Can php-scoper prevent vendor dependency conflicts when bundling a Laravel CLI tool as a PHAR?
- Yes, that is its primary purpose. When a PHAR bundles its own vendor dependencies, PHP may load the PHAR's copy of a package instead of the host project's version, causing hard-to-debug conflicts. PHP-Scoper moves all bundled code into a distinct namespace so the PHAR and the host application can use different package versions safely. You still need to validate the scoped build and ensure dynamic class loading is excluded or patched.
- What PHP version does php-scoper require for Laravel apps using enums?
- php-scoper requires PHP 8.0+ for full feature support, and Laravel apps using PHP 8.1+ enums should pin php-scoper to 0.18.20 or newer. Earlier versions could mis-scope enums that implement interfaces, which is a low-risk but real edge case. The safe floor is therefore 0.18.20 or newer when your codebase defines backed enums or enums implementing custom contracts. Always run a scoped build and test enum-heavy code paths.
- How do I integrate php-scoper with Box for building Laravel PHARs?
- Box has PHP-Scoper integration, so you can configure Box to run php-scoper during the PHAR build instead of invoking both tools manually. This lets Box handle the PHAR packaging while php-scoper prefixes the Laravel app and vendor namespaces. You still need a scoper configuration for prefix, finders, exclusions, and patchers. Test the resulting PHAR against a host Laravel project to confirm autoloading and realpath behavior.
- What are common php-scoper issues with Laravel and how do I fix them?
- Common issues include broken autoloading, namespace collisions, PHAR path problems, and failures on dynamic symbols such as eval or create_function. Fix autoloading by running composer dump-autoload --classmap-authoritative in the scoped build directory, and validate with composer validate after scoping. Exclude runtime-generated symbols in the scoper config, patch realpath calls or use PHAR-relative paths, and test with --no-plugins if Composer plugins rely on global namespace state. Heredoc or nowdoc blocks with unscoped namespaces may need patchers or file exclusions.
- How do I test a Laravel app after scoping with php-scoper?
- Run php-scoper inspect on critical files to see which symbols are exposed or excluded before building the PHAR. After scoping, run composer dump-autoload --classmap-authoritative in the build directory and execute the PHAR against a host Laravel app to verify autoloading, service providers, and realpath behavior. Test Laravel-specific managers such as cache and queue, and exercise any dynamic class loading paths. Use PHAR extraction or php-scoper inspect for debugging scoped code.
- Are there alternatives to php-scoper for Laravel PHAR namespace isolation?
- There is no native Laravel solution for this problem. Box-project/box can build PHARs and has PHP-Scoper integration, but it requires manual scoping configuration whereas php-scoper automates namespace prefixing. You can also build custom tooling or use other namespace-prefixing scripts, but php-scoper is the established Composer-installable option. Evaluate alternatives against your need for PHAR isolation, multi-tenant PHARs, or vendor isolation in Laravel builds.
Weaver
How can I help you explore Laravel packages today?