gacela-project/container

A minimalistic container dependency resolver

1.1.1 2026-07-26 20:58 UTC

Requires

• php: >=8.3
• psr/container: ^1.1 || ^2.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.75
• infection/infection: ^0.31
• phpbench/phpbench: ^1.4
• phpstan/phpstan: ^2.2
• phpunit/phpunit: ^12.5
• psalm/plugin-phpunit: ^0.19
• symfony/var-dumper: ^6.4 || ^7.0
• vimeo/psalm: ^6.16

MIT

• Jose M. Valera Reales
• Jesus Valera Reales

• container
• php
• resolver
• gacela

Published on Packagist.org on 2026-07-26 20:59 UTC

README

A minimalistic, PSR-11 compliant dependency injection container with automatic constructor injection and zero configuration.

Features

• 🚀 Zero Configuration: Automatic constructor injection without verbose setup
• 🔄 Circular Dependency Detection: Clear error messages when dependencies form a loop
• 📦 PSR-11 Compliant: Standard container interface for interoperability
• ⚡ Performance Optimized: Built-in caching, warmup, and a compiled cache that skips reflection
• 🧩 Fluent Registration: Register bindings after construction with bind() and singleton()
• 🎁 Typed Resolution: make() returns a typed instance; getOrFail() never returns null
• 🔍 Introspection: Debug and inspect container state easily
• 🎯 Type Safe: Requires type hints for reliable dependency resolution
• 🏷️ PHP 8 Attributes: Declarative configuration with #[Inject], #[Singleton], and #[Factory]

Installation

composer require gacela-project/container

Requires PHP >= 8.3.

Hello World

use Gacela\Container\Container;

class Greeter {
    public function __construct(private Clock $clock) {}

    public function greet(): string {
        return 'Hello World at ' . $this->clock->now();
    }
}

class Clock {
    public function now(): string {
        return date('H:i:s');
    }
}

// Zero configuration — dependencies are auto-wired from type hints
$container = new Container();
$greeter = $container->make(Greeter::class);

echo $greeter->greet();

Need interfaces, singletons, attributes, or a compiled cache? See the docs below.

Documentation

Guide	What's inside
Getting Started	Installation, basic usage, how resolution works
Bindings & Registration	Constructor bindings, bind()/singleton(), contextual bindings, aliasing
Resolving Services	get(), make(), getOrFail(), resolve(), transient vs. shared
PHP 8 Attributes	#[Inject], #[Singleton], #[Factory]
Managing Services	Factories, extending, protecting closures, introspection
Performance & Compilation	warmUp(), compiled container cache
Cookbook	Recipes: testing, config, plugins, decorating, debugging
Error Handling	Every exception, what causes it, how to fix it
Best Practices	Recommended patterns
API Reference	Full method, static, and attribute reference
Backward Compatibility	What semver covers here, and what it does not
Upgrade Guide	Migrating from 0.10.0 to 1.0.0

Real-World Example

See how it's used in the Gacela Framework.

Testing

composer test          # Run tests
composer quality       # Run static analysis
composer test-coverage # Generate coverage report

License

MIT License. See LICENSE file for details.