From c36f2b95e4d4c762f4f4d4b98720fe2c1d7b6a49 Mon Sep 17 00:00:00 2001 From: Serge Kvashnin <75180587+serge-kvashnin@users.noreply.github.com> Date: Sun, 26 May 2024 13:24:26 +0200 Subject: [PATCH] Update `README.md`. --- README.md | 97 ++++++++++++++++++++++++++----------------------------- 1 file changed, 46 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 26fce15..c6ce9b5 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,55 @@ # Container -Simplify your application structure with a minimalist yet powerful PHP dependency injection container. +Simple yet powerful DI container for PHP, with PSR-11 compliance and easy configuration. -> [!WARNING] +> [!IMPORTANT] > This library is under active development and is not yet at version `1.0`. While some features or implementation details > may change in future updates, the core functionality adheres to the PSR-11 container interface, ensuring compatibility > with other PSR-11 compliant components. -The more stars this repo gets, the faster v1 arrives! 😉 - -## Features - -* **Simple Definitions**: Easily define objects, values, environment variables, and more with a clean configuration. -* **Constructor and Factory Injection**: Automatically resolve dependencies through constructor or static factory method - injection. -* **Method Calls**: Configure post-creation method calls on your objects for additional setup. -* **Type Hinting and Attributes**: Use type hints and attributes for clear dependency definitions. +## Why Choose This Container? + +### Simplicity Empowers Maintainability + +Complex tools can quickly become a burden. We believe in the power of simplicity to make your code easier to understand, +debug, and adapt over time. This library avoids unnecessary complexity, focusing on features that offer real value +without sacrificing performance. + +### Key Benefits + +- **Blazing Fast**: Optimized for performance in production environments. +- **Framework Agnostic**: Integrates seamlessly with any project using the PSR-11 container interface. +- **Explicit Over Implicit**: Prioritizes explicit, readable configuration over hidden "magic", making your code easier to maintain. +- **Lightweight**: A minimal footprint keeps your project lean and efficient. +- **Compilation Support**: Optimizes performance further with built-in compilation, including anonymous functions. +- **Autowiring**: Simplify your code with automatic dependency resolution, available even after compilation. +- **Zero-Config Option**: Get started quickly with sensible defaults, no configuration required. +- **Circular Dependency Guard**: Automatically detects and helps you resolve circular dependencies. + +### What's Not Included (and Why) + +This library intentionally omits certain features to prioritize simplicity, maintainability, and performance: + +- **No Property Injection**: We encourage using constructor or method injection for greater clarity and testability. If + dynamic configuration is needed, consider using anonymous functions within the container definition. +- **No Proxies/Lazy Loading**: These mechanisms often mask underlying design issues. Instead, focus on optimizing your + code's structure and dependencies for better performance. +- **No "Prototype" Scope**: This library acts as a service container, ensuring consistent object instances. If you need a + factory pattern, create a factory and register it in the container. +- **No Wildcard Definitions**: Wildcard definitions introduce implicit behavior that can become difficult to manage as + your project grows. We prioritize explicit, readable configurations. +- **No Directory Loading**: Similar to wildcard definitions, directory loading can lead to implicit behavior and + potential conflicts. +- **No `#[Service]` Attributes**: Explicitly defining services in your configuration makes them easier to locate, + understand, and manage. This approach also improves performance as there's no need to scan directories for service + attributes. +- **No Expression Language**: Closures provide enough flexibility for most use cases without introducing unnecessary + complexity. +- **No Tagging**: Tagging can obscure dependencies. Instead, focus on defining explicit relationships between services. + +These choices are made in order to keep the library lean, focused, and easy to understand. By avoiding features +that could introduce unnecessary complexity or ambiguity, we aim to empower you to write cleaner, more maintainable +code. ## Installation @@ -23,43 +57,4 @@ The more stars this repo gets, the faster v1 arrives! 😉 composer require norvica/container ``` -## Usage - -```php -// configuration.php - -use Norvica\Container\Definition\Env; -use Norvica\Container\Definition\Ref; -use function Norvica\Container\env; -use function Norvica\Container\obj; -use function Norvica\Container\ref; -use function Norvica\Container\val; - -return [ - 'a' => 'foo', // scalar value, same as 'a' => val('foo') - 'b' => env('MATH_PI')->float(), // can be also type-casted to int, and bool - 'c' => obj(C::class), // will be instantiated using constructor with no parameters passed - 'd' => obj(D::class, a: ref('a')), // named parameters will be passed to the constructor - 'e' => obj(E::create(...), a: env('MATH_PI', default: 3.14)->float(), b: 'bar'), // named parameters will be passed to the static factory method - 'f' => static function ( - #[Ref('c')] C $c, - #[Env('MATH_PI', type: 'float')] float $b, - ) { - return new F($c, $b); - }, - 'g' => obj(G::class)->call('setA', ref('a')), // create class G and call `setA` - 'h' => obj([ref('c'), 'createH'], b: ref('b')), // use service 'c' method 'createH' with parameter 'b' -]; -``` - -```php -$configurator = new Configurator(); -$configurator->load(__DIR__ . '//configuration.php'); -$configurator->load(__DIR__ . '//configuration.dev.php'); // your additional configuration for specific environment - -$container = $configurator->container(); - -// access your services: -$serviceC = $container->get('c'); -$serviceG = $container->get('g'); -``` +Read more on [https://validation.norvica.dev](https://container.norvica.dev)