PHP-Scoper

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

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

• Installation
  • Phive
  • PHAR
  • Composer
• Usage
• Configuration
  • Prefix
  • Finders and paths
  • Patchers
  • Whitelisted files
  • Excluded Symbols
  • Whitelist
    • Constants & functions from the global namespace
    • Symbols
      • Caveats
      • Implementation insights
        • Class whitelisting
        • Constants whitelisting
        • Functions whitelisting
    • Namespaces whitelisting
• Building a scoped PHAR
  • With Box
  • Without Box
    • Step 1: Configure build location and prep vendors
    • Step 2: Run PHP-Scoper
• Recommendations
• Limitations
  • Dynamic symbols
  • Date symbols
  • Heredoc values
  • Callables
  • String values
  • Native functions and constants shadowing
  • Grouped constants whitelisting
  • Composer
  • Composer Plugins
  • PSR-0 Partial support
  • WordPress support
• Contributing
• Credits

Installation

Phive

You can install PHP-Scoper with Phive

$ phive install humbug/php-scoper --force-accept-unsigned

To upgrade php-scoper use the following command:

$ phive update humbug/php-scoper --force-accept-unsigned

PHAR

The preferred method of installation is to use the PHP-Scoper PHAR, which can be downloaded from the most recent Github Release.

Composer

You can install PHP-Scoper with Composer:

composer global require humbug/php-scoper

If you cannot install it because of a dependency conflict or you prefer to install it for your project, we recommend you to take a look at bamarni/composer-bin-plugin. Example:

composer require --dev bamarni/composer-bin-plugin
composer bin php-scoper config minimum-stability dev
composer bin php-scoper config prefer-stable true 
composer bin php-scoper require --dev humbug/php-scoper

Keep in mind however that this library is not designed to be extended.

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 autoloading, dumping the autoloader again is required.

For a more concrete example, you can take a look at PHP-Scoper's build step in 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.

Configuration

If you need more granular configuration, you can create a scoper.inc.php by running the command php-scoper init. A different file/location can be passed with a --config option.

<?php declare(strict_types=1);

// scoper.inc.php

use Isolated\Symfony\Component\Finder\Finder;

return [
    'prefix' => null,                       // string|null
    'finders' => [],                        // Finder[]
    'patchers' => [],                       // callable[]
    'files-whitelist' => [],                // string[]
    'whitelist' => [],                      // string[]
    'expose-global-constants' => true,   // bool
    'expose-global-classes' => true,     // bool
    'expose-global-functions' => true,   // bool
    'exclude-constants' => [],             // string[]
    'exclude-classes' => [],               // string[]
    'exclude-functions' => [],             // string[]
];

Prefix

The prefix to be used to isolate the code. If null or '' (empty string) is given, then a random prefix will be automatically generated.

Finders and paths

By default when running php-scoper add-prefix, it will prefix all relevant code found in the current working directory. You can however define which files should be scoped by using Finders in the configuration:

<?php declare(strict_types=1);

// scoper.inc.php

use Isolated\Symfony\Component\Finder\Finder;

return [
    'finders' => [
        Finder::create()->files()->in('src'),
        Finder::create()
            ->files()
            ->ignoreVCS(true)
            ->notName('/LICENSE|.*\\.md|.*\\.dist|Makefile|composer\\.json|composer\\.lock/')
            ->exclude([
                'doc',
                'test',
                'test_old',
                'tests',
                'Tests',
                'vendor-bin',
            ])
            ->in('vendor'),
        Finder::create()->append([
            'bin/php-scoper',
            'composer.json',
        ])
    ],
];

Besides the finder, you can also add any path via the command:

php-scoper add-prefix file1.php bin/file2.php

Paths added manually are appended to the paths found by the finders.

Patchers

When scoping PHP files, there will be scenarios where some of the code being scoped indirectly references the original namespace. These will include, for example, strings or string manipulations. PHP-Scoper has limited support for prefixing such strings, so you may need to define patchers, one or more callables in a scoper.inc.php configuration file which can be used to replace some of the code being scoped.

Here's a simple example:

• Class names in strings.

You can imagine instantiating a class from a variable which is based on a known namespace, but also on a variable classname which is selected at runtime. Perhaps code similar to:

$type = 'Foo'; // determined at runtime
$class = 'Humbug\\Format\\Type\\' . $type;

