Container

DI Container

Razy includes a full-featured dependency injection container with auto-wiring, scoped/contextual bindings, tags, extenders, resolving hooks, rebind support, and PSR-11 compliance. It manages service lifecycles (transient, singleton, scoped, instance) and provides hierarchical parent/child isolation for the module system.

PSR-11 Compliance
Binding Services
Resolving Services
Auto-Wiring
Contextual Binding
Tagged Bindings
Extenders (Decorator Pattern)
Resolving Hooks
Method Injection (call)
Factory Closures
Rebinding (Hot-Swap)
Parent/Child Container Hierarchy
Framework Integration
Lifecycle Management
Exception Handling
Complete API Reference

PSR-11 Compliance

The Container implements PSR-11 compatible interfaces without requiring psr/container as a Composer dependency. Razy defines its own matching interfaces:


PsrContainerInterface              →get(), has()

  →?→ ContainerInterface            →bind(), singleton(), scoped(), instance(), make(), tag(), ...

        →?→ Container (concrete)

use Razy\Contract\Container\PsrContainerInterface;



// PsrContainerInterface defines:

//   get(string $id): mixed

//   has(string $id): bool



// ContainerInterface extends with:

//   bind(), singleton(), scoped(), instance(), make(),

//   tag(), tagged(), when(), alias(), factory(), ...

Binding Services

Transient Binding

A new instance is created on every make() / get() call:

// Explicit factory

$container->bind(MyService::class, function (Container $c) {

    return new MyService($c->make(Config::class));

});



// Auto-wiring (Container resolves constructor deps automatically)

$container->bind(MyService::class);



// Concrete-to-concrete (must satisfy instanceof / LSP)

$container->bind(LoggerInterface::class, FileLogger::class);

Singleton Binding

A shared instance — created on first access, reused for all subsequent calls:

$container->singleton(DatabasePool::class, function () {

    return new DatabasePool(['host' => 'localhost']);

});



// Auto-wired singleton

$container->singleton(CacheService::class);

Scoped Binding

A request-scoped singleton — shared within a single request scope, cleared between requests via forgetScopedInstances(). Designed for worker mode (Caddy, Swoole, RoadRunner):

$container->scoped(RequestContext::class, function () {

    return new RequestContext($_SERVER);

});



$container->scoped(UserSession::class);



// Between requests in worker mode:

$container->forgetScopedInstances(); // clears scoped caches, not definitions

Lifecycle comparison:


              PHP-FPM (per-request)        Worker Mode (persistent)

              ─────────────────────        ────────────────────────

Transient     New every make()             New every make()

Singleton     Created once, reused         Created once, lives forever

Scoped        →Singleton (same effect)    Created once per request,

                                           cleared by forgetScopedInstances()

Instance      Pre-built object             Pre-built object

Instance Registration

Register an already-existing object directly:

$container->instance(ContainerInterface::class, $container);

$container->instance('config', $configObject);

Conditional Binding

Register only if the abstract is not already bound — prevents accidental overrides:

$container->bindIf(MyService::class, ConcreteImpl::class);

$container->singletonIf(CacheService::class);

$container->scopedIf(RequestContext::class);

Aliases

Map a short name to an existing abstract binding. Alias chains are resolved up to 10 levels deep:

$container->singleton(CacheService::class);

$container->alias('cache', CacheService::class);



$cache = $container->get('cache'); // resolves CacheService singleton

Resolving Services

make() — Resolve with Parameters

// Auto-wired resolution

$service = $container->make(UserRepository::class);



// With explicit constructor parameters

$service = $container->make(UserRepository::class, [

    'tableName' => 'users',

]);

Resolution order in make():


1. Resolve alias chain (up to 10 levels)

2. Return cached singleton/scoped instance (if exists)

3. Delegate to parent container (if no local binding and parent has it)

4. Circular dependency check (throws ContainerException)

5. Fire beforeResolving hooks

6. Build instance (factory closure or auto-wire)

7. Apply extenders (decorator chain)

8. Cache instance (if shared: singleton/scoped)

9. Fire resolving hooks

10. Fire afterResolving hooks

11. Return instance

get() — PSR-11 Resolve

$service = $container->get(UserRepository::class);

// Throws ContainerNotFoundException if not bound

has() — PSR-11 Check

if ($container->has(UserRepository::class)) {

    $repo = $container->get(UserRepository::class);

}

bound() — Local Check Only

// Checks local bindings/instances only (no parent, no auto-wire)

if ($container->bound(MyService::class)) {

    // ...

}

Auto-Wiring

The Container automatically resolves constructor dependencies using PHP reflection. For each constructor parameter, the resolution order is:


1. Explicit $params (by name)

2. Contextual binding (when/needs/give)

3. Global make() resolution (type-hint)

