PHP 8.1.30 Released!

spl_autoload_register

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

spl_autoload_registerRegister given function as __autoload() implementation

Description

spl_autoload_register(?callable $callback = null, bool $throw = true, bool $prepend = false): bool

Register a function with the spl provided __autoload queue. If the queue is not yet activated it will be activated.

If your code has an existing __autoload() function then this function must be explicitly registered on the __autoload queue. This is because spl_autoload_register() will effectively replace the engine cache for the __autoload() function by either spl_autoload() or spl_autoload_call().

If there must be multiple autoload functions, spl_autoload_register() allows for this. It effectively creates a queue of autoload functions, and runs through each of them in the order they are defined. By contrast, __autoload() may only be defined once.

Parameters

callback

The autoload function being registered. If null, then the default implementation of spl_autoload() will be registered.

callback(string $class): void

The class will not contain the leading backslash of a fully-qualified identifier.

throw

This parameter specifies whether spl_autoload_register() should throw exceptions when the callback cannot be registered.

Warning

This parameter is ignored as of PHP 8.0.0, and a notice will be emitted if set to false. spl_autoload_register() will now always throw a TypeError on invalid arguments.

prepend

If true, spl_autoload_register() will prepend the autoloader on the autoload queue instead of appending it.

Return Values

Returns true on success or false on failure.

Changelog

Version Description
8.0.0 callback is now nullable.

Examples

Example #1 spl_autoload_register() as a replacement for an __autoload() function

<?php

// function __autoload($class) {
// include 'classes/' . $class . '.class.php';
// }

function my_autoloader($class) {
include
'classes/' . $class . '.class.php';
}

spl_autoload_register('my_autoloader');

// Or, using an anonymous function
spl_autoload_register(function ($class) {
include
'classes/' . $class . '.class.php';
});

?>

Example #2 spl_autoload_register() example where the class is not loaded

<?php

namespace Foobar;

class
Foo {
static public function
test($class) {
print
'[['. $class .']]';
}
}

spl_autoload_register(__NAMESPACE__ .'\Foo::test');

new
InexistentClass;

?>

The above example will output something similar to:

[[Foobar\InexistentClass]]
Fatal error: Class 'Foobar\InexistentClass' not found in ...

Example #3 The identifier will be provided without the leading backslash

<?php

spl_autoload_register
(static function ($class) {
var_dump($class);
});

class_exists('RelativeName');
class_exists('RelativeName\\WithNamespace');
class_exists('\\AbsoluteName');
class_exists('\\AbsoluteName\\WithNamespace');

?>

The above example will output:

string(12) "RelativeName"
string(26) "RelativeName\WithNamespace"
string(12) "AbsoluteName"
string(26) "AbsoluteName\WithNamespace"

See Also

add a note

User Contributed Notes 28 notes

up
205
a dot schaffhirt at sedna-soft dot de
15 years ago
Good news for PHP 5.3 users with namespaced classes:

When you create a subfolder structure matching the namespaces of the containing classes, you will never even have to define an autoloader.

<?php
spl_autoload_extensions
(".php"); // comma-separated list
spl_autoload_register();
?>

It is recommended to use only one extension for all classes. PHP (more exactly spl_autoload) does the rest for you and is even quicker than a semantically equal self-defined autoload function like this one:

<?php
function my_autoload ($pClassName) {
include(
__DIR__ . "/" . $pClassName . ".php");
}
spl_autoload_register("my_autoload");
?>

I compared them with the following setting: There are 10 folders, each having 10 subfolders, each having 10 subfolders, each containing 10 classes.

To load and instantiate these 1000 classes (parameterless no-action constructor), the user-definded autoload function approach took 50ms longer in average than the spl_autoload function in a series of 10 command-line calls for each approach.

I made this benchmark to ensure that I don't recommend something that could be called "nice, but slow" later.

Best regards,
up
24
nemanja
7 years ago
Even when autoloading (SPL) is used, class inheritance does not seem to work. Simply the PHP engine is unable to find parent (inherited) class. PHP 5.6 and 7.0 behave exactly same on this, which beats the purpose of autoloading.

And IMHO it's easy to fix as the autoloader is able to find all first level classes w/o problems, it just needs to follow same path recursively on parents too.