If we scoped the Humbug namespace to PhpScoperABC\Humbug, then the above snippet would fail as PHP-Scoper cannot interpret the above as being a namespaced class. To complete the scoping successfully, a) the problem must be located and b) the offending line replaced.

The patched code which would resolve this issue might be:

$type = 'Foo'; // determined at runtime
$scopedPrefix = array_shift(explode('\\', __NAMESPACE__));
$class = $scopedPrefix . '\\Humbug\\Format\\Type\\' . $type;

This and similar issues may arise after scoping, and can be debugged by running the scoped code and checking for issues. For this purpose, having a couple of end to end tests to validate post-scoped code or PHARs is recommended.

Applying such a change can be achieved by defining a suitable patcher in scoper.inc.php:

<?php declare(strict_types=1);

// scoper.inc.php

return [
    'patchers' => [
        function (string $filePath, string $prefix, string $content): string {
            //
            // PHP-Parser patch conditions for file targets
            //
            if ($filePath === '/path/to/offending/file') {
                return preg_replace(
                    "%\$class = 'Humbug\\\\Format\\\\Type\\\\' . \$type;%",
                    '$class = \'' . $prefix . '\\\\Humbug\\\\Format\\\\Type\\\\\' . $type;',
                    $content
                );
            }
            return $content;
        },
    ],
];

Whitelisted files

For the files listed in files-whitelist, their content will be left untouched during the scoping process.

Excluded Symbols

Symbols can be marked as excluded as follows:

<?php declare(strict_types=1);

// scoper.inc.php

return [
    'exclude-classes' => ['Stringeable'],
    'exclude-functions' => ['str_contains'],
    'exclude-constants' => ['PHP_EOL'],
];

This enriches the list of Symbols PHP-Scoper's Reflector considers as "internal", i.e. PHP engine or extension symbols and that will be left completely untouched.

This feature should be use very carefully as it can easily break the Composer autoloading and is recommended to be used only for compensating missing symbols from the PhpStorm's stubs shipped with PHP-Scoper.

Whitelist

PHP-Scoper's goal is to make sure that all code for a project lies in a distinct PHP namespace. However, you may want to share a common API between the bundled code of your PHAR and the consumer code. For example if you have a PHPUnit PHAR with isolated code, you still want the PHAR to be able to understand the PHPUnit\Framework\TestCase class.

Constants & Classes & functions from the global namespace

By default, PHP-Scoper will prefix the user defined constants, classes and functions belonging to the global namespace. You can however change that setting for them to be prefixed as usual unless explicitly whitelisted:

<?php declare(strict_types=1);

// scoper.inc.php

return [
    'expose-global-constants' => false,
    'expose-global-classes' => false,
    'expose-global-functions' => false,
];

Symbols

You can whitelist classes, interfaces, constants and functions like so like so:

<?php declare(strict_types=1);

// scoper.inc.php

return [
    'whitelist' => [
        'PHPUnit\Framework\TestCase',
        'PHPUNIT_VERSION',
        'iter\count',
        'Acme\Foo*', // Warning: will not whitelist sub namespaces like Acme\Foo\Bar but will whitelist symbols like
                     // Acme\Foo or Acme\Fooo
    ],
];

Caveats

This will not work on traits and this alias mechanism is case insensitive, i.e. when passing 'iter\count', if a class Iter\Count is found, this class will also be whitelisted.

Implementation insights

Class whitelisting

The class aliasing mechanism is done like follows:

• Prefix the class or interface as usual
• Append a class_alias() statement at the end of the class/interface declaration to link the prefixed symbol to the non prefixed one
• Append a class_exists() statement right after the autoloader is registered to trigger the loading of the method which will ensure the class_alias() statement is executed

It is done this way to ensure prefixed and whitelisted classes can co-exist together without breaking the autoloading. The class_exists() statements are dumped in vendor/scoper-autoload.php, do not forget to include this file in favour of vendor/autoload.php. This part is however sorted out by Box if you are using it with the PhpScoper compactor.

So if you have the following file with a whitelisted class:

<?php

namespace Acme;

class Foo {}

The scoped file will look like this:

<?php

namespace Humbug\Acme;

class Foo {}

\class_alias('Humbug\\Acme\\Foo', 'Acme\\Foo', \false);

With:

<?php

// scoper-autoload.php @generated by PhpScoper

$loader = require_once __DIR__.'/autoload.php';

class_exists('Humbug\\Acme\\Foo');   // Triggers the autoloading of
                                    // `Humbug\Acme\Foo` after the
                                    // Composer autoload is registered