4. Default value

5. Nullable →null

6. Throw ContainerException

class UserService {

    public function __construct(

        private UserRepository $repo,    // Auto-resolved via make()

        private CacheService $cache,     // Auto-resolved via make()

        private string $prefix = 'usr'   // Uses default value

    ) {}

}



// Container resolves UserRepository and CacheService automatically

$service = $container->make(UserService::class);

⚠️ Warning: Circular dependencies are detected and throw a ContainerException.

Contextual Binding

Contextual bindings let you provide different implementations of the same interface depending on which class is consuming it:

use Razy\ContextualBindingBuilder;



// When UserService needs LoggerInterface, give FileLogger

$container->when(UserService::class)

    ->needs(LoggerInterface::class)

    ->give(FileLogger::class);



// When PaymentService needs LoggerInterface, give DatabaseLogger

$container->when(PaymentService::class)

    ->needs(LoggerInterface::class)

    ->give(DatabaseLogger::class);



// With factory closure

$container->when(ReportService::class)

    ->needs(LoggerInterface::class)

    ->give(function (Container $c) {

        return new FileLogger('/var/log/reports.log');

    });

How it works: During auto-wiring, the Container checks contextualBindings[consumer][abstract] before falling back to the global binding. This is resolved per-parameter during constructor injection.

// Direct registration (equivalent to fluent API)

$container->addContextualBinding(

    UserService::class,        // consumer

    LoggerInterface::class,    // abstract needed

    FileLogger::class          // concrete to give

);



// Check if a contextual binding exists

$binding = $container->getContextualBinding(

    UserService::class,

    LoggerInterface::class

); // returns FileLogger::class or null

Tagged Bindings

Group related services under a tag name and resolve them all at once:

// Register services

$container->singleton(FileLogger::class);

$container->singleton(DatabaseLogger::class);

$container->singleton(StderrLogger::class);



// Tag them

$container->tag([

    FileLogger::class,

    DatabaseLogger::class,

    StderrLogger::class,

], 'loggers');



// Resolve all tagged services

$loggers = $container->tagged('loggers');

// Returns [FileLogger, DatabaseLogger, StderrLogger] instances



// Use case: aggregate pattern

class LogAggregator {

    public function __construct(private array $loggers) {}



    public function logToAll(string $message): void {

        foreach ($this->loggers as $logger) {

            $logger->log($message);

        }

    }

}



$container->singleton(LogAggregator::class, function (Container $c) {

    return new LogAggregator($c->tagged('loggers'));

});

Extenders (Decorator Pattern)

Extenders wrap resolved instances with additional behavior. Multiple extenders are applied in registration order:

// Add logging decorator to any CacheService resolution

$container->extend(CacheService::class, function (object $cache, Container $c) {

    return new LoggingCacheDecorator($cache, $c->make(Logger::class));

});



// Add metrics on top

$container->extend(CacheService::class, function (object $cache, Container $c) {

    return new MetricsCacheDecorator($cache);

});



// Resolution: CacheService → LoggingCacheDecorator → MetricsCacheDecorator

$cache = $container->make(CacheService::class);

Note: If extend() is called on a singleton that's already cached, the extender is applied immediately and the cache is updated in-place. Otherwise, the extender is queued for the next resolution.

Resolving Hooks

Three lifecycle hooks fire during resolution. Each supports type-specific (by class name) and global (wildcard *) callbacks:

// Before resolving → fires before the instance is built

$container->beforeResolving(UserService::class, function (string $abstract, Container $c) {

    echo "About to resolve: {$abstract}\n";

});



// During resolving → fires after build + extenders, before afterResolving

$container->resolving(UserService::class, function (object $instance, Container $c) {

    // Inject runtime config, set up listeners, etc.

    $instance->setDebugMode(true);

});



// After resolving → fires last, good for audit or logging

$container->afterResolving(UserService::class, function (object $instance, Container $c) {

    $c->make(Logger::class)->info('Resolved: ' . get_class($instance));

});



// Global hooks (fire for ALL resolutions)

$container->beforeResolving(function (string $abstract, Container $c) {

    // Fires for every make() call

});



$container->resolving(function (object $instance, Container $c) {

    // Post-build hook for every instance

});

Execution order:


beforeResolving (type-specific) →beforeResolving (global *)

    →build() →extenders

        →resolving (type-specific) →resolving (global *)

            →afterResolving (type-specific) →afterResolving (global *)

Method Injection

The call() method invokes any callable with auto-resolved parameters:

// Closure

$result = $container->call(function (UserRepository $repo, CacheService $cache) {

    return $repo->findAll();

});



// Instance method

$result = $container->call([$controller, 'handleRequest']);



// Static method

$result = $container->call([MyService::class, 'staticMethod']);



