hierone/injector

A powerful dependency injection container with TOML configuration support and advanced binding features

v1.0.1 2025-10-09 06:07 UTC

Requires

• php: >=8.2
• hierone/toml: ^1.0
• psr/container: ^2.0

Requires (Dev)

• phpunit/phpunit: ^10.4

MIT

• Jade Phyressi

• container
• di
• ioc
• dependency-injection
• toml
• hierone
• contextual-binding

README

A modern, high-performance dependency injection container for PHP 8.2+ with advanced features like contextual binding, service tagging, and container compilation.

Features

• 🚀 Zero-config autowiring - Automatic dependency resolution
• 🎯 Contextual binding - Different implementations for different contexts
• 🏷️ Service tagging - Group and inject collections of services
• ⚡ Container compilation - Optimized performance for production
• 🔧 Attribute-based configuration - Modern PHP 8+ attributes
• 📁 Multi-format parameters - TOML, JSON, and PHP configuration files
• 📦 PSR-11 compliant - Standard container interface

Installation

composer require hierone/injector

Quick Start

use Hierone\Component\Injector\Container;

$container = new Container();

// Automatic dependency injection
class UserService {
    public function __construct(
        private DatabaseInterface $db,
        private LoggerInterface $logger
    ) {}
}

$userService = $container->get(UserService::class);

Basic Usage

Service Registration

// Bind interface to implementation
$container->bind(DatabaseInterface::class, MySQLDatabase::class);

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

// Register with factory
$container->bind(ApiClient::class, function($container) {
    return new ApiClient($container->getParameter('api.key'));
});

Attribute Configuration

use Hierone\Component\Injector\Attribute\{Service, Inject, Parameter, Tag};

#[Service(singleton: true, tags: ['processor'])]
class DataProcessor {
    public function __construct(
        #[Parameter('batch.size')] private int $batchSize,
        #[Inject('logger')] private LoggerInterface $logger
    ) {}
}

Contextual Binding

// Different database for different services
$container->when(ReportService::class)
    ->needs(DatabaseInterface::class)
    ->give(ReportDatabase::class);

$container->when(UserService::class)
    ->needs(DatabaseInterface::class)
    ->give(UserDatabase::class);

Service Tagging

// Tag services
$container->tag([EmailHandler::class, SmsHandler::class], 'notification');

// Inject all tagged services
class NotificationManager {
    public function __construct(
        #[Tag('notification')] private iterable $handlers
    ) {}
}

Parameter Configuration

// Load from TOML file
$container->loadParameters('config.toml');

// Set individual parameters
$container->setParameter('database.host', 'localhost');
$container->setParameter('cache.ttl', 3600);

// Use in services
class DatabaseService {
    public function __construct(
        #[Parameter('database.host')] private string $host
    ) {}
}

Container Compilation

For production performance, compile the container:

use Hierone\Component\Injector\Dumper\PhpDumper;

$dumper = new PhpDumper($container);
$compiled = $dumper->dump(['class' => 'CompiledContainer']);

file_put_contents('compiled_container.php', $compiled);

// Use compiled container
require 'compiled_container.php';
$container = new CompiledContainer();

Configuration Formats

TOML Configuration

[database]
host = "localhost"
port = 3306

[cache]
driver = "redis"
ttl = 3600

JSON Configuration

{
  "database": {
    "host": "localhost",
    "port": 3306
  },
  "cache": {
    "driver": "redis",
    "ttl": 3600
  }
}

Requirements

• PHP 8.2 or higher
• PSR Container 2.0

License

MIT License. See LICENSE for details.