This contains a simple, zero dependency autoloader class for use in PHP 7.0+ projects. It is very simple to configure and use, and fully supports PHP's case-insensitive namespacing.
The autoloader implements two strategies to find classes. These are namespace mapping, and filesystem lookups. Namespace mapping consists of configuring a mapping for a namespace to a directory in the filesystem. The autoloder will then find the best match for a class in the list of mappings and check the filesystem to see if the class exists at that location. If the namespace mapping failes, then the autoloader will search the filesystem for the namespaced class from the configured root directory.
For example, we have a class example\Loader\MyClass
to be loaded. In the namespace map, we have configured that the example
namespace should be mapped to src/
. Thus, the autoloader namespace mapper will look for src/Loader/MyClass.php
. However, if that does not exist, the namespace mapping will fail, we will fall back to the filesystem loader and will look for example/Loader/MyClass.php
.
Now let's say that we are looking for example\Loader\MyClass
and have configured the example
namespace to be loaded from the src/
directory. We have also configured example\Loader
to be loaded from loader/
directory (outside the src/
dirctory). The namespace mapper will no longer attempt to load from src/Loader/MyClass.php
, and will only attempt to load from loader/MyClass.php
. This is because the namespace mapper only attempts to load the best match.
The first step is to instantiate the autoloader. The constructor takes the following 3 parameters:
- Filesystem Root
- Namespace Prefix (optional)
- Namespace Map (optional)
This specifies the root directory under which the autoloader will search for files.
The Namespace Prefix specifies the namespace under which all autoloaded classes are included. If the autoloader is configured
The Namespace Map is a 2D array of namespaces mapped to one or more directories. An initial 2D array may be passed to the constructor, and additional namespaces may be loaded after. The namespace map array must follow this format:
[
'\\' => [
'rootNamespace/',
'alternateDirectory/',
],
'\\namespace1' => [
'directory1a/',
'directory1b/',
'directory1c/',
],
'\\namespace1\\subNS' => [
'directory2a/subDirectory/',
],
]
NOTE the leading backslashes, and the trailing directory slashes. This is the required format for the autoloader.
To use the autoloader, simply instantiate it with the necessary parameters (as above) and call register()
, then you are ready!
<?php
use shanept\Autoloader;
$directory = __DIR__;
$prefix = 'shanept\MyProject';
$mapping = [
'\\' => 'src/'
];
$autoloader = new Autoloader($directory, $prefix, $mapping);
$autoloader->register(); // Now we are good to go!
// This class will be autoloaded from src/MyClass.php
$class = new shanept\MyProject\MyClass();
// You can register more namespaces
$newDirectories = [
'src/sub1',
'src/sub2',
'src/sub3',
];
$autoloader->registerNamespace('\\NewNS', $newDirectories);
// This is loaded from src/sub(1 or 2 or 3)/AnotherClass.php
$newClass = new shanept\MyProject\NewNS\AnotherClass();
The autoloader additionally supports adding new namespaces after instantiation. This may be achieved with a call to registerNamespace()
. The function takes 2 parameters, as follows:
- The namespace
- The list of directories
The format of these parameters is as above for the Namespace Map, where the first parameter becomes the array key, and the list of directories becomes the second dimension/value.
For example:
<?php
$autoloader->registerNamespace('\\myNS', [
'dir1/',
'dir2/',
]);
// This generates the following namespace map:
[
'\\myNS' => [
'dir1/',
'dir2/',
]
]