README

PHP autoload management tools

Wellspring provides simple tools to manage and configure autoloaders in PHP.

Installation

This package requires PHP 8.4 or higher.

Install via Composer:

composer require decodelabs/wellspring

Usage

Wellspring offers an easy to use wrapper around SPL autoload functions, providing extra functionality such as priority ordering and deduplication.

The API is simple and intuitive, allowing you to register autoloaders with a priority level - the higher the priority, the earlier the autoloader will be called. Loaders are grouped by priority but maintain the first-come, first-served order within each group by virtue of leveraging the original order of the SPL autoload functions.

Loaders registered via the built in SPL functions are automatically assigned the Priority::Medium priority, allowing users of Wellspring to easily register other loaders before with Priority::High or after them using Priority::Low.

The registered list of loaders is automatically remapped on the fly when necessary (even when spl_autoload_register() and spl_autoload_unregister() are used directly), ensuring edge-case functionality does not interfere with the intended load order.

use DecodeLabs\Wellspring;
use DecodeLabs\Wellspring\Priority;

spl_autoload_register(function(string $class) {
    // This will get called second
});

Wellspring::register(function(string $class) {
    // This will get called last
}, Priority::Low);

Wellspring::register(function(string $class) {
    // This will get called first
}, Priority::High);

spl_autoload_register(function(string $class) {
    // This will get called third
});

spl_autoload_call('test');

When registered via Wellspring, loaders are wrapped in a Loader instance; this wrapper passes autoload calls directly to the original callback and has a void return type, matching the expected signature of the spl_autoload_register() function.

Error handling

Wellspring does not intercept exceptions thrown by user autoloaders; SPL stops the chain automatically when an exception is thrown, matching existing behaviour with SPL functions.

Deduplication

Wellspring ensures that each autoloader is only registered once, even if the same callable is added directly through SPL. Callable identity covers functions, static methods, instance methods, closures, and invokable objects, matched case-insensitively for class and method names.

If static references (such as ['Class', 'method'] or 'Class::method') are registered multiple times, Wellspring will automatically deduplicate them, ensuring the same loader is not called multiple times for the same class.

Object instances are only deduplicated if they are the same instance, not if they are different instances of the same class as instances are considered unique. This also applies to Closures (both defined as classic anonymous functions and as first class callables such as $this->method(...)) as the context of the closure is considered unique.

Unregistering Loaders

If you need to unregister a loader, you can do so by passing the same callback or loader instance to the unregister() method. This applies whether the callback was registered via Wellspring or directly via spl_autoload_register().

Wellspring::unregister(function(string $class) {
    // This will be unregistered
});

It is also safe to use spl_autoload_unregister() directly to unregister a loader, Wellspring with automatically handle the necessary remapping of the queue the next time a class is loaded.

Debugging

If you need to debug the current state of the autoloader queue, you can use the dump() method to output the current state of the queue.

Wellspring::dump();

This will output a list of all registered loaders in order of priority, including their priority, type and source, keyed by their callback identity:

[
    'ob:Closure(15)' => [
        'callback' => Loader,
        'priority' => Priority::High,
        'type' => CallbackType::Object,
        'source' => Source::Wellspring,
    ],
    'ao:Composer\Autoload\ClassLoader(5)::loadclass' => [
        'callback' => [Composer\Autoload\ClassLoader, loadclass],
        'priority' => Priority::Medium,
        'type' => CallbackType::ObjectArray,
        'source' => Source::SPL,
    ],
    'st:test' => [
        'callback' => Loader,
        'priority' => Priority::Low,
        'type' => CallbackType::String,
        'source' => Source::Wellspring,
    ]
]

You can also query the number of order checks and remaps that have been performed:

Wellspring\QueueHandler::$checks;
Wellspring\QueueHandler::$remaps;

Performance

Wellspring is designed to be performant and efficient, ensuring that managing the autoloader queue does not significantly impact performance. The QueueHandler works in the hot path of the autoloader system and leverages PHP's internal referencing of arrays to minimise memory allocations and churn.

Licensing

Wellspring is licensed under the MIT License. See LICENSE for the full license text.

decodelabs / wellspring

Maintainers

Details