Repository navigation
Clarify require might be preferable over require_once for autoloaders #5245
Description
Description
The following code:
<?php
spl_autoload_register( function ( $class_name ) {
if ( $class_name === 'Foo' ) {
echo "ONE" . PHP_EOL;
require_once __DIR__ . '/foo.php';
}
} );
spl_autoload_register( function ( $class_name ) {
if ( $class_name === 'Foo' ) {
echo "TWO" . PHP_EOL;
require __DIR__ . '/fake-foo.php';
}
} );
try {
class_exists( Foo::class );
} catch ( Throwable $e ) {
echo 'catch' . PHP_EOL;
}
try {
class_exists( Foo::class );
} catch ( Throwable $e ) {
echo 'catch' . PHP_EOL;
}foo.php
<?php
echo "foo.php" . PHP_EOL;
class Foo extends Bar {}
fake-foo.php
<?php
echo "fake-foo.php" . PHP_EOL;
class Foo {}
Resulted in this output:
ONE
foo.php
catch
ONE
TWO
fake-foo.php
But I expected this output instead:
Up to discussion
It's unexpected that the class of the file is not added to the loaded classes (possibly at least as incomplete class? https://www.php.net/manual/en/class.php-incomplete-class.php) but the file it is located in is.
This leads to unxpected/inconsistent runtime behavior.
Perhaps the file the class is located in should not be added to the loaded files either?
Or the class that failed to load should be added as existing class but incomplete?
Or perhaps any classes it extends/implements (and trait use) should not be autoloaded yet but only when the class is instantiated/used?
Or perhaps treat include/require_once in autoloader like require/include?
Or anything else?
At least, the documentation for spl_autoload_register needs to be updated to clearly mention that it should not use include_once/require_once to load classes, since it can lead to unexpected behavior.
PHP Version
8.5
Operating System
No response
Activity
iluuu1994 commentedon Feb 2, 2026
Hi @kkmuffme. I don't see a bug here.
require_onceis required once. This includes script that throw. When you autoload the second time, the inclusion is skipped and the other autoloader runs instead.This class is only used for serialization. It has no other purpose. If the class can't be linked, it can't be added to the class list. That would break all kinds of assumptions.
I think if you're relying on catching inheritance
Errors, you're in for a bad time in any case. Regardless, let me transfer to the docs repo and then @Girgias can decide whether to close this.[-]Autoloaded class missing implements/extends cannot be loaded again with require_once/will result in different class to be loaded[/-][+]Clarify require might be preferable over require_once for autoloaders[/+]kkmuffme commentedon Feb 3, 2026
I don't have an in issue with the current behavior, the issue is that it's unexpected to say the least - static analysis run into this issue (which is how I ended up becoming aware of it, since it reported missing class errors when running it on a codebase), and upon further inspection in a few projects I realized that people are apparently unaware of it generally (e.g. from Google oauth packages to WooCommerce autoloaders)
Girgias commentedon Feb 3, 2026
Where should this be clarified? As far as I can see all our docs use
includerather thanrequire.I don't see any reason why we should start changing language semantics just because it is run in an autoloader... which in any case would require an RFC.
If there is something you want to add as a description to one of the pages, I'm happy to help with reviewing a PR. But currently I don't really see how this is a problem with PHP.