// Invokable object

$result = $container->call($invokable);



// With explicit overrides

$result = $container->call(function (UserRepository $repo, string $role) {

    return $repo->findByRole($role);

}, ['role' => 'admin']);

Parameter resolution order per argument:


1. Explicit $params (by name)

2. Type-hint resolution via make()

3. Default value

4. Nullable →null

5. Throw ContainerException

Factory Closures

Get a reusable factory closure that produces instances on demand:

$factory = $container->factory(UserService::class);



// Each call creates (or returns cached) instance

$service1 = $factory();

$service2 = $factory();



// Transient binding: $service1 !== $service2

// Singleton binding: $service1 === $service2

Rebinding (Hot-Swap)

Atomically replace a binding at runtime and notify interested parties. Designed for worker mode hot-reload:

// Register a callback when a binding changes

$container->onRebind(CacheService::class, function (string $abstract, ?object $old, Container $c) {

    echo "CacheService was replaced!\n";

    // $old is the previous cached instance (if any)

});



// Replace the binding → fires onRebind callbacks, returns old cached instance

$oldInstance = $container->rebind(CacheService::class, function () {

    return new RedisCacheService();

});



// Track rebind statistics (for worker stability monitoring)

$count = $container->getRebindCount(CacheService::class); // per-abstract count

$total = $container->getTotalRebindCount();                // sum of all

$shouldRestart = $container->exceedsRebindThreshold();     // >= 50 by default



// Configure threshold (PHP class table bloat detection)

$container->setMaxRebindsBeforeRestart(100);

Note: Rebind counts intentionally survive reset() to track cumulative class table bloat across the worker process lifetime. When exceedsRebindThreshold() returns true, a graceful worker restart is recommended.

Parent/Child Container Hierarchy

Razy uses a hierarchical container architecture. Each module receives its own child container that delegates to the Application container (parent) for unresolved bindings:


┌──────────────────────────────────────────┐

→           Application Container            → →Root: core services

│ (ContainerInterface, PluginManager, ...)   │

└──────────────────────────────────────────┘

│Module A →Module B →Module C              │ →Child containers

│Container→Container→Container             │

│         │         │                      │

│Local    →Local    →Local bindings        │

│bindings →bindings →(isolated per module) │

┌──────────────────────────────────────────┐

Resolution priority chain:


1. Instance (pre-built object)

2. Contextual Binding (when/needs/give for the consumer)

