huynt57/laravel-singletonize

Laravel package to default container resolution to singleton

dev-main 2025-10-22 07:17 UTC

Requires

• php: >=8.1
• illuminate/container: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0

MIT

README

Laravel Singletonize is a lightweight package that switches the default behaviour of the Laravel service container to resolve dependencies as singletons. Once installed, every concrete that is resolved without an explicit binding will automatically be cached and reused by the container.

Compatibility

Laravel Singletonize is tested against Laravel 10.x, 11.x, and 12.x applications.

Why this package?

Laravel's automatic resolution relies heavily on reflection to discover constructor dependencies on every request. For large codebases with many services, repeatedly reflecting on types becomes expensive and increases bootstrapping time. By promoting implicitly resolved services to singletons, the package ensures the reflection work is only performed once per service lifecycle, which can noticeably improve application performance.

Installation

composer require huynt57/laravel-singletonize

The service provider is auto-discovered through Laravel's package discovery. If you prefer to register it manually, add the provider to your config/app.php file:

'providers' => [
    Huynt57\LaravelSingletonize\SingletonizeServiceProvider::class,
],

Configuration

Publish the configuration file to toggle the behaviour at runtime:

php artisan vendor:publish --tag=config --provider="Huynt57\\LaravelSingletonize\\SingletonizeServiceProvider"

The published file config/laravel-singletonize.php contains a single option:

return [
    'enabled' => true,
];

Set enabled to false to restore Laravel's default behaviour of creating a fresh instance on every resolution unless it has been explicitly registered as a singleton.

How it works

The package listens to the container's resolution lifecycle events. When a type is resolved for the first time, the resolved instance is cached and immediately re-registered in the container. Subsequent resolutions therefore reuse the same instance, effectively promoting every binding (including implicit bindings) to a singleton while still respecting contextual parameters.

Parameterised resolutions continue to return fresh instances, ensuring factories and runtime arguments behave as expected.

Testing

A lightweight test harness is provided in tests/run.php. Execute the suite with:

composer test

The tests cover:

• Implicit binding reuse for classes without manual registration.
• Nested dependency reuse.
• Parameterised resolution exclusions.
• Closure bindings.
• Configuration toggling.