On 07/07/2026 04:06, Michael Morris wrote:
If a namespace chain is encountered only one call is made. Hence
```
namespace A\B\C;
```
Will result in a call to the autoloader of (null, "A\B\C").
NOTE. The engine will mark namespaces "A" and "A\B" as seen in
addition to the specified namespace "A\B\C", so the autoloader needs
to work out if it should do anything for those namespaces as well.
Hi Michael,
I agree with others that adding an extra parameter to the class
autoloader is probably more confusing than helpful. I think the same is
true of this idea of "namespace chains" and marking multiple prefixes as
"seen" at once.
Let's say I want to register an autoloader that loads a file
'src/Acme/Frobulator/functions.php' containing functions in the
namespace 'Acme\Frobulator'. In your current draft, I would have to
register an autoloader that checked:
- that the namespace argument is not null
- that EITHER the namespace argument is exactly 'Acme\Frobulator' OR
begins with 'Acme\Frobulator\' (I don't want to also match
'Acme\FrobulatorNG')
- that I haven't already loaded the file - since calls will still happen
for both 'Acme\Frobulator\Foo' and 'Acme\Frobulator\Bar'
Or maybe I want to automatically check for a relevant 'functions.php',
so need to break down an argument of 'Acme\Frobulator\Foo' into a loop
looking for 'src/Acme/functions.php' and
'src/Acme/Frobulator/functions.php'
and 'src/Acme/Frobulator/Foo/functions.php' - again, manually handling
the fact that I'll get a call for 'Acme\Frobulator\Bar'.
All of that complexity can be completely avoided with a single-argument
function, called with the exact namespace which is being seen for the
first time. One name check for a specific namespace, or one file stat
check for a specific file name.
If someone wants to match "any namespace starting Acme\", that looks
exactly the same either way: check with str_starts_with, and account for
multiple namespaces matching that prefix.
That function would be called:
1) When an undefined function or constant is encountered with a
qualified name
2) At the top of any file or block using the "namespace" keyword (i.e.
when that line is reached at run-time)
3) When an undefined class-like (class, trait, interface, enum) is
encountered with a non-empty namespace prefix, either just before or
just after the existing autoloader
Once the function has been called, the exact string it was given is
added to an internal hashmap. Future events which would call with that
exact string are skipped, unless a new callback has been registered.
Note that (2) and (3) cover different use cases: (2) covers unqualified
function and constant calls, which need to be loaded early so that
global fallback still works efficiently; (3) covers files with multiple
class-likes, e.g. 'src/Acme/Frobulator/Options/enums.php' containing a
bunch of enums in the 'Acme\Frobulator\Options' namespace.
As you point out, (2) is also a natural point for "namespace setup"
behaviour, beyond just declaring symbols.
This RFC will almost certainly trigger a related PSR standard that
takes namespace setup into account. Once that is settled the
maintainers of composer will likely implement such a standard. One
possible route is to follow Python's lead of having a __setup__.php
file in the namespace's directory if the namespaces are set up in
mirror to the file system setup, but nothing in this RFC mandates that
approach.
I would imagine it less as a single "setup" file, and more as a
convention for files with more than one symbol in - as in the above
examples of 'src/Acme/Frobulator/functions.php' and
'src/Acme/Frobulator/Options/enums.php'
Maybe even a prefix, like 'autoload_', so that
'src/Acme/Frobulator/autoload_helpers.php',
'src/Acme/Frobulator/autoload_shortcuts.php' and
'src/Acme/Frobulator/autoload_mode_consts.php' all get picked up
automatically.
As you say, not something the RFC needs to mandate, but examples can be
useful to picture how a feature would play out in practice.
--
Rowan Tommins
[IMSoP]
