PHPackages                             decodelabs/wellspring - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. decodelabs/wellspring

ActiveLibrary[Utility & Helpers](/categories/utility)

decodelabs/wellspring
=====================

PHP autoload management tools

v0.2.0(8mo ago)020.6k1MITPHPPHP ^8.4CI passing

Since Mar 4Pushed 1mo ago2 watchersCompare

[ Source](https://github.com/decodelabs/wellspring)[ Packagist](https://packagist.org/packages/decodelabs/wellspring)[ RSS](/packages/decodelabs-wellspring/feed)WikiDiscussions develop Synced 1mo ago

READMEChangelog (4)Dependencies (1)Versions (6)Used By (1)

Wellspring
==========

[](#wellspring)

[![PHP from Packagist](https://camo.githubusercontent.com/b7e2b82922d304bf6980755de1fff728e7ba01a011bf516859a77428a74be6cb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6465636f64656c6162732f77656c6c737072696e673f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/wellspring)[![Latest Version](https://camo.githubusercontent.com/c84127e63e5dc199803f84cdedf4bc41475484a87ee755d22259d964c2ad238a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6465636f64656c6162732f77656c6c737072696e672e7376673f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/wellspring)[![Total Downloads](https://camo.githubusercontent.com/06f4095daacb0a76a619cb92dbfee34fd789b628dc443284b613cd2e9c15e50e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6465636f64656c6162732f77656c6c737072696e672e7376673f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/wellspring)[![GitHub Workflow Status](https://camo.githubusercontent.com/63c53190cdcba0a33ae0790bdd10c91a9d9dc54105fa0942a80b5950bf607e83/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6465636f64656c6162732f77656c6c737072696e672f696e746567726174652e796d6c3f6272616e63683d646576656c6f70)](https://github.com/decodelabs/wellspring/actions/workflows/integrate.yml)[![PHPStan](https://camo.githubusercontent.com/e25c14ce011edabdd0fbd2e10415b41cc5d66ed11ef3e5b7edd074c5bdd35a2d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d656e61626c65642d3434434331312e7376673f6c6f6e6743616368653d74727565267374796c653d666c6174)](https://github.com/phpstan/phpstan)[![License](https://camo.githubusercontent.com/5fd5b008955983b06d93543fad04c796abe2b6baf72958d83fe1d6574d6de943/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6465636f64656c6162732f77656c6c737072696e673f7374796c653d666c6174)](https://packagist.org/packages/decodelabs/wellspring)

### PHP autoload management tools

[](#php-autoload-management-tools)

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

---

Installation
------------

[](#installation)

This package requires PHP 8.4 or higher.

Install via Composer:

```
composer require decodelabs/wellspring
```

Usage
-----

[](#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

[](#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
-------------

[](#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

[](#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
---------

[](#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

[](#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
---------

[](#licensing)

Wellspring is licensed under the MIT License. See [LICENSE](./LICENSE) for the full license text.

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance77

Regular maintenance activity

Popularity26

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~202 days

Total

4

Last Release

244d ago

PHP version history (2 changes)v0.1.0PHP ^8.1

v0.1.2PHP ^8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/8a241d64d12b3b5ee94197862ec1ec30b82ed2efa34a0cd7f4c3565a021daddd?d=identicon)[betterthanclay](/maintainers/betterthanclay)

---

Top Contributors

[![betterthanclay](https://avatars.githubusercontent.com/u/1273586?v=4)](https://github.com/betterthanclay "betterthanclay (46 commits)")

---

Tags

autoloadphp

### Embed Badge

![Health badge](/badges/decodelabs-wellspring/health.svg)

```
[![Health](https://phpackages.com/badges/decodelabs-wellspring/health.svg)](https://phpackages.com/packages/decodelabs-wellspring)
```

###  Alternatives

[magepal/link-product

Custom product relation for magento 2

5444.2k](/packages/magepal-link-product)[baraja-core/simple-php-diff

Find the quick difference between two text files in PHP.

1145.0k1](/packages/baraja-core-simple-php-diff)[wsdltophp/package-ews365

Package generated from /var/www/wsdl/services.updated.wsdl using wsdltophp/packagegenerator

164.6k](/packages/wsdltophp-package-ews365)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)