README

描述

Calgamo/Di 是一个类似Pimple风格的依赖注入（DI）容器库。

Pimple

特性

• Pimple风格API
• 懒加载以提高性能
• 多容器构建器
• 保护或限制组件
• 可缓存
• 动态代码生成以启动
• 依赖注入
  • 自动装配
  • 构造函数、setter、字段注入
  • 作用域：单例/原型
  • 自定义注解
    • @Inject
    • @Scope
    • @Singleton
    • @Named
    • @Prototype

要求

PHP 7.1 或更高版本

安装 calgamo/di

推荐通过Composer 安装 calgamo/di。

composer require calgamo/di

安装后，您需要要求 Composer 的自动加载器

require 'vendor/autoload.php';

用法

1. 构建容器

容器可以通过构建器类或直接创建。您可以根据喜好选择容器创建方式。
有几种容器构建方法

• 简单（无容器构建器）
• 启动容器构建器
• 编译容器构建器
• 模块化容器构建器
• 缓存编译容器构建器

简单（无容器构建器）

您可以在没有任何内置容器构建器的情况下构建容器。
这种方法简单且最快，但如果使用很多组件，容器初始化代码会变得复杂。

use Calgamo\Di\Container;
use Sample\Person;
 
$container = Container();
$container['david'] = function(Container $c){
   return new Person('David Smith', 24, 179.2, function($target){ return 'throws '.$target.'.'; });
};
 
$david = $container['david'];
$david->sayHello();        // David Smith says "Hello! My name is David Smith. I am 24 years old."

启动容器构建器

启动容器构建器将通过回调函数（启动）中编写的代码设置容器。这种方法非常快，但可能有些冗余。

use Calgamo\Di\Container;
use Calgamo\Di\BootstrapContainerBuilder;
use Sample\Person;
  
$bootstrap = function(Container $c){
       $c['david'] = function(Container $c){
           return new Person('David Smith', 24, 179.2, function($target){ return 'throws '.$target.'.'; });
       };
   };
$bulder = new BootstrapContainerBuilder($bootstrap);
$container = $bulder->build();
  
$david = $container['david'];
$david->sayHello();        // David Smith says "Hello! My name is David Smith. I am 24 years old."

编译容器构建器

编译容器构建器将通过配置文件（支持 .json/.yml/.php）设置容器。此容器构建器在缓存目录中动态生成启动代码，因此第二次激活容器的启动时间将大大减少。

sample.php

use Calgamo\Di\CompilerContainerBuilder;
use Calgamo\Config\Util\ConfigFileUtil;
  
$config = ConfigFileUtil::loadConfigFromFile('components.json');
$container = (new CompilerContainerBuilder($config))->build();
  
$david = $container['david'];
$david->sayHello();        // David Smith says "Hello! My name is David Smith. I am 24 years old."

components.json

{
  "compiler": {
    "vendor_dir": "../vendor",
    "autoloaders": [
      "../sample_autoloader2.php"
    ]
  },
  
  "cache": {
    "root": "../cache",
    "filename": "demo_di"
  },
 
  "components": [
    {
      "id": "david",
      "type": "object",
      "class_name": "Sample\\Person",
      "injections": [
        {
          "new": [ "David Smith", "@int: 24", "@float: 179.2", "@func: function($target){ return 'throws '.$target.'.'; }" ]
        }
      ]
    }
  ]
}

@ 指令

如上述配置文件（components.json），您可以在组件配置文件中使用 '@xxx' 指令。
以下有一些 '@xxx' 指令。

模块化容器构建器

模块化容器构建器通过安装"容器模块"来设置容器。容器模块是一组容器初始化代码。
BootstrapContainerBuilder只提供一组初始化代码，但ModularContainerBuilder如果需要可以接受多个模块。

use Calgamo\Di\Container;
use Calgamo\Di\ModularContainerBuilder;
use Calgamo\Di\ContainerModuleInterface;
use Sample\Person;
 
class DavidModule implements ContainerModuleInterface
{
    public function install(Container $container)
    {
        $container['david'] = function(){
           return new Person('David Smith', 24, 179.2, function($target){ return 'throws '.$target.'.'; });
        };
    }
}
 
$builder = new ModularContainerBuilder([ new DavidModule() ]);
$container = $builder->build();
 
$david = $container['david'];
$david->sayHello();        // David Smith says "Hello! My name is David Smith. I am 24 years old."

2.使用容器

get

// get service
$service = $container['my-service'];
 
// do something
$service->doSomething();

set/unset

您可以使用相同的方式将实例或值设置为容器中。您还可以设置用于生成实例的工厂代码或用于延迟创建的常量值。

// set object
$container['my-favorite-fruits'] = new MyService();
 
// set object factory(lazy creation)
$container['my-service'] = function(){
    return new MyService();
};
  
// set constant value
$container['my-favorite-fruits'] = [ 'apple', 'banana' ];
  
// set constant value factory(lazy creation)
$container['my-service'] = function(){
    return [ 'apple', 'banana' ];
};
 
// unset entry
unset($container['my-favorite-fruits']);

slot

槽位是关于容器组件的信息。您可以通过槽位对象锁定或限制组件。

// get slot object
$slot = $contianer->slot('something');
 