<?php
//Using default SPL autoloader, with namespaces mapping 1:1 to directory structure, with file names being all lowercase.
//This works with first level classes only, for inheritance it does NOT work, it cannot find parent classes.
spl_autoload_register();

//This is ugly but working code if you want to be able to autoload parent classes too.
spl_autoload_register(function ($class){
require_once
__DIR__ . '/' . strtolower(str_replace('\\', '/', $class) . '.php');
});
up
4
abhijeet dot sweden at gmail dot com
2 years ago
Type#1:

<?php

require_once('Second.php');
require_once(
'First.php');

$Second = new Second;
$Second->run_second();

$First = new First;
$First->run_first();

?>

---------------------------------------------------------
Type#2:

<?php

spl_autoload_register
(function($class){
//
require_once($class.'.php');
});

$Second = new Second;
$Second->run_second();

$First = new First;
$First->run_first();

?>
up
10
kuzawinski dot marcin at nospam dot gmail dot com
3 years ago
Since PHP 8.0 spl_autoload_register() will always throw a TypeError on invalid arguments, therefore the second argument `throw` is ignored and a notice will be emitted if it is set to False.
up
30
eyeofmidas at gmail dot com
9 years ago
When switching from using __autoload() to using spl_autoload_register keep in mind that deserialization of the session can trigger class lookups.

This works as expected:
<?php
session_start
();
function
__autoload($class) {
...
}
?>

This will result in "__PHP_Incomplete_Class_Name" errors when using classes deserialized from the session.
<?php
session_start
();
function
customAutoloader($class) {
...
}
spl_autoload_register("customAutoloader");
?>

So you need to make sure the spl_autoload_register is done BEFORE session_start() is called.

CORRECT:
<?php
function customAutoloader($class) {
...
}
spl_autoload_register("customAutoloader");
session_start();
?>
up
44
(delphists) at (apollo) dot (lv)
13 years ago
When using spl_autoload_register() with class methods, it might seem that it can use only public methods, though it can use private/protected methods as well, if registered from inside the class:
<?php

class ClassAutoloader {
public function
__construct() {
spl_autoload_register(array($this, 'loader'));
}
private function
loader($className) {
echo
'Trying to load ', $className, ' via ', __METHOD__, "()\n";
include
$className . '.php';
}
}

$autoloader = new ClassAutoloader();

$obj = new Class1();
$obj = new Class2();

?>

Output:
--------
Trying to load Class1 via ClassAutoloader::loader()
Class1::__construct()
Trying to load Class2 via ClassAutoloader::loader()
Class2::__construct()
up
15
iam at thatguy dot co dot za
9 years ago
<?php

// Example to auto-load class files from multiple directories using the SPL_AUTOLOAD_REGISTER method.
// It auto-loads any file it finds starting with class.<classname>.php (LOWERCASE), eg: class.from.php, class.db.php
spl_autoload_register(function($class_name) {

// Define an array of directories in the order of their priority to iterate through.
$dirs = array(
'project/', // Project specific classes (+Core Overrides)
'classes/', // Core classes example
'tests/', // Unit test classes, if using PHP-Unit
);

// Looping through each directory to load all the class files. It will only require a file once.
// If it finds the same class in a directory later on, IT WILL IGNORE IT! Because of that require once!
foreach( $dirs as $dir ) {
if (
file_exists($dir.'class.'.strtolower($class_name).'.php')) {
require_once(
$dir.'class.'.strtolower($class_name).'.php');
return;
}
}
});
up
20
florent at mediagonale dot com
17 years ago
If your autoload function is a class method, you can call spl_autoload_register with an array specifying the class and the method to run.

* You can use a static method :
<?php

class MyClass {
public static function
autoload($className) {
// ...
}
}

spl_autoload_register(array('MyClass', 'autoload'));
?>

* Or you can use an instance :
<?php
class MyClass {
public function
autoload($className) {
// ...
}
}

$instance = new MyClass();
spl_autoload_register(array($instance, 'autoload'));
?>
up
20
anthon at piwik dot org
14 years ago
Think twice about throwing an exception from a registered autoloader.