return $loader;

Constants whitelisting

The constant aliasing mechanism is done by transforming the constant declaration into a define() statement when this is not already the case. Note that there is a difference here since define() defines a constant at runtime whereas const defines it at compile time. You have a more details post regarding the differences here

Give the following file with a whitelisted constant:

<?php

namespace Acme;

const FOO = 'X';

The scoped file will look like this:

<?php

namespace Humbug\Acme;

\define('FOO', 'X');

Functions whitelisting

The function aliasing mechanism is done by declaring the original function as an alias of the prefixed one in the vendor/scoper-autoload.php file.

Given the following file with a function declaration:

<?php

// No namespace: this is the global namespace

if (!function_exists('dd')) {
    function dd() {}
}

The file will be scoped as usual in order to avoid any autoloading issue:

<?php

namespace PhpScoperPrefix;

if (!function_exists('PhpScoperPrefix\dd')) {
    function dd() {...}
}

And the following function which will serve as an alias will be declared in the scoper-autoload.php file:

<?php

// scoper-autoload.php @generated by PhpScoper

$loader = require_once __DIR__.'/autoload.php';

if (!function_exists('dd')) {
    function dd() {
        return \PhpScoperPrefix\dd(...func_get_args());
    }
}

return $loader;

Namespaces whitelisting

If you want to be more generic and whitelist a whole namespace, you can do it so like this:

<?php declare(strict_types=1);

// scoper.inc.php

return [
    'whitelist' => [
        'PHPUnit\Framework\*',
    ],
];

Now anything under the PHPUnit\Framework namespace will not be prefixed. Note this works as well for the global namespace:

<?php declare(strict_types=1);

// scoper.inc.php

return [
    'whitelist' => [
        '*',
    ],
];

Note that this may lead to autoloading issues. Indeed if you have the following package:

{
    "autoload": {
        "psr-4": {
            "PHPUnit\\": "src"
        }
    }
}

And whitelist the namespace PHPUnit\Framework\*, then the autoloading for this package will be faulty and will not work. For this to work, the whole package PHPUnit\* would need to be whitelisted.

Warning: the following is not a namespace whitelist:

<?php declare(strict_types=1);

// scoper.inc.php

return [
    'whitelist' => [
        'PHPUnit\F*',   // Will only whitelist symbols such as PHPUnit\F or PHPunit\Foo, but not symbols belonging to
                        // sub-namespaces like PHPunit\Foo\Bar
    ],
];

Building a Scoped PHAR

With Box

If you are using Box to build your PHAR, you can use the existing PHP-Scoper integration. 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

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

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

There is 3 things to manage when dealing with isolated PHARs:

• 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 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 whitelists or patchers.

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 to have several tests for each steps.

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!.
• When using 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 or any other PHAR building tool), you can use the Phar::extractTo() method.

Also take into consideration that bundling code in a PHAR is not guaranteed to work out of the box either. Indeed there is a number of things such as

For this reason, you should also h

Limitations

Dynamic symbols

PHP-Scoper tries to prefix strings as well whenever possible. There will however be cases in which it will not be possible such as:

• strings in regexps, e.g. /^Acme\\\\Foo/
• concatenated strings strings, e.g.:
  • $class = 'Symfony\\Component\\'.$name;
  • const X = 'Symfony\\Component' . '\\Yaml\\Ya_1';

Date symbols

You code may be using a convention for the date string formats which could be mistaken for classes, e.g.:

const ISO8601_BASIC = 'Ymd\THis\Z';

In this scenario, PHP-Scoper has no way to tell that string 'Ymd\THis\Z' does not refer to a symbol but is a date format. In this case, you will have to rely on patchers. Note however that PHP-Scoper will be able to handle some cases such as, see the date-spec.

Heredoc values

If you consider the following code:

<?php

<<<PHP_HEREDOC
<?php

use Acme\Foo;

PHP_HEREDOC;

The content of PHP_HEREDOC will not be prefixed. Some partial support could be added in the future but is bound to be very limited due to the dynamic nature of heredocs. If you consider the following for example:

<?php

<<<EOF
<?php

{$namespaceLine}

// This file has been auto-generated by the Symfony Dependency Injection Component for internal use.

if (\\class_exists(\\Container{$hash}\\{$options['class']}::class, false)) {
    // no-op
} elseif (!include __DIR__.'/Container{$hash}/{$options['class']}.php') {
    touch(__DIR__.'/Container{$hash}.legacy');
    return;
}

