Exlcuding global namespace on versions >=0.18.0

[VBelozyorov]

I have a project where I use PHP-Scoper to isolate dependencies. Initially, PHP-Scoper was added when it was on version 0.17.5. Now I’m trying to update PHP-Scoper to 0.18.18 and have some questions about the results.

My scoper.inc.php looks like this:

<?php

declare(strict_types=1);

use Isolated\Symfony\Component\Finder\Finder;

…

return [
    'prefix' => 'myPrefix',
    'finders' => [ … ],
    'exclude-files' => [ … ],

    'patchers' => [ … ],

    'exclude-namespaces' => [        
        '~^$~',
        …
    ],
    'exclude-classes' => [],
    'exclude-functions' => [],
    'exclude-constants' => [],

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

As an example, I have a file in my project with the following content:

<?php

class Parts_MyProject_Config extends Base_Config
{
    public function getDefaults()
    {
        …
    }
}

With PHP-Scoper 0.18.18, I get that file processed as follows:

<?php

namespace {
    class Parts_MyProject_Config extends \Base_Config
    {
        public function getDefaults()
        {
            …
        }
    }

    \class_alias('myPrefix\Parts_MyProject_Config', 'Parts_MyProject_Config', \false);
}

The only difference compared to the result of PHP-Scoper 0.17.5 is the class_alias() call.

This is probably expected because of this:
1a30d98#diff-c411ff3325ee021026ca5314ce27ee16e29049575e909fe1a4a924340bab39b2R84-R89

But I don’t quite understand the idea of how this should work. Could you please help me with this?

// Excluded global classes (for which we found a declaration) need to be
// aliased since otherwise any usage will not point to the prefixed
// version (since it's an alias) but the declaration will now declare
// a prefixed version (due to the namespace).

In my case, it seems I don’t have a declaration for the prefixed version, and the alias just doesn’t work.

Is the exclusion of the global namespace no longer allowed since 0.18.0?

[theofidry]

Uff a bit hard to recall exactly! I vaguely remember it was related to polyfills to support them without any extra work. I remember clearly the case for the functions, but I can't recall for classes.

In my case, it seems I don’t have a declaration for the prefixed version, and the alias just doesn’t work.

Which should be fine: the alias shouldn't cause any failure does it?

Is the exclusion of the global namespace no longer allowed since 0.18.0?

The alias statement doesn't prevent the exclusion does it? Note that https://github.com/humbug/php-scoper/releases/tag/0.18.0-rc.0 global symbols are now exposed default. Edit: I see that you set it to false though so should not matter.

---

As a rule of thumb:

• exposed = people using this scoped code should be able to access to some symbols (it does make the scoping promise weaker, but sometimes it's necessary).
• excluded: polyfills and symbols not declared by yourself, i.e. third-party code that will execute your scoped code.

[VBelozyorov]

First of all, thank you for your quick reply and for your work on this tool — it's much appreciated!

I just wanted to clarify a few details:

Which should be fine: the alias shouldn't cause any failure does it?

Strictly speaking, it works, but it produces a warning that leads (in my case) to execution failure.
See https://3v4l.org/8gMuT#vnull

excluded: polyfills and symbols not declared by yourself, i.e. third-party code that will execute your scoped code.

Is the excluded code supposed to execute my scoped code, or is my scoped code supposed to execute the excluded code? 🤔

Returning to the code lines I referenced (1a30d98#diff-c411ff3325ee021026ca5314ce27ee16e29049575e909fe1a4a924340bab39b2R84-R89):

        // Excluded global classes (for which we found a declaration) need to be
        // aliased since otherwise any usage will not point to the prefixed
        // version (since it's an alias) but the declaration will now declare
        // a prefixed version (due to the namespace).
        return $this->enrichedReflector->belongsToGlobalNamespace($resolvedName)
            && $this->enrichedReflector->isClassExcluded($resolvedName);

Doesn't exclusion mean that the class's namespace won't be prefixed? So we don't have a declaration of the prefixed version and, in turn, don't need to add an alias pointing to the undeclared prefixed class?

From what I see in my project, there really aren't any declarations for prefixed versions of excluded classes.

[theofidry]

Strictly speaking, it works, but it produces a warning that leads (in my case) to execution failure.

Hmm, maybe it is incorrect then. I'll have to look into it.

excluded: polyfills and symbols not declared by yourself, i.e. third-party code that will execute your scoped code.
Is the excluded code supposed to execute my scoped code, or is my scoped code supposed to execute the excluded code? 🤔

You lost me 😅

I remember before excluded meant the symbol was left entirely alone, but eventually that definition changed a bit.

For certain, a key point is that it is registered to PHP-Scoper's reflector to define what is an internal (i.e. comes from PHP or an extension) symbol, and this fits the case of consuming third-party symbols. The easiest example is a WP: it defines some symbols and your plugin may use them, e.g. Wordpress\Config (made up name). Your scoped code needs to be able to use that symbol, but you don't declare it, so it should not be prefixed to <prefix>\Wordpress\Config.

Exposed symbols on the other hand are meant for symbols declared by your code, but for which you want people using your scoped code to still be able to use. (necessary remainder, this does weaken the promise of PHP-Scoper).

Now this is the theory and usage, but as I said the implementation changed a bit and I'm not clear anymore how things are working. I remember changing strategy at some point to use more aliases, tracking the usage of symbols and dumping the aliases in the scoper autoload to fix cases of broken autoloading and making the support of polyfills native, i.e. without any extra config. But all of that the details are kinda lost to me right now, I'd need to dig back into it, which I'll have to do soonish to review the PHP 8.5 and Symfony8 support.

That said if you have a concrete minimal setup that breaks, that would make it easier for me to double check. In order of preference:

• A spec test (see the tests in specs/). This is more akin to a unit test however, so maybe too limited to highlight the issue.
• An e2e test, there is several examples in fixtures/set*. Setting up the test is done via e2e.Makefile, but honestly I can do without. As long as there is minimal code with a reproducible script, that is sufficient.
• A dedicated repository reproducing the issue, the less there is there the better.

I'll have a look regardless, but having a concrete failing scenario would certainly help. Unfortunately it's also getting Christmas time so I cannot guarantee I'll have a look at it before January.

[VBelozyorov]

I think I understand the difference between the reasons for excluding and exposing symbols. But in the end, they seem to me like two different approaches to the same result: a symbol can be called without a prefix from outside the scoped code.

• Excluding: by not changing either the declaration or the calls.
• Exposing: by creating an alias that points to the prefixed declaration and by prefixing every call within the scoped code.

Of course, there are probably more differences that I just don’t know about yet.

I’ll try to prepare a spec in the coming days.

UPD: A couple of clarifications

[theofidry]

Of course, there are probably more differences that I just don’t know about yet.

I could also be that there should no longer be a distinction between the two. I'll keep that in mind once diving into that again.