If you have multiple autoloaders registered, and one (or more) throws an exception before a later autoloader loads the class, stacked exceptions are thrown (and must be caught) even though the class was loaded successfully.
up
16
a dot schaffhirt at sedna-soft dot de
11 years ago
What I said here previously is only true on Windows. The built-in default autoloader that is registered when you call spl_autoload_register() without any arguments simply adds the qualified class name plus the registered file extension (.php) to each of the include paths and tries to include that file.

Example (on Windows):

include paths:
- "."
- "d:/projects/phplib"

qualified class name to load:
network\http\rest\Resource

Here's what happens:

PHP tries to load
'.\\network\\http\\rest\\Resource.php'
-> file not found

PHP tries to load
'd:/projects/phplib\\network\\http\\rest\\Resource.php'
-> file found and included

Note the slashes and backslashes in the file path. On Windows this works perfectly, but on a Linux machine, the backslashes won't work and additionally the file names are case-sensitive.

That's why on Linux the quick-and-easy way would be to convert these qualified class names to slashes and to lowercase and pass them to the built-in autoloader like so:

<?php
spl_autoload_register
(
function (
$pClassName) {
spl_autoload(strtolower(str_replace("\\", "/", $pClassName)));
}
);
?>

But this means, you have to save all your classes with lowercase file names. Otherwise, if you omit the strtolower call, you have to use the class names exactly as specified by the file name, which can be annoying for class names that are defined with non-straightforward case like e. g. XMLHttpRequest.

I prefer the lowercase approach, because it is easier to use and the file name conversion can be done automatically on deploying.
up
23
Anonymous
14 years ago
Be careful using this function on case sensitive file systems.

<?php
spl_autoload_extensions
('.php');
spl_autoload_register();
?>

I develop on OS X and everything was working fine. But when releasing to my linux server, none of my class files were loading. I had to lowercase all my filenames, because calling a class "DatabaseObject" would try including "databaseobject.php", instead of "DatabaseObject.php"

I think i'll go back to using the slower __autoload() function, just so i can keep my class files readable
up
7
rayro at gmx dot de
14 years ago
It is never a good idea and a unconscienable concept to create the classes in the autoload function via eval.
It should be a nice feature with these Exception, but i think anyone is able to handle it without this method although. Atm i dont realize for what this is good for...

As i might note, class_exists() will ever define the classes u only want to check for existance, and will therefor ever return true:
<?php
function EvalIsEvil($class) {
eval(
'class '.$className.'{}');
}
spl_autoload_register('EvalIsEvil');
if (
class_exists($s="IsMyModuleHere")) {
// this is no module, but get there with eval()...
return new $s();
}
?>
up
5
phil at propcom dot co dot uk
11 years ago
It is important to note that the autoloader will NOT be called if an E_STRICT error triggers the error handler which, in turn, tries to use classes which are not yet loaded.