if (!\\class_exists({$options['class']}::class, false)) {
    \\class_alias(\\Container{$hash}\\{$options['class']}::class, {$options['class']}::class, false);
}

return new \\Container{$hash}\\{$options['class']}(array(
    'container.build_hash' => '$hash',
    'container.build_id' => '$id',
    'container.build_time' => $time,
), __DIR__.\\DIRECTORY_SEPARATOR.'Container{$hash}');

EOF;

It would be very hard to properly scope the relevant classes.

Callables

If you consider the two following values:

['Acme\Foo', 'bar'];
'Acme\Foo::bar';

The classes used there will not be scoped. It should not be impossible to add support for it but it is currently not supported. See #286.

String values

PHP-Scoper tries whenever possible to prefix strings as well:

class_exists('Acme\Foo');

// Will be prefixed into:

\class_exists('Humbug\Acme\Foo');

PHP-Scoper uses a regex to determine if the string is a class name that must be prefixed. But there is bound to have confusing cases. For example:

• If you have a plain string 'Acme\Foo' which has nothing to do with a class, PHP-Parser will not be able to tell and will prefix it

• Classes belonging to the global scope: 'Foo' or 'Acme_Foo', because there is no way to know if it is a class name or a random string except for a handful of methods:

• class_alias()

• class_exists()

• define()

• defined()

• function_exists()

• interface_exists()

• is_a()

• is_subclass_of()

• trait_exists()

Native functions and constants shadowing

In the following example:

<?php

namespace Foo;

is_array([]);

No use statement is used for the function is_array. This means that PHP will try to load the function \Foo\is_array and if fails to do so will fallback on \is_array (note that PHP does so only for functions and constants: not classes).

In order to bring some performance optimisation, the call will nonetheless be prefixed in \is_array. This will break your code if you were relying on \Foo\is_array instead. This however should be extremely rare, so if that happens you have two solutions: use a patcher or simpler remove any ambiguity by making use of a use statement (which is unneeded outside of the context of prefixing your code):

<?php

namespace Foo;

use function Foo\is_array;

is_array([]);

The situation is exactly the same for constants.

Grouped constants whitelisting

When a grouped constant declaration like the following is given:

const X = 'foo', Y = 'bar';

PHP-Scoper will not be able to whitelist either X or Y. The statement above should be replaced by multiple constant statements:

const X = 'foo';
const Y = 'bar';

Composer Autoloader

PHP-Scoper does not support prefixing the dumped Composer autoloader and autoloading files. This is why you have to manually dump the autoloader again after prefixing an application.

Note: when using Box, Box is able to take care of that step for you.

PHP-Scoper also can not handle Composers static file autoloaders. This is due to Composer loading files based on a hash which is generated from package name and relative file path. For a workaround see #298.

Composer Plugins

Composer plugins are not supported. The issue is that for whitelisting symbols PHP-Scoper relies on the fact that you should load the vendor/scoper-autoload.php file instead of vendor/autoload.php to trigger the loading of the right classes with their class aliases. However Composer does not do that and as a result interfaces such as Composer\Plugin\Capability\Capable are prefixed but the alias is not registered.

This cannot be changed easily so for now when you are using an isolated version of Composer, you will need to use the --no-plugins option.

PSR-0 Partial support

As of now, given the following directory structure:

src/
  JsonMapper.php
  JsonMapper/
    Exception.php

with the following configuration:

{
  "autoload": {
     "psr-0": {"JsonMapper": "src/"}
  }
}

The autoloading will not work. Indeed, PHP-Scoper attempts to support PSR-0 by transforming it to PSR-4, i.e. in the case above:

{
  "autoload": {
     "psr-4": {"PhpScoperPrefix\\JsonMapper": "src/"}
  }
}

If this will work for the classes under src/JsonMapper/, it will not for JsonMapper.php.

WordPress

As of now PHP-Scoper does not easily allow to completely leave unchanged non-included third-party code causing some hurdles with Wordpress plugins. There is a standing issue about providing a better integration out of the box (See #303) but alternatively you can already use WP React Starter which is a boilerplate for WordPress plugins.

If you are not able to migrate you can have a look at the solution itself, read more about it here #303 (comment).

Contributing

Contribution Guide

Credits

Project originally created by: Bernhard Schussek (@webmozart) which has now been moved under the Humbug umbrella.