// lock the slot(in this case, 'something' slot will be locked)
$slot->lock();
 
// type restriction
$slot->mustBeTypeOf('array');
 
// instance-of restriction
$slot->mustBeInstanceOf('MyServiceInterface');

提示

每次访问都获取新实例

默认情况下，容器在第二次访问后返回现有对象。但您可以通过调用Container#newInstance()方法获取每次访问的新对象。

$cart = $container['cart'];
echo 'count:' . $cart->countItems();   // count: 0
$cart->addItem('apple');
echo 'count:' . $cart->countItems();   // count: 1
 
$cart = $container['cart'];
echo 'count:' . $cart->countItems();   // count: 1
 
$cart = $container->newInstance('cart');
echo 'count:' . $cart->countItems();   // count: 0

保护组件

您可以通过使用Slot#lock()方法来保护组件。

$container['cart'] = new MyCart();
 
// lock slot
$container->slot('cart')->lock();
 
// this will fail becasue the slot is locked
$container['cart'] = new AnotherCart();     // throws SlotIsLockedException

限制组件类型

您可以通过使用Slot#mustBeTypeOf()方法来限制组件类型。

$container['something'] = new MyCart();
 
// restrict slot to array value
$container->slot('something')->mustBeTypeOf('array');
 
// this will fail because AnotherCart is not array
$container['something'] = new AnotherCart();     // throws SlotTypeRestrictionViolationException
 
// array value can be set
$container['something'] = [ 'apple', 'banana' ];

限制组件类或接口

您可以通过使用Slot#mustBeInstanceOf()方法来限制组件类或接口。

$container['something'] = new MyCart();
 
// restrict slot to array value
$container->slot('something')->mustBeInstanceOf('MyServiceInterface');
 
// this will fail because AnotherCart does not implement MyServiceInterface
$container['something'] = new AnotherCart();     // throws SlotInstanceOfRestrictionViolationException
 
// interface implemented instance can be set in this slot
$container['something'] = new MyService;        // class MyService implements MyServiceInterface

扩展组件

您可以通过使用Container#extend()方法来扩展组件。

// register my service
$container['my_service'] = new MyService();
 
// extend my serice(set max item count)
$container->extend('my_service', function($my_service) {
    $my_service->setMaxItems(10);
});

echo 'max: ' . $container['my_service']->getMaxItems();       // max: 10
 
// register array
$container['my_favorite_fruits'] = ['apple'];
 
// add banana to my favorites array
$container->extend('my_favorite_fruits', function(&$favorites) {
    $favorites[] = 'banana';
});

echo implode(', ',$container['my_favorite_fruits']);     // apple, banana

编译器配置文件格式 & 参数

编译器配置文件可以写成json、YAML和PHP格式。所有参数必须以数组元素开始。

组件配置文件：json格式示例

{
  "compiler": {
    "vendor_dir": "../vendor",
    "autoloaders": [
      "../sample_autoloader2.php"
    ]
  },
  
  "cache": {
    "root": "../cache",
    "filename": "demo_di"
  },
 
  "slots": [
    {
      "id": "david",
      "type": "object",
      "instanceOf": "\\Sample\\PersonInterface",
      "locked": true
    }
  ],
 
  "components": [
    {
      "id": "david",
      "type": "object",
      "class_name": "Sample\\Person",
      "injections": [
        {
          "new": [ "David Smith", "@int: 24", "@float: 179.2", "@func: function($target){ return 'throws '.$target.'.'; }" ]
        }
      ]
    }
  ]
}

组件配置文件：YAML格式示例

compiler:
  vendor_dir: "../vendor"
  autoloaders:
      "../sample_autoloader2.php"
  
cache:
  root: "../cache",
  filename: demo_di

slots:
  - id: david,
    type: object,
    instanceOf: \Sample\PersonInterface,
    locked: true

components:
  - id: david,
    type: object,
    class_name: Sample\Person,
    injections": 
    new: 
      - "David Smith"
      - "@int: 24"
      - "@float: 179.2"
      - "@func: function($target){ return 'throws '.$target.'.'; }"

组件配置文件：PHP格式示例

<?php
return [
    'compiler' => [
        'vendor_dir' => '../vendor',
        'autoloaders' => [ '../sample_autoloader2.php' ],
    ],
    'cache' => [
        'root' => '../cache',
        'filename' => 'demo_di',
    ],
    'slots' => [
        [
            'id' => 'david',
            'type' => 'object',
            'instanceOf' => '\Sample\PersonInterface',
            'locked' => true,
        ]
    ],
    'components' => [
        [
            'id' => 'david',
            'type' => 'object',
            'class_name' => 'Sample\Person',
            'injections' => [
                'new' => [
                    "David Smith",
                    "@int: 24",
                    "@float: 179.2",
                    "@func: function(\$target){ return 'throws '.\$target.'.'; }",
                ]
            ]        
        ]
    ],
];

组件配置文件：参数

组件配置文件：槽位项参数

组件配置文件：组件项参数

组件配置文件：组件注入参数

许可证

此库受MIT许可证的许可。

作者

stk2k

免责声明

此软件无任何保证。

我们不承担由此软件使用引起任何结果的任何责任。请自行承担责任。