In this instance, you should manually load classes required by the error handler.
up
4
rnealxp at yahoo dot com
7 years ago
I now utilize spl_autoload_register and there's no turning back. So let me gather here for you what I've learned...
1.) the issue mentioned in these docs about case-sensitivity of filenames (Windows vs Linux/Mac): it only comes into play if you don't provide your own custom function as an argument when calling spl_autoload_register. Your function is to accept a single argument which will be the class name that your code is currently trying to access. I observe that the class name comes in with the same letter-casing as that you are actually using in your code base (mixed-case or not). I am not doing/using namespaces, but as a best practice, and to make your implementation straight-forward and predictable, go with fileName===className (1:1).
2.) I often refactor my code-base's directory structure as my code base morphs. I'm not using namespaces, but even if I were, I would want a decoupling between my namespace hierarchy and my directory structure hierarchy. I like my directory hierarchies to be intuitive for getting to code I want to work with. To save myself from having to manually tell my autoloader the path to each file/class, I cache a couple of arrays in static variables that store just the file/class name in the one array and the folder path to the file in the other. After the cache (static vars) have been set on the first call to my function, it's just a matter of looking up in the filename array. For safety, and to be problem-free, no two php filenames should be identical across all of your directory hierarchy (your namespace)--I favor this practice anyways, and accordingly, I favor unique class names across my single namespace (despite it not yet explicitly defined). I did build in a check in my function to ensure all php file names/classes are unique.
3.) I converted many, many files that once had sets of functions in the global space to *abstract classes* that have private static variables and methods and of course also public static methods. So those sets of functions are now encapsulated in objects, and those objects are now auto-loaded. Simply for this benefit I will never again have a function in the global space other than my auto-loader function and other exceptions such as that.
4.) My auto-loader function uses only built-in php language constructs and operations and has no outside dependencies.
5.) If you utilize the function class_exists() in your codebase somewhere, realize that unless you are passing the second arg as false, you will trigger the autoloader to load that class. I stumbled on this of course. My use-case is that I don't want the class loaded: I only wanted to take some action if the class was being used (in an error-handler method).
6.) If you use the function method_exists(), you will definitely trigger the class to be loaded (which makes sense since you have already decided to drill down to looking for a specific method).
7.) I credit someone else's idea here: I also elected to call an init() method for the class being loaded should it exist. This saves me from having to manually call from the outside, let alone managing how and from where the call should be made. It is so useful to get your object set up and ready to do work in an automated fashion such as this.
8.) as another said, I also use require() and not require_once() as the first is enough to generate an error and if already loaded the function will not have been called.
9.) If for some reason I fail to find a class name in my cached arrays, I knowingly still call require(), passing the class name I had not accounted for in order to generate and reveal the problem (which of course is not anticipated!).
10.) Again, I ensure uniqueness across all class names. If I observe non-uniqueness, I again do a faulty call to require() like this: require('FoundMultiplesOfClassFile.php'); to reveal the problem. (I don't yet, and you likely should not, have any sophisticated error-handler registered so this is as good as anything else to me).
up
2
daniel at amnistechnology dot com
11 years ago
Cleverly - and usefully - I have noticed that (on PHP 5.3 at least) these autoloaders "kick in" even when you call a public static method of an as-yet-unloaded all static class.
up
5
sebastian dot krebs at kingcrunch dot de
14 years ago
It seems, that spl_autoload tests, if the class exists, after calling every registered loader. So it breaks the chain, if the class exists and will not call the other loaders

<?php
function a ($c) {
echo
"a\n";
class
Bla {} // Usually "include 'path/to/file.php';"
}
function
b ($c) {
echo
"b\n";
}
spl_autoload_register('a');
spl_autoload_register('b');

$c = new Bla();
?>
up
1
kakkau at grr dot la
9 years ago
A note on registering autoloading functions with additional parameters.

./alf.home.php
<?php
/*
* class containing an autoloading function alias ALF :)
*/
class ALF {
public function
haaahaaahaaa($class = "ALF", $param = "Melmac") {
echo
"I am ".$class." from ".$param.".\n";
}
}
?>

./kate.melmac.php
<?php
require_once("alf.home.php");
/*
* the normal way is to get ALF
* and register an autoloading function
*/
$alf = new ALF();
spl_autoload_register(array($alf,'haaahaaahaaa'));
$alf->haaahaaahaaa(); // ALF is from Melmac :)
/*
* now lets try to autoload a class
*/
@$kate = new Kate(); // this throws a fatal error because
// Kate is NOT from Melmac :)
?>
I am ALF from Melmac.
I am Kate from Melmac.

./kate.earth.php
<?php
require_once("alf.home.php");
/*
* BUT what if we want to correct Kates origin ?
* How can one pass parameters to an autoloading function
* upon registering?
*
* spl_autoload_register is not suitable for that
* but we can try is to define a callable during registration
*/
spl_autoload_register(function($class){
call_user_func(array(new ALF(),'haaahaaahaaa'), $class, "Earth"); });
/*
* now lets try again to autoload a class
* Kate will still not be found but we corrected her origin :)
*/
@$kate = new Kate(); // Kate is from Earth :)
/*
* NOTE: that you cannot pass $this or another object created
* outside of the callable context using the
* registering way above. therefor you should swap your autoloading
* function to a seperate class as done at the beginning with ALF.
*
* NOTE: you may not able to unregister your autoloading function
* directly as an instance was created in another context
*/
?>
I am Kate from Earth.
up
0
Daniel Klein
2 years ago
If you want to be able to run your PHP script from anywhere without changing to the directory first, use chdir(__DIR__) in the first file you run (not any includes):

<?php
spl_autoload_register
();
chdir(__DIR__);

For
some reason, trying to use namespaced classes from within other namespaced classes fails otherwise.

e.g. Running "php src/main.php" will fail, but "cd src && php main.php" will work.

src/main.php
<?php
spl_autoload_register
();
//chdir(__DIR__); // Uncomment this to make it work from any directory
MyNamespace\MyClass::foo();

src/MyNamespace/MyClass.php
<?php
namespace MyNamespace;

class
MyClass {
public static function
foo(): void {
echo
MyOtherClass::BAR; // This will fail even if MyOtherClass.php is in the right place
}
}

src/MyNamespace/MyOtherClass.php
<?php
namespace MyNamespace;

class
MyOtherClass {
public const
BAR = 'baz';
}
up
1
stanlemon at mac dot com
17 years ago
Editorial note: The appropriate PHP bug that requests behavior this function emulates is http://bugs.php.net/bug.php?id=42823 . This function does NOT work if there has been an array($obj, 'nonStaticMethod') registered in the autoload stack--while the autoload will be removed, it will be re-registered incorrectly.

The spl_autoload_register() method registers functions in its stack in the order that spl_autoload_register() was called, and subsequently if you want an autoload function to override previous autoload functions you will either need to unregister the previous ones or change the order of the autoload stack.

For example, say in your default implementation of an autoload function you throw an exception if the class cannot be found, or perhaps a fatal error. Later on in your code you add a second implementation of an autoload function which will load a library that the previous method would fail on. This will not call the second autoloader method first, but rather will continue to error out on the first method.

As previously mentioned, you can unregister the existing autoloader that errors out, or you can create a mechanism for unregistering and re-registering the autoloaders in the order you want.

Here is a sample/example of how you might consider re-registering autoloaders so that the newest autoloader is called first, and the oldest last:

<?php

// Editorial notes: Small bug and compatibility fixes
// added to the function

function spl_autoload_preregister( $autoload ) {
// No functions currently in the stack.
if ( ($funcs = spl_autoload_functions()) === false ) {
spl_autoload_register($autoload);
} else {
// Unregister existing autoloaders...
$compat =
version_compare(PHP_VERSION, '5.1.2', '<=') &&
version_compare(PHP_VERSION, '5.1.0', '>=');
foreach (
$funcs as $func) {
if (
is_array($func)) {
// :TRICKY: There are some compatibility issues and some
// places where we need to error out
$reflector = new ReflectionMethod($func[0], $func[1]);
if (!
$reflector->isStatic()) {
throw new
Exception('
This function is not compatible
with non-static object methods due to PHP Bug #44144.
'
);
}
// Suprisingly, spl_autoload_register supports the
// Class::staticMethod callback format, although call_user_func doesn't
if ($compat) $func = implode('::', $func);
}
spl_autoload_unregister($func);
}

// Register the new one, thus putting it at the front of the stack...
spl_autoload_register($autoload);

// Now, go back and re-register all of our old ones.
foreach ($funcs as $func) {
spl_autoload_register($func);
}
}
}

?>

Note: I have not tested this for overhead, so I am not 100% sure what the performance implication of the above example are.
up
0
n0mAd at example dot com
6 years ago
If you need to register the function when using namespaces, use the __NAMESPACE__ constant to define the name.

<?php

namespace Foobar;

spl_autoload_register('MyFunction'); // incorrect
spl_autoload_register('\MyFunction');// incorrect
spl_autoload_register(__NAMESPACE__ . '\MyFunction'); // correct

?>
up
0
harvey dot NO_SPAM dot robin at gmail dot com
17 years ago
This function is smart enough not to add the same loader twice. This seems to work for all of the different loader formats. Example:

<?php
class ALoader
{
static function
load($class) { return true; }
}

function
anotherLoader($class) {
return
true;
}

$F = new ALoader;

spl_autoload_register(array('ALoader', 'load'));
spl_autoload_register(array('ALoader', 'load'));
spl_autoload_register(array($F, 'load'));
spl_autoload_register('anotherLoader');
spl_autoload_register('anotherLoader');
var_dump(spl_autoload_functions());

/*
* Results on PHP5.2 CLI, linux.
* array(2) {
* [0]=>
* array(2) {
* [0]=>
* string(7) "ALoader"
* [1]=>
* string(4) "load"
* }
* [1]=>
* string(13) "anotherLoader"
* }
*/
?>
up
-1
hajo-p
10 years ago
if you have a dir-structure like "/abc/def/ghi", your index.php lies in the top directory, but you want to use namespaces starting with "def" or "ghi":

you can switch the namespace root directory of php with e.g. set_include_path(__DIR__ . '/abc') and afterwards define + use your namespaces with the simple spl_autoload_register() function without any arguments supplied.

remember that php handlers "cli" and "cli-server" are special cases.
up
-1
joneschrisan at aol dot com
8 years ago
Looks like on the latest update of debian php passing no params to spl_autoload doesn't work on linux any more.

It is failing to replace the \'s in the namespace with /'s for file paths.
up
-3
Kurd the Great
11 years ago
if(!defined('BASE_PATH')) {
define('BASE_PATH', dirname(__FILE__) . '/');
require BASE_PATH . 'Autoloader.php';
Autoloader::Register();
}

class Autoloader
{
public static function Register() {
return spl_autoload_register(array('Autoloader', 'Load'));
}

public static function Load($strObjectName) {
if(class_exists($strObjectName) === false) {
return false;
}

$strObjectFilePath = BASE_PATH . $strObjectName . '.php';

if((file_exists($strObjectFilePath) === false) || (is_readable($strObjectFilePath) === false)) {
return false;
}

require($strObjectFilePath);
}
}
up
-2
neolium at gmail dot com
9 years ago
This autoload will find every class you call if you put each one in a different file.

It walks into every directory recursivly from the root you specify in the $root var.

You can specify the folders ou don't want to walk in (e.g you won't find any class in a 'view' folder on an MVC project) in the $dir_to_not_look_in array;

