This is tangential to the function autoload discussion.
An idea that popped into my head an hour ago, that I don't have another PHP
Dev to talk to about, what if you could register a function that is called
by PHP the first time it sees a namespace declared?
This would allow functions and for that matter constants of the namespace
to be declared before they get called. It isn't as clean as waiting until
the function call itself is being called, but maybe that's for the best.
After all, if you have a dozen 10 line utility functions do you necessarily
want 10 files.
Again, I don't know the engine, but this doesn't seem like this would be
that hard to do. Note that how autoloaders register themselves to this
function, resolve what to load and so on is a separate can of worms.
As to what to call it, maybe spl_namespace_register($callback, $prepend).
The callback gets the string of the namespace that PHP just saw for the
first time and it gets to execute before any code in that namespace gets to
execute.
Thoughts?
Le 02/07/2026 à 16:41, Michael Morris a écrit :
This is tangential to the function autoload discussion.
An idea that popped into my head an hour ago, that I don't have
another PHP Dev to talk to about, what if you could register a
function that is called by PHP the first time it sees a namespace
declared?This would allow functions and for that matter constants of the
namespace to be declared before they get called. It isn't as clean as
waiting until the function call itself is being called, but maybe
that's for the best. After all, if you have a dozen 10 line utility
functions do you necessarily want 10 files.Again, I don't know the engine, but this doesn't seem like this would
be that hard to do. Note that how autoloaders register themselves to
this function, resolve what to load and so on is a separate can of worms.As to what to call it, maybe spl_namespace_register($callback,
$prepend). The callback gets the string of the namespace that PHP just
saw for the first time and it gets to execute before any code in that
namespace gets to execute.Thoughts?
Interesting idea, not sure whether it's viable or not.
As of how I understand it, there are multiple ways to do this and all of
them will imply different ways developers can use such feature.
With the namespace order, for instance, imagine the very first namespace
declaration is "namespace Foo\Bar\Baz;": what is the order of
declarations that will be sent to callbacks?
- Will the callbacks receive "Foo\Bar\Baz" as argument directly and be
called only once? - Will they be called once per sub-namespace? If yes, will it be like
calling the callback three times, like this:$callback('Foo'); $callback('Foo\\Bar'); $callback('Foo\\Bar\\Baz'); - How should it propagate if other sub-namespaces of these namespaces
are declared? Like, if you have statements like "namespace Foo\Bar
{} namespace Foo\Baz {}" , would it call registered callbacks like
"Foo -> Foo\Bar -> Foo\Baz", or should it do like no1 and just go
with "Foo\Bar -> Foo\Baz"? - Or something else?
There might be other issues, but that's my "hot reaction" when reading
your suggestion :)
Le 02/07/2026 à 16:41, Michael Morris a écrit :
This is tangential to the function autoload discussion.
An idea that popped into my head an hour ago, that I don't have another
PHP Dev to talk to about, what if you could register a function that is
called by PHP the first time it sees a namespace declared?This would allow functions and for that matter constants of the namespace
to be declared before they get called. It isn't as clean as waiting until
the function call itself is being called, but maybe that's for the best.
After all, if you have a dozen 10 line utility functions do you necessarily
want 10 files.Again, I don't know the engine, but this doesn't seem like this would be
that hard to do. Note that how autoloaders register themselves to this
function, resolve what to load and so on is a separate can of worms.As to what to call it, maybe spl_namespace_register($callback, $prepend).
The callback gets the string of the namespace that PHP just saw for the
first time and it gets to execute before any code in that namespace gets to
execute.Thoughts?
Interesting idea, not sure whether it's viable or not.
As of how I understand it, there are multiple ways to do this and all of
them will imply different ways developers can use such feature.With the namespace order, for instance, imagine the very first namespace
declaration is "namespace Foo\Bar\Baz;": what is the order of declarations
that will be sent to callbacks?
- Will the callbacks receive "Foo\Bar\Baz" as argument directly and be
called only once?Hmm.. Good question. I think one call, with Foo\Bar\Baz, because the goal
is to have a hook so user code can initiate the referencing of that name
space. It would be up to the callback to sort out what to do - the engine
need only give opportunity.
And this applies for use statements as well. For example, if use A\foo;
is foo a class? a function, a constant? Who knows, but this is the moment
to find out and execute this handler.
Or, perhaps, change the use statement so that it explicitly fires a
callback if the referenced chain doesn't already exist. That, however,
creates some overlap to spl_autoload_register, but it might be cleaner all
the same. Calling in functions of a namespace could get JavaScript levels
of obnoxious and runs against the grain of PHP, but this could be eased
with wildcard loading use A\* telling the callback to load all symbols
related to A explicitly.
Maybe this should be tied to use and not to namespace entirely? No - I
don't think so, this isn't intuitive
namespace A;
use A/*;
So I'm thinking both will be needed.
- Will they be called once per sub-namespace? If yes, will it be like
calling the callback three times, like this:$callback('Foo'); $callback('Foo\\Bar'); $callback('Foo\\Bar\\Baz');- How should it propagate if other sub-namespaces of these namespaces
are declared? Like, if you have statements like "namespace Foo\Bar {}
namespace Foo\Baz {}" , would it call registered callbacks like "Foo ->
Foo\Bar -> Foo\Baz", or should it do like no1 and just go with "Foo\Bar ->
Foo\Baz"?- Or something else?
I think some coordination with the engine will be needed, not necessarily
required but for optimization definitely needed.
The engine will track which namespaces it has given the callback the
opportunity to set up. The callback, by returning an array, can tell the
engine what namespaces it has set up. So on namespace A\B\C; The callback
could return ['A', 'A\B', 'A\B\C', 'A\D', 'A\D\E'] because it knows those
other sub namespaces exist and doesn't need to be pestered about them in
the future.
Use statements will need to assume the last symbol encountered is a class,
constant or function and step over it. So
namespace B;
use C\foo;
use D\*;
Breaking down, the engine could end up firing the callback three times.
However, when the callback is made for B it could, for whatever reason,
register C and D as well, run their setups and mark them off - tell the
engine it's done that so the other two firings would be skipped.
Further thinking on the second use statement above - the callback gets
namespace 'D' and needs to set it up. But, this is also an opportunity to
change the load order. Say D has a strpos statement for whatever reason -
the use D* would cause the D namespace to be checked before the root
namespace. I believe the current namespace is also always checked before
the root as well.
This callback could give us a logical place to tell the engine to reverse
this - check root before checking local for a given namespace.
There might be other issues, but that's my "hot reaction" when reading
your suggestion :)
Thanks. Again, this is an idea I haven't really sussed out all the corner
cases. It just struck me as something that could be useful and the more I
look at it the more useful it seems - but symbol loading is a vital and
complicated part of the engine and it definitely needs brainstorming before
any RFC to change it in any way.
And this applies for use statements as well. For example, if
use A\foo;is foo a class? a function, a constant? Who knows, but this is
the moment to find out and execute this handler.
It's known because the syntax says what it is.
use Foo\Bar; // Bar is a class, or a namespace prefix.
use function Foo\Bar\baz; // baz is a function.
use const Foo\Bar\Beep; // Beep is a constant.
This feels somewhat similar to Python, where a given module can have an init.py file that is automatically loaded the first time the module is referenced. I'm not sure how well that maps into PHP (see previous module/package/namespace threads), but it's an interesting model to explore for function autoloading.
--Larry Garfield
On Fri, Jul 3, 2026 at 12:35 PM Larry Garfield larry@garfieldtech.com
wrote:
And this applies for use statements as well. For example, if
use A\foo;is foo a class? a function, a constant? Who knows, but this is
the moment to find out and execute this handler.It's known because the syntax says what it is.
use Foo\Bar; // Bar is a class, or a namespace prefix.
use function Foo\Bar\baz; // baz is a function.
use const Foo\Bar\Beep; // Beep is a constant.
I had forgotten about that. It may simplify things then. Hmm...
This feels somewhat similar to Python, where a given module can have an
init.py file that is automatically loaded the first time the module is
referenced. I'm not sure how well that maps into PHP (see previous
module/package/namespace threads), but it's an interesting model to explore
for function autoloading.--Larry Garfield
I was aware of the Python approach, but I'm also aware of how beloved magic
file names are in PHP (as in, not - see the argument over treating an
extension differently, let alone a reserved file name).
Anyway, the main reason I brought this up is I cannot recall this exact
approach being discussed before. I don't have the expertise to determine if
the path is viable.
Hi Michael,
This is tangential to the function autoload discussion.
An idea that popped into my head an hour ago, that I don't have another PHP Dev to talk to about, what if you could register a function that is called by PHP the first time it sees a namespace declared?
That's a neat idea ...
This would allow functions and for that matter constants of the namespace to be declared before they get called. It isn't as clean as waiting until the function call itself is being called, but maybe that's for the best. After all, if you have a dozen 10 line utility functions do you necessarily want 10 files.
... but do note that function autoloading need not be 1-file-per-function, as is the typical case with classes (cf. PSR-0 and PSR-4). For example, the Moto autoloader allows more-than-one class or function per file.
https://github.com/motophp/autoload
That's only one option for multiples-per-file, so that those "dozen 10 line utility functions" can be in a single file.
-- pmj
Hi Michael,
This is tangential to the function autoload discussion.
An idea that popped into my head an hour ago, that I don't have another
PHP Dev to talk to about, what if you could register a function that is
called by PHP the first time it sees a namespace declared?That's a neat idea ...
This would allow functions and for that matter constants of the
namespace to be declared before they get called. It isn't as clean as
waiting until the function call itself is being called, but maybe that's
for the best. After all, if you have a dozen 10 line utility functions do
you necessarily want 10 files.... but do note that function autoloading need not be 1-file-per-function,
as is the typical case with classes (cf. PSR-0 and PSR-4). For example,
the Moto autoloader allows more-than-one class or function per file.https://github.com/motophp/autoload
That's only one option for multiples-per-file, so that those "dozen 10
line utility functions" can be in a single file.-- pmj
How autoloaders/callbacks use this hook is independent of the hook
implementation itself. It does need to be kept in mind, but it also doesn't
need to be addressed directly in any RFC that rises out of this.
An idea that popped into my head an hour ago, that I don't have
another PHP Dev to talk to about, what if you could register a
function that is called by PHP the first time it sees a namespace
declared?This would allow functions and for that matter constants of the
namespace to be declared before they get called. It isn't as clean as
waiting until the function call itself is being called, but maybe
that's for the best. After all, if you have a dozen 10 line utility
functions do you necessarily want 10 files.
I think this is a really interesting idea.
As you say, grouping a bunch of functions with the same prefix into one
file is probably quite a common pattern anyway - it would certainly give
a very straight-forward migration for purely-static classes, e.g.
GuzzleHttp\Utils::headersFromLines() could become
GuzzleHttp\Utils\headersFromLines(), still defined in src/Utils.php
To answer points that have come up in other replies:
-
I don't think it needs any special handling of sub-namespaces. The
same handler passed "Acme\Foo\Widgets\Green" might load both a
project-level setup at "$packageRoot/setup.php" and a namespace-specific
file "$packageRoot/src/Widgets/Green/functions.php". If it wants "run
once" behaviour, it can use require_once, "if ( defined('some_constant')
) return;", or just unregister itself from the stack. -
I don't think loaders should trigger for "use" statements at all. In
fact, I don't think "use" statements are even visible at run-time -
they're basically a compiler string expansion, which is why you can
write "use Foo\Bar\Baz as B; echo B::class;" without "Foo\Bar\Baz" ever
existing as a symbol.
I think it would be enough to call the handler in three places:
- on a "namespace" declaration (mostly once per file, but a block form
does exist) - just before calling the normal class autoloader
- just before throwing an "undefined function/constant" error for a
qualified function/constant name
This really nicely side-steps the global-vs-namespace sequence problem
that function autoloading always runs into: by the time the engine
reaches an unqualified name, the namespace loader has already run for
the current namespace, and defined any functions it wants. The engine
can fall back to the global namespace, and error immediately if that
fails, without an extra autoload call.
To illustrate:
namespace Acme\Foo\Widgets;
use Omnicorp\Bar\Helpers;
$name = make_widget_name();
echo strlen($name);
Helpers\spin_wheels();
Line 1: All registered namespace loaders called with argument
'Acme\Foo\Widgets'
Line 2: Use statement, has no run-time effect
Line 3: Attempt to call Acme\Foo\Widgets\make_widget_name(); this might
have been defined by the loader at line 1. If it doesn't exist, attempt
to call \make_widget_name(); if that doesn't exist, throw an Error.
Line 4: Attempt to call Acme\Foo\Widgets\strlen(); if that doesn't
exist, call \strlen() which is built-in, so never fails.
Line 5: Attempt to call Omnicorp\Bar\Helpers\spin_wheels(); if it
doesn't exist, call all registered namespace loaders with argument
'Omnicorp\Bar\Helpers' and try again. If it still doesn't exist, throw
an Error.
The only thing that might need a bit more thought is the interaction
with classes: at the moment, the engine doesn't need to "remember" which
autoload calls have already happened, it can just assume that a
successful call won't happen again because the class is no longer
undefined. But with a namespace loader, code like"$client = new
Acme\Foo\Client; $server = new Acme\Foo\Server;" is going to trigger two
calls for "Acme\Foo". If the engine has an explicit cache to avoid the
duplicate call, do we need to invalidate that cache when new handlers
are registered?
The alternative is never to call the namespace loader for class
references, but that means it can't be used for other initialisation,
like setting namespace-level settings or loading data or whatever.
This feels very promising to me as an idea, though, thanks for
contributing it.
--
Rowan Tommins
[IMSoP]
On Sat, Jul 4, 2026 at 7:52 AM Rowan Tommins [IMSoP] imsop.php@rwec.co.uk
wrote:
An idea that popped into my head an hour ago, that I don't have
another PHP Dev to talk to about, what if you could register a
function that is called by PHP the first time it sees a namespace
declared?This would allow functions and for that matter constants of the
namespace to be declared before they get called. It isn't as clean as
waiting until the function call itself is being called, but maybe
that's for the best. After all, if you have a dozen 10 line utility
functions do you necessarily want 10 files.I think this is a really interesting idea.
As you say, grouping a bunch of functions with the same prefix into one
file is probably quite a common pattern anyway - it would certainly give
a very straight-forward migration for purely-static classes, e.g.
GuzzleHttp\Utils::headersFromLines() could become
GuzzleHttp\Utils\headersFromLines(), still defined in src/Utils.phpTo answer points that have come up in other replies:
I don't think it needs any special handling of sub-namespaces. The
same handler passed "Acme\Foo\Widgets\Green" might load both a
project-level setup at "$packageRoot/setup.php" and a namespace-specific
file "$packageRoot/src/Widgets/Green/functions.php". If it wants "run
once" behaviour, it can use require_once, "if ( defined('some_constant')
) return;", or just unregister itself from the stack.I don't think loaders should trigger for "use" statements at all. In
fact, I don't think "use" statements are even visible at run-time -
they're basically a compiler string expansion, which is why you can
write "use Foo\Bar\Baz as B; echo B::class;" without "Foo\Bar\Baz" ever
existing as a symbol.
If it can be avoided, great, but this code worries me:
namespace A;
use function B\foo;
foo();
What happens? I think you give a reply below but I want to be clear that I
understand correctly:
I think it would be enough to call the handler in three places:
- on a "namespace" declaration (mostly once per file, but a block form
does exist)- just before calling the normal class autoloader
- just before throwing an "undefined function/constant" error for a
qualified function/constant name
So, if I'm following, the use statement means the qualified name of B\foo()
is what is called under the hood. Therefore, the callback can be called for
the B namespace before the undefined function/constant error is thrown.
This really nicely side-steps the global-vs-namespace sequence problem
that function autoloading always runs into: by the time the engine
reaches an unqualified name, the namespace loader has already run for
the current namespace, and defined any functions it wants. The engine
can fall back to the global namespace, and error immediately if that
fails, without an extra autoload call.To illustrate:
namespace Acme\Foo\Widgets;
use Omnicorp\Bar\Helpers;
$name = make_widget_name();
echo strlen($name);
Helpers\spin_wheels();Line 1: All registered namespace loaders called with argument
'Acme\Foo\Widgets'Line 2: Use statement, has no run-time effect
Line 3: Attempt to call Acme\Foo\Widgets\make_widget_name(); this might
have been defined by the loader at line 1. If it doesn't exist, attempt
to call \make_widget_name(); if that doesn't exist, throw an Error.Line 4: Attempt to call Acme\Foo\Widgets\strlen(); if that doesn't
exist, call \strlen() which is built-in, so never fails.Line 5: Attempt to call Omnicorp\Bar\Helpers\spin_wheels(); if it
doesn't exist, call all registered namespace loaders with argument
'Omnicorp\Bar\Helpers' and try again. If it still doesn't exist, throw
an Error.
Yeah, you've accounted for it too. I just read too quickly the first time
over. We're on the same page. I'll still post my reasoning out of this
because it might help someone else follow it as well.
The only thing that might need a bit more thought is the interaction
with classes: at the moment, the engine doesn't need to "remember" which
autoload calls have already happened, it can just assume that a
successful call won't happen again because the class is no longer
undefined. But with a namespace loader, code like"$client = new
Acme\Foo\Client; $server = new Acme\Foo\Server;" is going to trigger two
calls for "Acme\Foo". If the engine has an explicit cache to avoid the
duplicate call, do we need to invalidate that cache when new handlers
are registered?
One possible way to quietly bypass this is if the namespace and class
autoloaders are the same function, don't double call. I imagine that if
this was added composer would likely be upgraded to take this into account.
I know that if I had an autoload system I would setup a common entry point.
A backwards compatible way to do this is to start giving the callback
supplied to spl_autoload_register both a $class and $namespace argument.
Existing callbacks will ignore the unexpected (to them) 2nd argument, but
new callbacks would be able to work with it. So
function myAutoloader(string $class, string $namespace = null) {
/*
* namespace register only sends one argument for the namespace, so
* if the second arg is null, spl_namespace_register is the caller
*/
if ($namespace === null) {
$namespace = class;
$class = null;
}
/* further resolve logic here */
}
spl_autoload_register("myAutoloader");
spl_namespace_register("myAutoloader");
The alternative is never to call the namespace loader for class
references, but that means it can't be used for other initialisation,
like setting namespace-level settings or loading data or whatever.
There's no reason a class autoloader cannot also initialize a namespace by
including a setup file before the class file. The last time I wrote an
autoloader I did this, but I had to be careful that all initial references
to a namespace where class requests (which was brittle).
As far as invalidating the cache when a new handler is registered - that is
the suboptimal but safest approach. Just as with class autoloaders, ideally
an application shouldn't need multiple namespace autoloaders.
This feels very promising to me as an idea, though, thanks for
contributing it.
You're welcome.
After feedback from Rowan Tommins, Larry Garfield, pmjones and Alex Rock
I'm going to move to a first draft of a spec for this idea.
INTRODUCTION
Numerous attempts have been made to create function and constant
autoloaders within namespaces, and they've ran into problems concerning
symbol lookup. This RFC proposes to sidestep this issue by allowing
userland to register an improved autoloader able to not only handle the
first time classes are sought out by the engine, but also the first time
the engine sees a namespace. This allows userland code to set up a
namespace - load its functions, constants and/or perform other
initialization work deemed necessary by the user.
PROPOSAL
Users will be able to provide a callback to spl_autoload_register() that
has two string arguments instead of one. If they do those arguments are as
follows.
function (string $class, string $namespace) {}
When the engine encounters a class that it does not have on the symbol
table it will invoke the callback for the class as it presently does. The
namespace argument will only be populated if the engine has not seen this
namespace. For example
$a = new A\AClass();
$b = new A\BClass();
Line 1: Autoloader will be called with arguments ("A\AClass", "A")
Line 2: Autoloader will be called with arguments ("A\BClass", null)
PHP will also call the autoloader when it encounters the namespace keyword
referencing a namespace it hasn't seen before. Hence
namespace B;
This will result in a call to the autoloader with arguments (null, "B")
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.
BACKWARDS INCOMPATIBLE CHANGES
None foreseen.
I guess technically if someone has already written an autoloader that takes
2 or more arguments the code would break because the engine previously was
not sending 2 arguments. However, is this a realistic thing to worry about?
I can't think of a rational reason to write such an autoloader.
Note that autoloaders written to this spec should happily run on older PHP
versions because those versions will always give null to the 2nd argument
causing the autoloader to only act on its class code. An autoloader that
prepares namespaces based on classes is still possible, but unsafe since a
function from the namespace could get called.
PROPOSED PHP VERSIONS
This should be safe on any minor release. Realistically this won't be
available until 8.7 I would guess as we're already in 8.6 alpha. I don't
think this could be coded before feature freeze, but I don't know the
engine well. I think I can do this myself though if needed, especially if
someone volunteers to coach me.
RFC IMPACT
This RFC allows a route to function autoloading by sidestepping issues it
has had. Quoting Rowan Tommins (with example updated to reflect this
proposal):
This really nicely side-steps the global-vs-namespace sequence problem
that function autoloading always runs into: by the time the engine
reaches an unqualified name, the namespace loader has already run for
the current namespace, and defined any functions it wants. The engine
can fall back to the global namespace, and error immediately if that
fails, without an extra autoload call.To illustrate:
namespace Acme\Foo\Widgets;
use Omnicorp\Bar\Helpers;
$name = make_widget_name();
echo strlen($name);
Helpers\spin_wheels();Line 1: All autoloaders that accept 2 arguments are called with arguments
(null, 'Acme\Foo\Widgets')Line 2: Use statement, has no run-time effect
Line 3: Attempt to call Acme\Foo\Widgets\make_widget_name(); this might
have been defined by the loader at line 1. If it doesn't exist, attempt
to call \make_widget_name(); if that doesn't exist, throw an Error.Line 4: Attempt to call Acme\Foo\Widgets\strlen(); if that doesn't
exist, call \strlen() which is built-in, so never fails.Line 5: Attempt to call Omnicorp\Bar\Helpers\spin_wheels(); if it
doesn't exist, call all autoloaders that accept two arguments with
arguments
(null, 'Omnicorp\Bar\Helpers') and try again. If it still doesn't exist,
throw
an Error.
And to extend on his example, when a class is referenced from a previously
unknown namespace the autoloader will receive both arguments as outlined
above and be responsible for executing both setup processes.
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.
PHP will also call the autoloader when it encounters the namespace
keyword referencing a namespace it hasn't seen before. Hencenamespace B;This will result in a call to the autoloader with arguments (null, "B")
you (and the current implementation's) callback defines 1st argument as
string. Changing it to accept null will be a big BC break you missed.
Maybe an empty string would solve that.
--
Aleksander Machniak
Kolab Groupware Developer [https://kolab.org]
Roundcube Webmail Developer [https://roundcube.net]
PGP: 19359DC1 # Blog: https://kolabian.wordpress.com
I guess technically if someone has already written an autoloader that
takes 2 or more arguments the code would break because the engine
previously was not sending 2 arguments. However, is this a realistic
thing to worry about? I can't think of a rational reason to write such
an autoloader.
There is the default autoloader
https://www.php.net/manual/en/function.spl-autoload.php.
--
Aleksander Machniak
Kolab Groupware Developer [https://kolab.org]
Roundcube Webmail Developer [https://roundcube.net]
PGP: 19359DC1 # Blog: https://kolabian.wordpress.com
Le 07/07/2026 à 05:06, Michael Morris a écrit :
After feedback from Rowan Tommins, Larry Garfield, pmjones and Alex
Rock I'm gong to move to a first draft of a spec for this idea.INTRODUCTION
Numerous attempts have been made to create function and constant
autoloaders within namespaces, and they've ran into problems
concerning symbol lookup. This RFC proposes to sidestep this issue by
allowing userland to register an improved autoloader able to not only
handle the first time classes are sought out by the engine, but also
the first time the engine sees a namespace. This allows userland code
to set up a namespace - load its functions, constants and/or perform
other initialization work deemed necessary by the user.PROPOSAL
Users will be able to provide a callback tospl_autoload_register()
that has two string arguments instead of one. If they do those
arguments are as follows.function (string $class, string $namespace) {}When the engine encounters a class that it does not have on the symbol
table it will invoke the callback for the class as it presently does.
The namespace argument will only be populated if the engine has not
seen this namespace. For example$a = new A\AClass(); $b = new A\BClass();Line 1: Autoloader will be called with arguments ("A\AClass", "A")
Line 2: Autoloader will be called with arguments ("A\BClass", null)PHP will also call the autoloader when it encounters the namespace
keyword referencing a namespace it hasn't seen before. Hencenamespace B;This will result in a call to the autoloader with arguments (null, "B")
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.BACKWARDS INCOMPATIBLE CHANGES
None foreseen.I guess technically if someone has already written an autoloader that
takes 2 or more arguments the code would break because the engine
previously was not sending 2 arguments. However, is this a realistic
thing to worry about? I can't think of a rational reason to write such
an autoloader.Note that autoloaders written to this spec should happily run on older
PHP versions because those versions will always give null to the 2nd
argument causing the autoloader to only act on its class code. An
autoloader that prepares namespaces based on classes is still
possible, but unsafe since a function from the namespace could get called.PROPOSED PHP VERSIONS
This should be safe on any minor release. Realistically this won't be
available until 8.7 I would guess as we're already in 8.6 alpha. I
don't think this could be coded before feature freeze, but I don't
know the engine well. I think I can do this myself though if
needed, especially if someone volunteers to coach me.RFC IMPACT
This RFC allows a route to function autoloading by sidestepping issues
it has had. Quoting Rowan Tommins (with example updated to reflect
this proposal):This really nicely side-steps the global-vs-namespace sequence problem
that function autoloading always runs into: by the time the engine
reaches an unqualified name, the namespace loader has already run for
the current namespace, and defined any functions it wants. The engine
can fall back to the global namespace, and error immediately if that
fails, without an extra autoload call.To illustrate:
namespace Acme\Foo\Widgets;
use Omnicorp\Bar\Helpers;
$name = make_widget_name();
echo strlen($name);
Helpers\spin_wheels();Line 1: All autoloaders that accept 2 arguments are called with
arguments
(null, 'Acme\Foo\Widgets')Line 2: Use statement, has no run-time effect
Line 3: Attempt to call Acme\Foo\Widgets\make_widget_name(); this might
have been defined by the loader at line 1. If it doesn't exist, attempt
to call \make_widget_name(); if that doesn't exist, throw an Error.Line 4: Attempt to call Acme\Foo\Widgets\strlen(); if that doesn't
exist, call \strlen() which is built-in, so never fails.Line 5: Attempt to call Omnicorp\Bar\Helpers\spin_wheels(); if it
doesn't exist, call all autoloaders that accept two arguments with
arguments
(null, 'Omnicorp\Bar\Helpers') and try again. If it still doesn't
exist, throw
an Error.And to extend on his example, when a class is referenced from a
previously unknown namespace the autoloader will receive both
arguments as outlined above and be responsible for executing both
setup processes.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'm not sure that I like the current shift of the first ideas you exposed.
At first, it was about adding an internal hook when encountering a
"namespace" statement. Something that could be used to setup libraries
after autoload, for instance.
Here, your new draft suggests an update to the "use" statement, which
currently has absolutely zero impact, and doesn't trigger autoload at
all. Plus, it would trigger in two different ways, depending on whether
the final symbol exists in the symbols table or not, and triggering
another call with the namespace as argument.
This sounds out of scope and a bit too much direct impact, because it
will happen on any unloaded symbol, especially built-in functions that
have not been fully-qualified using a "use function strlen"-like
statement or a fully-qualified reference, like "\strlen()".
These are two completely different proposals to me, and deserve two
different RFCs:
- Namespace declaration hooks, via a hypothetical
"spl_namespace_declaration_register($callback)" function (or whatever
other naming that fits better - Triggering autoload and namespace declaration hooks when resolving
unresolved "use" statements (at whatever steps, of the compilation or
runtime)
Another thing: updating existing spl_autoload_register callbacks with a
non-deterministic additional "$namespace" argument seems like a no-go to
me: this goes beyond what autoload currently does. Triggering a
namespace-declaration hook should be done after autoload IMO, to
separate both features as much as possible.
I mean this especially with this example of yours:
$a = new A\AClass();
$b = new A\BClass();
Line 1: Autoloader will be called with arguments ("A\AClass", "A")
Line 2: Autoloader will be called with arguments ("A\BClass", null)
The above behavior suggestion implies that it works like this:
Since autoloader is called with ("A\AClass", "A") , the result of it
might be an exception for undefined class, or an error coming from the
namespace declaration hooks, all at the same place and coming from the
same callbacks.
If you do it in two ways so that the two features are separated inside
engine itself , autoloaders won't have to change at all, but
willing-devs that need to listen to namespace declarations will have
their own code, namespaces, stack traces, etc., if an error occurs. But
what is certain is that if the namespace hook is reached, it means the
autoloading process was a success: can't trigger namespace hook if the
autoloader throws an exception, or if the PHP file that's loaded doesn't
declare any namespace at all (which would be a violation of some PSR
rules, depending on the project, but it's another subject). This
guarantees that all namespace hooks will be called after a successful
autoload, therefore the potential classes in the declared namespace are
already autoloaded.
Still, it still implies a non-deterministic assumption about "what has
already been declared". A namespace hook should not take care at all on
whether the classes in its namespace have been declared already, or it
might "ensure" it with a bunch of graceful "require_once" calls. And if
these required files correspond to the same namespace, no further hooks
are called. If required files belong to sub-namespaces, however, hooks
will be called... and here comes the chain of calls.
PHP's autoload is powerful, but things can become really annoying, since
autoload is called for ANY non-existing symbol (classes, functions,
constants) that have to be resolved before being actually called.
Thanks to Composer, we have classmaps (and even authoritative classmaps)
that drastically improves performances, but it's not built-in PHP.
Adding namespace declaration hooks in the process would kinda enforce
Composer to update its behavior and its dumped autoloaders to include
all namespace hooks that can be registered by libraries, and since
autoload isn't predictable about the order in which classes will be
loaded, it's gonna be the exact same for namespaces, if not worse.
I think the whole thing is an interesting idea, but so far, there's
still quite a lot of things that can become messy depending on how it's
implemented, and in consideration of the impact on the ecosystem itself,
and I'm not seeing a lot of values or problems solved, apart the
potential to solve the "function autoload" issue that's been there for a
while, but it looks quite overkill as a feature if it only solves
function autoload 😕
Le 07/07/2026 à 05:06, Michael Morris a écrit :
I'm not sure that I like the current shift of the first ideas you exposed.
At first, it was about adding an internal hook when encountering a
"namespace" statement. Something that could be used to setup libraries
after autoload, for instance.
At first it was a function to hook into the namespace keyword and fire code
that would initialize the newly declared namespace. However, namespaces
also get declared when a new class is loaded. The namespace init logic
would still end up firing - when the class def file is loaded it's going to
have a namespace keyword. So this can be be accomplished with just that
function - but it occured to me that it's actually highly unlikely that a
dev will want to do this without also taking autoloading into account. So
it makes sense to unify the handlers.
Here, your new draft suggests an update to the "use" statement, which
currently has absolutely zero impact, and doesn't trigger autoload at
all.
And you've misread the proposal entirely. Use statements still do nothing
under this proposal.
Plus, it would trigger in two different ways, depending on whether
the final symbol exists in the symbols table or not, and triggering
another call with the namespace as argument.
Again, no, that's not how it works at all. I'll repeat the example
namespace Acme\Foo\Widgets;
The autoloaders may be called after this line. Supplied callbacks with 2
arguments will receive (null, "Acme\Foo\Widgets"). Supplied callbacks
expecting 1 argument will NOT BE CALLED, as they are presumed to be of the
older form and are only able to load classes, and that's not what's
happening here.
use Omnicorp\Bar\Helpers;
Nothing happens on this line currently, or under the RFC.
$controller = new Controller();
The engine will look for Acme\Foo\Widgets\Controller. If it doesn't find it
autoloaders are invoked. Autoloaders that expect 1 argument will receive
"Acme\Foo\Widgets\Controller". Autoloaders expecting 2 arguments will
receive ("Acme\Foo\Widgets\Controller", null). Why null? Because the
namespace declaration at the beginning of the file already tripped off
namespace initialization and it should not need to run again.
$name = make_widget_name();
The engine will try to call Acme\Foo\Widgets\make_widget_name, and on
failure will try \make_widget_name, and if that fails a fatal error is
raised. This function can be defined by the namespace initialization code
gets called with the namespace statement.
echo strlen($name);
The engine will try to call Acme\Foo\Widgets\strlen() and on failure will
call \strlen() which is always available.
Helpers\spin_wheels();
The use statement above silently rewrites this line as
Omnicorp\Bar\Helpers, and now at this line Omnicorp\Bar\Helpers\spin_wheels
is called. If it fails, since "Omnicorp\Bar\Helpers" is not in the list of
initialized namespaces the engine will call autoloaders expecting 2
arguments only with argument (null, "Omnicorp\Bar\Helpers"). After these
callbacks run, Omnicorp\Bar\Helpers\spin_wheels() will be retried. If it
fails \spin_wheels() will be tried, and a fatal error raises if the symbol
still does not resolve.
I will not address the rest of your reply as it is responding to a
misunderstanding of how the RFC works.
After feedback from Rowan Tommins, Larry Garfield, pmjones and Alex
Rock I'm going to move to a first draft of a spec for this idea.INTRODUCTION
Numerous attempts have been made to create function and constant
autoloaders within namespaces, and they've ran into problems concerning
symbol lookup. This RFC proposes to sidestep this issue by allowing
userland to register an improved autoloader able to not only handle the
first time classes are sought out by the engine, but also the first
time the engine sees a namespace. This allows userland code to set up a
namespace - load its functions, constants and/or perform other
initialization work deemed necessary by the user.PROPOSAL
Users will be able to provide a callback tospl_autoload_register()
that has two string arguments instead of one. If they do those
arguments are as follows.function (string $class, string $namespace) {}When the engine encounters a class that it does not have on the symbol
table it will invoke the callback for the class as it presently does.
The namespace argument will only be populated if the engine has not
seen this namespace. For example$a = new A\AClass(); $b = new A\BClass();Line 1: Autoloader will be called with arguments ("A\AClass", "A")
Line 2: Autoloader will be called with arguments ("A\BClass", null)PHP will also call the autoloader when it encounters the namespace
keyword referencing a namespace it hasn't seen before. Hencenamespace B;This will result in a call to the autoloader with arguments (null, "B")
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.BACKWARDS INCOMPATIBLE CHANGES
None foreseen.I guess technically if someone has already written an autoloader that
takes 2 or more arguments the code would break because the engine
previously was not sending 2 arguments. However, is this a realistic
thing to worry about? I can't think of a rational reason to write such
an autoloader.Note that autoloaders written to this spec should happily run on older
PHP versions because those versions will always give null to the 2nd
argument causing the autoloader to only act on its class code. An
autoloader that prepares namespaces based on classes is still possible,
but unsafe since a function from the namespace could get called.PROPOSED PHP VERSIONS
This should be safe on any minor release. Realistically this won't be
available until 8.7 I would guess as we're already in 8.6 alpha. I
don't think this could be coded before feature freeze, but I don't know
the engine well. I think I can do this myself though if needed,
especially if someone volunteers to coach me.RFC IMPACT
This RFC allows a route to function autoloading by sidestepping issues
it has had. Quoting Rowan Tommins (with example updated to reflect this
proposal):This really nicely side-steps the global-vs-namespace sequence problem
that function autoloading always runs into: by the time the engine
reaches an unqualified name, the namespace loader has already run for
the current namespace, and defined any functions it wants. The engine
can fall back to the global namespace, and error immediately if that
fails, without an extra autoload call.To illustrate:
namespace Acme\Foo\Widgets;
use Omnicorp\Bar\Helpers;
$name = make_widget_name();
echo strlen($name);
Helpers\spin_wheels();Line 1: All autoloaders that accept 2 arguments are called with arguments
(null, 'Acme\Foo\Widgets')Line 2: Use statement, has no run-time effect
Line 3: Attempt to call Acme\Foo\Widgets\make_widget_name(); this might
have been defined by the loader at line 1. If it doesn't exist, attempt
to call \make_widget_name(); if that doesn't exist, throw an Error.Line 4: Attempt to call Acme\Foo\Widgets\strlen(); if that doesn't
exist, call \strlen() which is built-in, so never fails.Line 5: Attempt to call Omnicorp\Bar\Helpers\spin_wheels(); if it
doesn't exist, call all autoloaders that accept two arguments with arguments
(null, 'Omnicorp\Bar\Helpers') and try again. If it still doesn't exist, throw
an Error.And to extend on his example, when a class is referenced from a
previously unknown namespace the autoloader will receive both arguments
as outlined above and be responsible for executing both setup processes.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.
"So many problems in programming come from making one thing try to do two things." --I forget who
I quite like the idea of having a "namespace autoload file" (or files). It seems like it would neatly side step most issues with function autoloading, and offer a place for "small stuff" that arguably doesn't need its own file: A 2 element enum, typedefs if we ever get them, empty exception classes, etc. I'd support going this route.
However, like others, I dislike shoving both autoload paths into a single callback function. Just let it be its own utility, independent of class autoloading. Having to think about many different code paths in a single function (how do I behave on string, null; null, string; and string, string; and wait, what about null,null?) is bugs waiting to happen and needlessly confusing.
Let's also remember that there's really only one autoloader that matters for most projects: Composer. And that autoloader is called hundreds or thousands of times on every request, in an FPM type setup. Adding even a single if-statement to that function would have a performance impact on nearly every PHP project in the world, and in practice this approach would require adding several, I'm sure.
Just make it its own autoload registration system and be done with it. Otherwise, I like this approach better than most function autoloading proposals that have come up, because it doesn't push toward function-per-file, which I don't think anyone wants.
As far as FIG and Composer, I'm not sure we'd even need a PSR. Composer would likely just add an "autoload_namespaces" key, which maps namespaces to a file or files, and do it itself. The only use for a PSR would be to have some standard name that Composer would automatically register; it's up to the Composer team if they would benefit from that. I'm happy to help on the FIG side if so, but that's really their call.
--Larry Garfield
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:
-
When an undefined function or constant is encountered with a
qualified name -
At the top of any file or block using the "namespace" keyword (i.e.
when that line is reached at run-time) -
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]