Pre-RFC spitball - Namespace Load event

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.

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.

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.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.

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.