spl_autoload_register(function($class) {

$root = 'my/root/path';
$file = $class . '.php';
$dir_to_not_look_in = array($directories, $to, $not, $look, $in);

if(!function_exists('load')) {
function load($dir, $file) {
if(file_exists($dir . '/' . $file)) {
require_once $dir . '/' . $file;
} else {
foreach(scandir($dir) as $value) {
if(is_dir($dir. '/' . $value) && !in_array($value, $dir_to_no_look_in))
load($dir. '/' . $value, $file);
}
}
};
}

load($root, $file);

});
up
-5
nmmm at nmmm dot nu
10 years ago
spl_autoload_register() can be used with include_path.

suppose in current directory we have directory "a", and inside there is directory "test" and inside is test.php :

<?
namespace test;
class test{
function __construct(){
echo "Test created\n";
}
}
?>

then we can use following code to load the class:
<?
ini_set("include_path", "./a/");

spl_autoload_register();

$t = new \test\test();
?>
up
-5
xavier dot bouhours at free dot fr
9 years ago
// Get last class version

if( !function_exists('classAutoLoader') )
{
function classAutoLoader($className)
{
$classFiles = array() ;
$classFile = FALSE ;
$classDir = __DIR__ .'/' ;
// Get all files
$files = scandir( $classDir ) ;
foreach ( $files as $url )
{
// Verifie if file is : Name + class + version + extension
if( is_file($classDir.$url) && preg_match('/([^\.]+)\.class\.([\d\.]+)\.(.+)$/', $url, $m ) )
{
// Verifie finded file
if( $className == $m[1] )
{
// Get previous version or init
$previous = isset( $classFiles[$m[1]] ) ? $classFiles[$m[1]] : 0 ;

// Get last version
if( $previous<$m[2] )
{
$classFiles[ $m[1] ] = $m[2] ; // version
$classFile = $classDir.$url ;
}
}
}
} ;
if( !class_exists($className) ) include( $classFile );
}
}
spl_autoload_register('classAutoLoader') ;
up
-5
sebastian at 34n dot de
11 years ago
You can also use it like this:

> spl_autoload_register ( array( new AutoloaderClass, 'method') );

or in PHP > 5.3:

> spl_autoload_register ( [ new My\Namespace\Autoloader, 'method'] );

On this way you dont have to create a variable, which is used once.
To Top