PHPackages humbug/php-scoper - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [CLI & Console](/categories/cli) 4. / 5. humbug/php-scoper ActiveLibrary[CLI & Console](/categories/cli) humbug/php-scoper ================= Prefixes all PHP namespaces in a file or directory. 0.18.19(2mo ago)7963.0M↓19.2%75[22 issues](https://github.com/humbug/php-scoper/issues)[6 PRs](https://github.com/humbug/php-scoper/pulls)20MITPHPPHP ^8.2CI passing Since Jun 17Pushed 1mo ago10 watchersCompare [ Source](https://github.com/humbug/php-scoper)[ Packagist](https://packagist.org/packages/humbug/php-scoper)[ RSS](/packages/humbug-php-scoper/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (34)Versions (80)Used By (20) PHP-Scoper ========== [](#php-scoper) [![Package version](https://camo.githubusercontent.com/80893499ff0bcf99a07498b0d723dbb59987c7a619d3825f420434336f057ff4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f68756d6275672f7068702d73636f7065722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/humbug/php-scoper)[![Build Status](https://github.com/humbug/php-scoper/workflows/Build/badge.svg)](https://github.com/humbug/php-scoper/actions)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/0e06b8603b8cbba7a7a76fc5de040236fb682fd54ee9e185b17afd76fd731de9/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f68756d6275672f7068702d73636f7065722e7376673f6272616e63683d6d61696e267374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/humbug/php-scoper/?branch=main)[![Code Coverage](https://camo.githubusercontent.com/c93086fb103084d6c7f8dec9e06d5209a0aea1974dbb8bd7dc0fa768d1390b55/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f68756d6275672f7068702d73636f7065722f6261646765732f636f7665726167652e706e673f623d6d61696e)](https://scrutinizer-ci.com/g/humbug/php-scoper/?branch=main)[![Slack](https://camo.githubusercontent.com/2f6358cd8cd3927356f9a75fc3b8fd8e83ce5bbad7f9efa4879e54f29780ebfb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f736c61636b2d25323368756d6275672d7265642e7376673f7374796c653d666c61742d737175617265)](https://symfony.com/slack-invite)[![License](https://camo.githubusercontent.com/10e85a5778fe7601504a17ecd18dfa7097f473186b0f947bc10db2d3e4f530e4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d7265642e7376673f7374796c653d666c61742d737175617265)](LICENSE) PHP-Scoper is a tool which essentially moves any body of code, including all dependencies such as vendor directories, to a new and distinct namespace. Goal ---- [](#goal) PHP-Scoper's goal is to make sure that all code for a project lies in a distinct PHP namespace. This is necessary, for example, when building PHARs that: - Bundle their own vendor dependencies; and - Load/execute code from arbitrary PHP projects with similar dependencies When a package (of possibly different versions) exists, and is found in both a PHAR and the executed code, the one from the PHAR will be used. This means these PHARs run the risk of raising conflicts between their bundled vendors and the vendors of the project they are interacting with, leading to issues that are potentially very difficult to debug due to dissimilar or unsupported package versions. Table of Contents ----------------- [](#table-of-contents) - [Installation](docs/installation.md#installation) - [Phive](docs/installation.md#phive) - [Composer](docs/installation.md#composer) - [Docker](docs/installation.md#docker) - [GitHub](docs/installation.md#github) - [Usage](#usage) - [Configuration](docs/configuration.md#configuration) - [Prefix](docs/configuration.md#prefix) - [PHP Version](docs/configuration.md#php-version) - [Output directory](docs/configuration.md#output-directory) - [Finders and paths](docs/configuration.md#finders-and-paths) - [Patchers](docs/configuration.md#patchers) - [Excluded files](docs/configuration.md#excluded-files) - [Excluded Symbols](docs/configuration.md#excluded-symbols) - [Excluding namespaces](docs/configuration.md#excluding-namespaces) - [Exposed Symbols](docs/configuration.md#exposed-symbols) - [Exposing namespaces](docs/configuration.md#exposing-namespaces) - [Exposing classes](docs/configuration.md#exposing-classes) - [Exposing functions](docs/configuration.md#exposing-functions) - [Exposing constants](docs/configuration.md#exposing-constants) - [Building a scoped PHAR](#building-a-scoped-phar) - [With Box](#with-box) - [Without Box](#without-box) - [Step 1: Configure build location and prep vendors](#step-1-configure-build-location-and-prep-vendors) - [Step 2: Run PHP-Scoper](#step-2-run-php-scoper) - [Recommendations](#recommendations) - [Debugging](#debugging) - [Further Reading](docs/further-reading.md#further-reading) - [How to deal with unknown third-party symbols](docs/further-reading.md#how-to-deal-with-unknown-third-party-symbols) - [Autoload aliases](docs/further-reading.md#autoload-aliases) - [Class aliases](docs/further-reading.md#class-aliases) - [Function aliases](docs/further-reading.md#function-aliases) - [Laravel support](docs/further-reading.md#laravel-support) - [Symfony support](docs/further-reading.md#symfony-support) - [Wordpress support](docs/further-reading.md#wordpress-support) - [Limitations](docs/limitations.md#limitations) - [Dynamic symbols](docs/limitations.md#dynamic-symbols) - [Date symbols](docs/limitations.md#date-symbols) - [Heredoc values](docs/limitations.md#heredoc-values) - [Callables](docs/limitations.md#callables) - [String values](docs/limitations.md#string-values) - [Native functions and constants shadowing](docs/limitations.md#native-functions-and-constants-shadowing) - [Composer Autoloader](docs/limitations.md#composer-autoloader) - [Composer Plugins](docs/limitations.md#composer-plugins) - [PSR-0 Partial support](docs/limitations.md#psr-0-partial-support) - [Files autoloading](docs/limitations.md#files-autoloading) - [Exposing/Excluding traits](docs/limitations.md#exposingexcluding-traits) - [Exposing/Excluding enums](docs/limitations.md#exposingexcluding-enums) - [Contributing](#contributing) - [Credits](#credits) Usage ----- [](#usage) ``` php-scoper add-prefix ``` This will prefix all relevant namespaces in code found in the current working directory. The prefixed files will be accessible in a `build` folder. You can then use the prefixed code to build your PHAR. **Warning**: After prefixing the files, if you are relying on Composer for the auto-loading, dumping the autoloader again is required. For a more concrete example, you can take a look at PHP-Scoper's build step in [Makefile](Makefile), especially if you are using Composer as there are steps both before and after running PHP-Scoper to consider. Refer to TBD for an in-depth look at scoping and building a PHAR taken from PHP-Scoper's makefile. Building a Scoped PHAR ---------------------- [](#building-a-scoped-phar) ### With Box [](#with-box) If you are using [Box](https://github.com/box-project/box) to build your PHAR, you can use the existing [PHP-Scoper integration](https://github.com/box-project/box/blob/main/doc/code-isolation.md#phar-code-isolation). Box will take care of most of the things for you so you should only have to adjust the PHP-Scoper configuration to your needs. ### Without Box [](#without-box) #### Step 1: Configure build location and prep vendors [](#step-1-configure-build-location-and-prep-vendors) Assuming you do not need any development dependencies, run: ``` composer install --no-dev --prefer-dist ``` This will allow you to save time in the scoping process by not processing unnecessary files. #### Step 2: Run PHP-Scoper [](#step-2-run-php-scoper) PHP-Scoper copies code to a new location during prefixing, leaving your original code untouched. The default location is `./build`. You can change the default location using the `--output-dir` option. By default, it also generates a random prefix string. You can set a specific prefix string using the `--prefix` option. If automating builds, you can set the `--force` option to overwrite any code existing in the output directory without being asked to confirm. Onto the basic command assuming default options from your project's root directory: ``` bin/php-scoper add-prefix ``` As there are no path arguments, the current working directory will be scoped to `./build` in its entirety. Of course, actual prefixing is limited to PHP files, or PHP scripts. Other files are copied unchanged, though we also need to scope certain Composer related files. Speaking of scoping Composer related files... The next step is to dump the Composer autoloader if we depend on it, so everything works as expected: ``` composer dump-autoload --working-dir build --classmap-authoritative ``` Recommendations --------------- [](#recommendations) There is 3 things to manage when dealing with isolated PHARs: - The PHAR format: there is some incompatibilities such as `realpath()` which will no longer work for the files within the PHAR since the paths are not virtual. - Isolating the code: due to the dynamic nature of PHP, isolating your dependencies will never be a trivial task and as a result you should have some end-to-end test to ensure your isolated code is working properly. You will also likely need to configure the excluded and exposed symbols or [patchers](docs/configuration.md#patchers). - The dependencies: which dependencies are you shipping? Fine controlled ones managed with a `composer.lock` or you always ship your application with up-to-date dependencies? The latter, although more ideal, will by design result in more brittleness as any new release from a dependency may break something (although the changes may be SemVer compliant, we are dealing with PHARs and isolated code) As a result, you *should* have end-to-end tests for your (at the minimum) your released PHAR. Since dealing with the 3 issues mentioned above at once can be tedious, it is highly recommended having several tests for each step. For example, you can have a test for both your non-isolated PHAR and your isolated PHAR, this way you will know which step is causing an issue. If the isolated PHAR is not working, you can try to test the isolated code directly outside the PHAR to make sure the scoping process is not the issue. To check if the isolated code is working correctly, you have a number of solutions: - When using PHP-Scoper directly, by default PHP-Scoper dump the files in a `build` directory. Do not forget that [you need to dump the Composer autoloader for the isolated code to work!](#step-2-run-php-scoper). - When using [Box](https://github.com/box-project/box), you can use its `--debug` option from the `compile`command in order to have the code shipped in the PHAR dumped in the `.box`directory. - When using a PHAR (created by [Box](https://github.com/box-project/box) or any other PHAR building tool), you can use the [`Phar::extractTo()`](https://secure.php.net/manual/en/phar.extractto.php) method. Debugging --------- [](#debugging) Having a good breakdown like described in [Recommendations](#recommendations) will help to know where the issue is coming from. However, if you have a doubt or you are fiddling with patchers and want to check the result for a specific file without doing the whole scoping process, you can always check the result for that single individual file: ``` php-scoper inspect path/to/my-file.php ``` Contributing ------------ [](#contributing) [Contribution Guide](CONTRIBUTING.md) Credits ------- [](#credits) Project originally created by: [Bernhard Schussek](https://webmozart.io/) ([@webmozart](https://twitter.com/webmozart)) which has now been moved under the [Humbug umbrella](https://github.com/humbug). ### Health Score 72 — ExcellentBetter than 100% of packages Maintenance87 Actively maintained with recent releases Popularity66 Solid adoption and visibility Community43 Growing community involvement Maturity81 Battle-tested with a long release history Bus Factor1 Top contributor holds 79.4% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~43 days Recently: every ~136 days Total 74 Last Release 77d ago PHP version history (8 changes)0.1.0PHP ^7.0 0.2.0PHP ^7.1 0.12.0PHP ^7.2 0.13.10PHP ^7.3 0.14.0PHP ^7.3 || ^8.0 0.16.0PHP ^7.4 || ^8.0 0.17.6PHP ^8.1 0.18.8PHP ^8.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/6fbf458a1f05f8ac5a3c8f6c5426abe81084b7077b24955747b09c35f6c983be?d=identicon)[theofidry](/maintainers/theofidry) --- Top Contributors [![theofidry](https://avatars.githubusercontent.com/u/5175937?v=4)](https://github.com/theofidry "theofidry (713 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (71 commits)")[![matthieuauger](https://avatars.githubusercontent.com/u/1172099?v=4)](https://github.com/matthieuauger "matthieuauger (21 commits)")[![padraic](https://avatars.githubusercontent.com/u/19780?v=4)](https://github.com/padraic "padraic (20 commits)")[![webmozart](https://avatars.githubusercontent.com/u/176399?v=4)](https://github.com/webmozart "webmozart (16 commits)")[![villfa](https://avatars.githubusercontent.com/u/2891564?v=4)](https://github.com/villfa "villfa (10 commits)")[![marekdedic](https://avatars.githubusercontent.com/u/3134692?v=4)](https://github.com/marekdedic "marekdedic (6 commits)")[![szepeviktor](https://avatars.githubusercontent.com/u/952007?v=4)](https://github.com/szepeviktor "szepeviktor (5 commits)")[![BackEndTea](https://avatars.githubusercontent.com/u/14289961?v=4)](https://github.com/BackEndTea "BackEndTea (4 commits)")[![mattstauffer](https://avatars.githubusercontent.com/u/151829?v=4)](https://github.com/mattstauffer "mattstauffer (3 commits)")[![VincentLanglet](https://avatars.githubusercontent.com/u/9052536?v=4)](https://github.com/VincentLanglet "VincentLanglet (2 commits)")[![alexander-schranz](https://avatars.githubusercontent.com/u/1698337?v=4)](https://github.com/alexander-schranz "alexander-schranz (2 commits)")[![peter279k](https://avatars.githubusercontent.com/u/9021747?v=4)](https://github.com/peter279k "peter279k (2 commits)")[![sebastianbergmann](https://avatars.githubusercontent.com/u/25218?v=4)](https://github.com/sebastianbergmann "sebastianbergmann (2 commits)")[![leoloso](https://avatars.githubusercontent.com/u/1981996?v=4)](https://github.com/leoloso "leoloso (2 commits)")[![moorscode](https://avatars.githubusercontent.com/u/2005352?v=4)](https://github.com/moorscode "moorscode (2 commits)")[![TomasVotruba](https://avatars.githubusercontent.com/u/924196?v=4)](https://github.com/TomasVotruba "TomasVotruba (2 commits)")[![Nyholm](https://avatars.githubusercontent.com/u/1275206?v=4)](https://github.com/Nyholm "Nyholm (2 commits)")[![Huluti](https://avatars.githubusercontent.com/u/5782198?v=4)](https://github.com/Huluti "Huluti (2 commits)")[![poisa](https://avatars.githubusercontent.com/u/348248?v=4)](https://github.com/poisa "poisa (1 commits)") --- Tags archivecommand-linepharphar-prefixerphpphp-console ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/humbug-php-scoper/health.svg) ``` [![Health](https://phpackages.com/badges/humbug-php-scoper/health.svg)](https://phpackages.com/packages/humbug-php-scoper) ``` ### Alternatives [humbug/box Fast, zero config application bundler with PHARs. 1.3k801.5k69](/packages/humbug-box)[psy/psysh An interactive shell for modern PHP. 9.8k545.6M719](/packages/psy-psysh)[sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.4k5.6M651](/packages/sylius-sylius)[infection/infection Infection is a Mutation Testing framework for PHP. The mutation adequacy score can be used to measure the effectiveness of a test set in terms of its ability to detect faults. 2.2k26.2M1.8k](/packages/infection-infection)[drush/drush Drush is a command line shell and scripting interface for Drupal, a veritable Swiss Army knife designed to make life easier for those of us who spend some of our working hours hacking away at the command prompt. 2.4k57.4M685](/packages/drush-drush)[drupal/core-recommended Locked core dependencies; require this project INSTEAD OF drupal/core. 6939.5M343](/packages/drupal-core-recommended) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)