3. Local Binding (module's own container)

4. Parent Container (Application container)

5. Auto-wire (reflection-based construction)

Creating child containers:

// No createChild() method → instantiate directly with parent reference

$child = new Container($parentContainer);



// Child inherits parent bindings but can override locally

$child->singleton(MyService::class, CustomImpl::class);



// Resolution: child first → parent fallback

$service = $child->make(SomeService::class);

// If not bound in child, delegates to parent

Module integration (Module::initializeContainer()):

// Inside Module class (framework-internal)

private function initializeContainer(): void

{

    $parentContainer = $this->distributor->getContainer();

    $this->container = new Container($parentContainer);



    // Auto-bind ModuleInfo for this module

    $this->container->bind(ModuleInfo::class, fn() => $this->moduleInfo);



    // Load services from package.php 'services' key

    foreach ($this->package['services'] ?? [] as $abstract => $config) {

        // Register each service binding...

    }

}

Framework Integration

Application Level

The Application creates the root Container and registers core framework services:

$app = new Application();

$container = $app->getContainer();



// Pre-registered services:

$container->get(ContainerInterface::class);  // Container itself

$container->get(PluginManager::class);       // Singleton

Distributor Level

Each Distributor receives the Container and registers itself:

$distributor = $app->getDistributor();

$container = $distributor->getContainer();

Module Level — package.php Services

Define services in your module's package.php to auto-register them in the module's child container:

// package.php

return [

    'name' => 'vendor/my-module',

    'services' => [

        PaymentGateway::class => [

            'type' => 'singleton',

            'concrete' => StripeGateway::class,

        ],

        ReportGenerator::class => [

            'type' => 'transient',

        ],

    ],

];

Controller Level

Controllers access the Container via convenience methods:

class MyController extends Controller

{

    public function __onInit(Agent $agent): bool

    {

        // Resolve a service

        $service = $this->resolve(MyService::class);



        // Check availability

        if ($this->hasService(CacheService::class)) {

            $cache = $this->resolve(CacheService::class);

        }



        return true;

    }

}

Lifecycle Management

// Forget scoped instances between requests (worker mode)

$container->forgetScopedInstances();



// Forget a specific binding

$container->forget(MyService::class);



// Reset everything (bindings, instances, aliases, tags, hooks, extenders)

// Note: rebindCounts are preserved for class-table bloat detection

$container->reset();



// Inspect current bindings

$bindings = $container->getBindings(); // string[] of registered abstract names

Exception Handling

The Container uses PSR-11 compliant exceptions:

| Exception | When | Interface |

| --- | --- | --- |

| ContainerNotFoundException | get() called for an unbound service | NotFoundExceptionInterface |

| ContainerException | Circular dependency, resolution failure, invalid callable | ContainerExceptionInterface |

use Razy\Exception\ContainerException;

use Razy\Exception\ContainerNotFoundException;



try {

    $service = $container->get('unknown.service');

} catch (ContainerNotFoundException $e) {

    // Service not found

} catch (ContainerException $e) {

    // Circular dependency or build failure

}

Complete API Reference

Registration

| Method | Description |

| --- | --- |

| bind(string $abstract, string\|Closure $concrete) | Transient binding |

| bindIf(string $abstract, string\|Closure $concrete) | Bind only if not already bound |

| instance(string $abstract, object $instance) | Pre-built object |

| alias(string $alias, string $abstract) | Alias mapping (chain depth → 10) |

Resolution

| Method | Description |

| --- | --- |

| make(string $abstract, array $params = []): mixed | Primary resolution with optional params |

| get(string $id): mixed | PSR-11 resolve (throws ContainerNotFoundException) |

| has(string $id): bool | PSR-11 check (includes parent) |

| bound(string $abstract): bool | Local-only check |

| factory(string $abstract): Closure | Returns fn() => $this->make($abstract) |

| call(callable\|array $callback, array $params = []): mixed | Method injection |

Contextual Binding

| Method | Description |

| --- | --- |

| when(string $consumer): ContextualBindingBuilder | Start fluent contextual binding |

| addContextualBinding(string $consumer, string $abstract, string\|Closure $concrete) | Direct registration |

Extenders & Hooks

| Method | Description |

| --- | --- |

| extend(string $abstract, Closure $extender) | Decorator: fn(object, Container): object |

| beforeResolving(string\|Closure $abstract, ?Closure $callback = null) | Pre-build hook |

| resolving(string\|Closure $abstract, ?Closure $callback = null) | Post-build hook |

| afterResolving(string\|Closure $abstract, ?Closure $callback = null) | Final hook |

Rebinding

| Method | Description |

| --- | --- |

| rebind(string $abstract, string\|Closure $concrete): ?object | Atomic replace, returns old instance |

| onRebind(string $abstract, Closure $callback) | fn(string, ?object, Container): void |

| getRebindCount(string $abstract): int | Per-abstract rebind count |

| getTotalRebindCount(): int | Sum of all rebind counts |

| exceedsRebindThreshold(): bool | true if total — max (default 50) |

| setMaxRebindsBeforeRestart(int $max) | Configure threshold (min 1) |

Cleanup

| Method | Description |

| --- | --- |

| forgetScopedInstances() | Clear scoped caches (worker mode) |

| forget(string $abstract) | Remove specific binding |

| reset() | Clear everything except rebind counts |

| getBindings(): array | List all bound abstract names |

| getParent(): ?ContainerInterface | Get parent container |

Common Mistakes

| Problem | Cause | Fix |

| --- | --- | --- |

| Circular dependency | A requires B and B requires A | Introduce an interface or lazy factory ($c->factory(...)) |

| Stale data in worker mode | Singleton persists across requests | Use scoped() or call forgetScopedInstances() each cycle |

| Binding works locally but fails elsewhere | Bound in child container, resolved in parent | Bind in the root container or pass the correct scope |

| Interface not resolved | Bound interface has no concrete class | Call $container->singleton(Interface::class, Concrete::class) |

| Rebind threshold exceeded | Too many re-bindings trigger restart guard | Raise setMaxRebindsBeforeRestart() or fix redundant bindings |

Decision Guide — Lifecycle Types

| --- | --- | --- | --- |

Container

DI Container

Table of Contents

PSR-11 Compliance

Binding Services

Transient Binding

Singleton Binding

Scoped Binding

Instance Registration

Conditional Binding

Aliases

Resolving Services

make() — Resolve with Parameters

get() — PSR-11 Resolve

has() — PSR-11 Check

bound() — Local Check Only

Auto-Wiring

Contextual Binding

Tagged Bindings

Extenders (Decorator Pattern)

Resolving Hooks

Method Injection

Factory Closures

Rebinding (Hot-Swap)

Parent/Child Container Hierarchy

Framework Integration

Application Level

Distributor Level

Module Level — package.php Services

Controller Level

Lifecycle Management

Exception Handling

Complete API Reference

Registration

Resolution

Tags

Contextual Binding

Extenders & Hooks

Rebinding

Cleanup

Common Mistakes

Decision Guide — Lifecycle Types

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!