PHP Autoloader (PAL)

PHP Autoloader (PAL) is a single-file PHP implementation of the autoloading mechanism for PHP with the goal to simplify autoloading PHP source files from a given directory path.

Features

• Autoload an existing PHP source directory without the need of using an autoloader file
• Generate an autoloader as a PHP code or as an array for programmatic purposes
• Extremely simple to use

Requirements

• PHP 8.3 or higher
• The tokenizer extension enabled (usually enabled by default)
• The SPL extension enabled (usually enabled by default)

Usage

PAL can be used simply by including/requiring the Autoloader.php file and calling it's public methods, additionally you can use the Makefile to copy over the Autoloader.php file to the target directory as pal.php file or build a pal.phar file for easier distribution.

You may also simply require pal remotely using one of the official repositories:

# Github
require 'https://raw.githubusercontent.com/nosial/pal/refs/heads/master/src/pal/Autoloader.php';

# N64
require 'https://git.n64.cc/Nosial/pal/raw/branch/master/src/pal/Autoloader.php';

# Codeberg
require 'https://codeberg.org/Nosial/pal/raw/branch/master/src/pal/Autoloader.php';

Note: Requiring remote files is not recommended for production use, it is better to download the file and include it, additionally for this feature to work the allow_url_fopen setting must be enabled in your php.ini.

Autoloading a directory

PAL expects a directory where the PHP source files are located, it will then scan the directory recursively and register an autoloader for the found PHP source files. The given directory can contain multiple different namespaces and classes, pal is designed to handle most common use cases.

require 'pal.php';
\pal\Autoloader::autoload('/example/src');

Additionally, a public method autoload is available which can be used to autoload multiple directories, this is an alias for calling \pal\Autoloader::autoload

require 'pal.php';
use function pal\autoload;
autoload('/example/src');

This method also accepts options to adjust the autoloading behavior, for example to exclude certain directories.

require 'pal.php';
\pal\Autoloader::autoload('/example/src', [
    'extensions' => ['php'], // only include files with .php extension
    'exclude' => ['tests', 'vendor'], // exclude directories named tests or vendor
    'case_sensitive' => false, // make class name matching case insensitive
    'follow_symlinks' => true, // follow symbolic links when scanning directories
    'prepend' => false, // prepend the autoloader to the autoload stack, default: false (append)
    'include_static' => false, // include static php files that do not contain any classes or interfaces, default: true
]);

Generating an autoloader

PAL can also generate an autoloader as a PHP code or as an array for programmatic purposes. This can be useful if you want to generate an autoloader once and then include it in your project which can be faster than scanning the directory on every request.

require 'pal.php';
$autoloaderCode = \pal\Autoloader::generateAutoloader('/example/src');
// or
$autoloaderArray = \pal\Autoloader::generateAutoloaderArray('/example/src');

And a public method generate_autoloader is also available which can be used to generate an autoloader for multiple directories, this is an alias for calling \pal\Autoloader::generateAutoloader

require 'pal.php';
use function \pal\generate_autoloader;
$autoloaderCode = generate_autoloader('/example/src');
// or
use function \pal\generate_autoloader_array;
$autoloaderArray = generate_autoloader_array('/example/src');

Similarly to the autoload method, the generateAutoloader and generateAutoloaderArray methods also accept options to adjust the autoloader generation behavior.

require 'pal.php';
$autoloaderCode = \pal\Autoloader::generateAutoloader('/example/src', [
    'extensions' => ['php'], // only include files with .php extension
    'exclude' => ['tests', 'vendor'], // exclude directories named tests or vendor
    'case_sensitive' => false, // make class name matching case insensitive
    'follow_symlinks' => true, // follow symbolic links when scanning directories
    'prepend' => false, // prepend the autoloader to the autoload stack, default: false (append)
    'relative' => true, // use relative paths in the generated autoloader, default: true,
    'include_static' => false, // include static php files that do not contain any classes or interfaces, default: true
    'base_directory' => '/example', // base directory to use when using relative paths, default: the given directory
    'post_definition' => null, // PHP code to append after the autoloader definition, default: null
    'pre_definition' => null, // PHP code to prepend before the autoloader definition, default: null
]);

The generated autoloader code can be saved as a PHP file and included in your project without requiring the pal.php file.

file_put_contents('/example/autoload.php', $autoloaderCode);
require '/example/autoload.php';

Management Methods

PAL also provides some management methods to interact with the autoloader after it has been registered.

• getRegisteredLoaders(): Returns an array of all registered autoloaders.
• clearCache(): Clears the internal cache of the autoloader.
• unregisterAll(): Unregisters all autoloaders that have been registered by PAL.

Building

To build distribution files:

# Build pal.php (copy of Autoloader.php)
make build

# Build pal.phar (PHAR archive)
make phar

# Build both
make all

# Clean build artifacts
make clean

License

This project is licensed under the MIT License - see the LICENSE file for details.