amphp/injector

一个用于启动面向对象PHP应用的依赖注入器。

维护者

详情

github.com/amphp/injector

主页

源代码

问题

资助包维护！
amphp

安装: 51

依赖者: 0

建议者: 0

安全: 0

星标: 32

关注者: 11

分支: 7

开放问题: 3

dev-master / 1.x-dev 2022-02-13 19:21 UTC

Requires

Requires (Dev)

MIT edf59c760eb0e8194814507e6ba207af109b8008

dependency injectiondicioc

This package is auto-updated.

Last update: 2024-09-14 01:10:30 UTC

README

一个递归依赖注入器，用于启动和连接S.O.L.I.D.、面向对象的PHP应用。

工作原理

除了其他功能外，注入器会递归地根据类构造函数签名中指定的参数类型提示创建类依赖。这需要使用反射。你可能听说过“反射很慢”。让我们澄清一下：如果你做错了，“任何东西”都可能“慢”。反射的速度比磁盘访问快一个数量级，比从远程数据库检索信息快几个数量级。此外，每个反射都提供了缓存结果的机会，如果你担心速度的话。注入器会缓存它生成的任何反射，以最小化潜在的性能影响。

注入器**不是**服务定位器。不要通过将注入器传递到你的应用类中将其变成一个。服务定位器是一个反模式；它隐藏了类依赖关系，使代码更难以维护，并让你的API成为谎言！你应该**仅**在启动阶段使用注入器来连接应用的不同部分。

指南

基本用法

高级用法

示例用法

需求和安装

  • 需要PHP 8.0或更高版本。

安装

Composer

你也可以使用composer在你的项目的composer.json中包含项目作为依赖项。相关的包是amphp/injector。

或者使用composer cli来要求该包

composer require amphp/injector

基本用法

要开始使用注入器，只需创建一个新的Amp\Injector\Injector（“注入器”）类的实例

<?php
$injector = new Amp\Injector\Injector;

基本实例化

如果一个类在其构造函数签名中没有指定任何依赖项，那么使用注入器来生成它是没有意义的。然而，为了完整性考虑，你可以做以下操作以获得等效的结果

<?php
$injector = new Amp\Injector\Injector;
$obj1 = new SomeNamespace\MyClass;
$obj2 = $injector->make(SomeNamespace\MyClass::class);

var_dump($obj2 instanceof SomeNamespace\MyClass); // true
具体类型提示的依赖项

如果一个类只请求具体的依赖项，你可以使用注入器注入它们而不指定任何注入定义。例如，在以下场景中，你可以使用注入器自动为MyClass提供所需的SomeDependency和AnotherDependency类实例

<?php
class SomeDependency {}

class AnotherDependency {}

class MyClass {
    public $dep1;
    public $dep2;
    public function __construct(SomeDependency $dep1, AnotherDependency $dep2) {
        $this->dep1 = $dep1;
        $this->dep2 = $dep2;
    }
}

$injector = new Amp\Injector\Injector;
$myObj = $injector->make(MyClass::class);

var_dump($myObj->dep1 instanceof SomeDependency); // true
var_dump($myObj->dep2 instanceof AnotherDependency); // true
递归依赖实例化

注入器的一个关键属性是它递归遍历类依赖树以实例化对象。这只是一个花哨的说法，“如果你实例化了对象A，它请求对象B，注入器将实例化对象B的任何依赖项，以便B可以被实例化并提供给A”。这最好用一个简单的例子来理解。考虑以下类，其中Car请求Engine，而Engine类有自己的具体依赖项

<?php
class Car {
    private $engine;
    public function __construct(Engine $engine) {
        $this->engine = $engine;
    }
}

class Engine {
    private $sparkPlug;
    private $piston;
    public function __construct(SparkPlug $sparkPlug, Piston $piston) {
        $this->sparkPlug = $sparkPlug;
        $this->piston = $piston;
    }
}

$injector = new Amp\Injector\Injector;
$car = $injector->make(Car::class);
var_dump($car instanceof Car); // true

注入定义

您可能已经注意到，之前的例子都是通过显式、类型提示的具体构造函数参数来实例化类的。显然，许多类都不符合这种模式。一些类会类型提示接口和抽象类。一些会指定标量参数，在PHP中无法进行类型提示。还有一些参数将是数组等。在这种情况下，我们需要帮助注入器，告诉它我们确切想要注入的内容。

为构造函数参数定义类名

让我们看看如何为具有构造函数签名中非具体类型提示的类提供支持。考虑以下代码，其中需要一个Car和Engine，而Engine是一个接口

<?php
interface Engine {}

class V8 implements Engine {}

class Car {
    private $engine;
    public function __construct(Engine $engine) {
        $this->engine = $engine;
    }
}

在这种情况下，我们只需在之前定义类的注入定义即可实例化一个Car

<?php
$injector = new Amp\Injector\Injector;
$injector->define(Car::class, ['engine' => 'V8']);
$car = $injector->make(Car::class);

var_dump($car instanceof Car); // true

这里最重要的几点是

  1. 自定义定义是一个array，其键与构造函数参数名称匹配
  2. 定义数组中的值代表要为指定的参数键注入的类名

因为我们需要定义的Car构造函数参数名为$engine，所以我们的定义指定了一个engine键，其值是我们想要注入的类的名称（V8）。

自定义注入定义只在每个参数的基础上是必要的。例如，在下面的类中，我们只需定义$arg2的注入类，因为$arg1指定了具体的类类型提示

<?php
class MyClass {
    private $arg1;
    private $arg2;
    public function __construct(SomeConcreteClass $arg1, SomeInterface $arg2) {
        $this->arg1 = $arg1;
        $this->arg2 = $arg2;
    }
}

$injector = new Amp\Injector\Injector;
$injector->define(MyClass::class, ['arg2' => 'SomeImplementationClass']);

$myObj = $injector->make(MyClass::class);

注意：在类型提示为抽象类时注入实例的工作方式与上述接口类型提示的例子完全相同。

在注入定义中使用现有实例

注入定义也可以指定所需类的预存在实例，而不是字符串类名

<?php
interface SomeInterface {}

class SomeImplementation implements SomeInterface {}

class MyClass {
    private $dependency;
    public function __construct(SomeInterface $dependency) {
        $this->dependency = $dependency;
    }
}

$injector = new Amp\Injector\Injector;
$dependencyInstance = new SomeImplementation;
$injector->define(MyClass::class, [':dependency' => $dependencyInstance]);

$myObj = $injector->make(MyClass::class);

var_dump($myObj instanceof MyClass); // true

注意：由于这个define()调用传递的是原始值（如冒号:的使用所示），您可以通过省略数组键并依靠参数顺序而不是名称来实现相同的结果。如下所示：$injector->define('MyClass', [$dependencyInstance]);

在运行时指定注入定义

您还可以使用Amp\Injector\Injector::make在调用时指定注入定义。考虑以下代码

<?php
interface SomeInterface {}

class SomeImplementationClass implements SomeInterface {}

class MyClass {
    private $dependency;
    public function __construct(SomeInterface $dependency) {
        $this->dependency = $dependency;
    }
}

$injector = new Amp\Injector\Injector;
$myObj = $injector->make('MyClass', ['dependency' => 'SomeImplementationClass']);

var_dump($myObj instanceof MyClass); // true

上面的代码显示了即使我们没有调用注入器的define方法，调用时的指定也允许我们实例化MyClass。

注意：在运行时实例化的定义将覆盖指定类的预定义定义，但仅限于该特定的Amp\Injector\Injector::make调用。

类型提示别名

面向接口是面向对象设计（OOD）中最有用的概念之一，并且设计良好的代码应该在可能的情况下类型提示接口。但这是否意味着我们必须为应用程序中的每个类分配注入定义才能获得抽象依赖的好处？幸运的是，这个问题的答案是，“不”。注入器通过接受“别名”来满足这个目标。考虑以下代码

<?php
interface Engine {}
class V8 implements Engine {}
class Car {
    private $engine;
    public function __construct(Engine $engine) {
        $this->engine = $engine;
    }
}

$injector = new Amp\Injector\Injector;

// Tell the Injector class to inject an instance of V8 any time
// it encounters an Engine type-hint
$injector->alias('Engine', 'V8');

$car = $injector->make('Car');
var_dump($car instanceof Car); // bool(true)

在这个例子中，我们演示了如何为特定接口或抽象类类型提示的任何发生指定别名类。一旦分配了实现，注入器将使用它为具有匹配类型提示的任何参数提供支持。

重要：如果为参数定义了注入定义，并且该参数包含实现分配，则定义优先于实现。

非类参数

所有之前的例子都演示了注入器类如何根据类型提示、类名定义和现有实例来实例化参数。但如果我们想要将标量或其他非对象变量注入类中会发生什么？首先，让我们建立以下行为规则

重要：注入器默认将所有命名参数定义视为类名。

如果您想让注入器将命名参数定义视为“原始”值而不是类名，必须在定义中用冒号字符：前缀参数名称。例如，考虑以下代码，我们告诉注入器共享一个PDO数据库连接实例并定义其标量构造函数参数

<?php
$injector = new Amp\Injector\Injector;
$injector->share('PDO');
$injector->define('PDO', [
    ':dsn' => 'mysql:dbname=testdb;host=127.0.0.1',
    ':username' => 'dbuser',
    ':passwd' => 'dbpass'
]);

$db = $injector->make('PDO');

在参数名称之前的前导冒号字符告诉注入器关联的值不是类名。如果省略了上面的冒号，注入器将尝试实例化指定在字符串中的类名，并导致异常。另外，请注意，我们还可以在上面的定义中使用数组、整数或任何其他数据类型。只要参数名称前有：前缀，注入器就会直接注入值，而不会尝试实例化它。

注意：如前所述，由于此define()调用正在传递原始值，您可以选择按参数顺序而不是按名称分配值。由于PDO的前三个参数是$dsn、$username和$password，顺序如下，您可以通过省略数组键来实现相同的结果：$injector->define('PDO', ['mysql:dbname=testdb;host=127.0.0.1', 'dbuser', 'dbpass']);

全局参数定义

有时应用程序可能需要到处重复使用相同的值。然而，在应用程序可能使用的地方手动指定此类定义可能很麻烦。注入器通过公开Injector::defineParam()方法来减轻这个问题。考虑以下示例...

<?php
$myUniversalValue = 42;

class MyClass {
    public $myValue;
    public function __construct($myValue) {
        $this->myValue = $myValue;
    }
}

$injector = new Amp\Injector\Injector;
$injector->defineParam('myValue', $myUniversalValue);
$obj = $injector->make('MyClass');
var_dump($obj->myValue === 42); // bool(true)

由于我们为myValue指定了全局定义，因此所有未以其他方式定义（如下所示）且与指定的参数名称匹配的参数都将自动填充全局值。如果参数符合以下任何标准，则不使用全局值

  • 类型提示
  • 预定义的注入定义
  • 自定义调用时间定义

高级用法

实例共享

在现代面向对象编程中，Singleton反模式是一种更为普遍的弊病。希望限制类到单个实例的编码者通常会陷入使用static Singleton实现配置类和数据库连接等事物的陷阱。虽然防止类的多个实例通常是必要的，但Singleton方法对可测试性来说是致命的，通常应避免使用。Amp\Injector\Injector使得在上下文中共享类实例变得简单，同时允许最大的可测试性和API透明度。

让我们考虑如何通过使用注入器将应用程序连接起来，轻松解决面向对象的Web应用程序中遇到的典型问题。在这里，我们想在应用程序的多层之间注入单个数据库连接实例。我们有一个控制器类，该类请求一个需要PDO数据库连接实例的数据映射器

<?php
class DataMapper {
    private $pdo;
    public function __construct(PDO $pdo) {
        $this->pdo = $pdo;
    }
}

class MyController {
    private $mapper;
    public function __construct(DataMapper $mapper) {
        $this->mapper = $mapper;
    }
}

$db = new PDO('mysql:host=localhost;dbname=mydb', 'user', 'pass');

$injector = new Amp\Injector\Injector;
$injector->share($db);

$myController = $injector->make('MyController');

在上面的代码中，将使用与最初共享相同的PDO数据库连接实例来提供DataMapper实例。这个例子是人为设计的，过于简单，但意义应该是明显的

通过共享类的实例，Amp\Injector\Injector将始终在提供类型提示的共享类时使用该实例来提供类。

一个更简单的例子

让我们看看一个简单的概念证明

<?php
class Person {
    public $name = 'John Snow';
}

$injector = new Amp\Injector\Injector;
$injector->share('Person');

$person = $injector->make('Person');
var_dump($person->name); // John Snow

$person->name = 'Arya Stark';

$anotherPerson = $injector->make('Person');
var_dump($anotherPerson->name); // Arya Stark
var_dump($person === $anotherPerson); // bool(true) because it's the same instance!

将对象定义为共享将存储在注入器的共享缓存中提供的实例，并且所有将来的请求都会返回最初创建的对象。注意，在上述代码中，我们共享了类名（Person）而不是实际实例。共享可以与类名或类的实例一起使用。区别在于，当您指定类名时，注入器将在第一次请求创建它时缓存共享的实例。

注意：一旦注入器缓存了一个共享实例，传递给Amp\Injector\Injector::make的调用时定义将不会有任何效果。一旦共享，该类型的实例将始终返回，直到对象取消共享或刷新。

实例化代表

通常，工厂类/方法用于在实例化后准备对象。注入器允许您通过指定每个类的可调用实例化代理来直接将工厂和构建器集成到注入过程中。让我们通过一个非常基本的例子来展示注入代理的概念。

<?php
class MyComplexClass {
    public $verification = false;
    public function doSomethingAfterInstantiation() {
        $this->verification = true;
    }
}

$complexClassFactory = function() {
    $obj = new MyComplexClass;
    $obj->doSomethingAfterInstantiation();

    return $obj;
};

$injector = new Amp\Injector\Injector;
$injector->delegate('MyComplexClass', $complexClassFactory);

$obj = $injector->make('MyComplexClass');
var_dump($obj->verification); // bool(true)

在上面的代码中，我们将MyComplexClass类的实例化委托给闭包$complexClassFactory。一旦进行了这种委托，注入器将在请求实例化MyComplexClass时返回指定的闭包的结果。

可用的代理类型

任何有效的PHP可调用函数都可以使用Amp\Injector\Injector::delegate注册为类实例化代理。此外，您可以指定一个委托类，该类指定了一个__invoke方法，它将在委托时自动配置并调用其__invoke方法。还可以使用['NonStaticClassName', 'factoryMethod']构造指定未实例化类的实例方法。例如

<?php
class SomeClassWithDelegatedInstantiation {
    public $value = 0;
}
class SomeFactoryDependency {}
class MyFactory {
    private $dependency;
    function __construct(SomeFactoryDependency $dep) {
        $this->dependency = $dep;
    }
    function __invoke() {
        $obj = new SomeClassWithDelegatedInstantiation;
        $obj->value = 1;
        return $obj;
    }
    function factoryMethod() {
        $obj = new SomeClassWithDelegatedInstantiation;
        $obj->value = 2;
        return $obj;
    }
}

// Works because MyFactory specifies a magic __invoke method
$injector->delegate('SomeClassWithDelegatedInstantiation', 'MyFactory');
$obj = $injector->make('SomeClassWithDelegatedInstantiation');
var_dump($obj->value); // int(1)

// This also works
$injector->delegate('SomeClassWithDelegatedInstantiation', 'MyFactory::factoryMethod');
$obj = $injector->make('SomeClassWithDelegatedInstantiation');
$obj = $injector->make('SomeClassWithDelegatedInstantiation');
var_dump($obj->value); // int(2)

准备和设置注入

构造函数注入几乎总是优于设置器注入。然而，某些API需要额外的实例化后突变。注入器通过其Injector::prepare()方法来适应这些用例。用户可以为实例化后的修改注册任何类或接口名称。考虑以下示例

<?php

class MyClass {
    public $myProperty = 0;
}

$injector->prepare('MyClass', function($myObj, $injector) {
    $myObj->myProperty = 42;
});

$myObj = $injector->make('MyClass');
var_dump($myObj->myProperty); // int(42)

虽然上面的示例是人为的，但它的实用性应该是明显的。

执行注入

除了使用构造函数提供类实例之外，注入器还可以递归地实例化任何有效的PHP可调用函数的参数。以下所有示例都有效

<?php
$injector = new Amp\Injector\Injector;
$injector->execute(function(){});
$injector->execute([$objectInstance, 'methodName']);
$injector->execute('globalFunctionName');
$injector->execute('MyStaticClass::myStaticMethod');
$injector->execute(['MyStaticClass', 'myStaticMethod']);
$injector->execute(['MyChildStaticClass', 'parent::myStaticMethod']);
$injector->execute('ClassThatHasMagicInvoke');
$injector->execute($instanceOfClassThatHasMagicInvoke);
$injector->execute('MyClass::myInstanceMethod');

此外，您还可以传递一个类的名称用于非静态方法，注入器将在提供和调用指定方法之前自动提供一个该类的实例（受注入器存储的任何定义或共享实例的影响）

<?php
class Dependency {}
class AnotherDependency {}
class Example {
    function __construct(Dependency $dep){}
    function myMethod(AnotherDependency $arg1, $arg2) {
        return $arg2;
    }
}

$injector = new Amp\Injector\Injector;

// outputs: int(42)
var_dump($injector->execute('Example::myMethod', $args = [':arg2' => 42]));

依赖解析

Amp\Injector\Injector按以下顺序解决依赖关系

  1. 如果存在该类的共享实例，将始终返回该共享实例
  2. 如果为类分配了代理可调用函数，则将始终使用其返回结果
  3. 如果将调用时定义传递给Amp\Injector\Injector::make，则将使用该定义
  4. 如果存在预定义的定义，则将使用它
  5. 如果依赖项具有类型提示，则注入器将递归地实例化它，受任何实现或定义的影响
  6. 如果没有类型提示并且参数具有默认值，则注入默认值
  7. 如果定义了全局参数值，则使用该值
  8. 抛出一个异常，因为您做了愚蠢的事情

示例用法

依赖注入容器（DIC）在PHP社区中通常被误解。主要原因是主流应用程序框架中这类容器的不当使用。通常，这些框架将它们的DIC扭曲成服务定位器反模式。这是可耻的，因为一个好的DIC应该是服务定位器的直接对立面。

注入器不是服务定位器！

使用DIC将应用程序连接起来和使用将DIC作为对象依赖项（服务定位器）之间存在巨大的差异。服务定位器（SL）是一种反模式——它隐藏了类依赖项，使代码难以维护，并使您的API成为谎言。

当您将SL传递给构造函数时，很难确定类的实际依赖关系。一个House对象依赖于Door和Window对象。无论ServiceLocator是否能提供Door和Window对象，House对象都不会依赖于ServiceLocator的实例。

在现实生活中，您不会把整个五金店（希望如此）运到建筑工地来建造房屋，以便可以访问所需的任何部分。相反，工头（__construct()）会请求所需的特定部件（Door和Window），并着手获取它们。您的对象应该以同样的方式工作；它们应该只请求执行其工作所需的具体依赖。给House访问整个五金店，至多是不良的OOP风格，最坏的情况是维护噩梦。这里的要点是

重要：不要像使用Service Locator一样使用注入器！

避免邪恶的单例

在Web应用程序中，限制数据库连接实例的数量是一个常见的难题。每次我们需要与数据库通信时打开新的连接既浪费又慢。不幸的是，使用单例来限制这些实例会使代码脆弱且难以测试。让我们看看我们如何可以使用注入器将相同的PDO实例注入到我们应用程序的整个范围内。

假设我们有一个需要两个单独的数据映射器将信息持久化到数据库的服务类

<?php

class HouseMapper {
    private $pdo;
    public function __construct(PDO $pdo) {
        $this->pdo = $pdo;
    }
    public function find($houseId) {
        $query = 'SELECT * FROM houses WHERE houseId = :houseId';

        $stmt = $this->pdo->prepare($query);
        $stmt->bindValue(':houseId', $houseId);

        $stmt->setFetchMode(PDO::FETCH_CLASS, 'Model\\Entities\\House');
        $stmt->execute();
        $house = $stmt->fetch(PDO::FETCH_CLASS);

        if (false === $house) {
            throw new RecordNotFoundException(
                'No houses exist for the specified ID'
            );
        }

        return $house;
    }

    // more data mapper methods here ...
}

class PersonMapper {
    private $pdo;
    public function __construct(PDO $pdo) {
        $this->pdo = $pdo;
    }
    // data mapper methods here
}

class SomeService {
    private $houseMapper;
    private $personMapper;
    public function __construct(HouseMapper $hm, PersonMapper $pm) {
        $this->houseMapper = $hm;
        $this->personMapper = $pm;
    }
    public function doSomething() {
        // do something with the mappers
    }
}

在我们的连接/引导代码中，我们只需实例化一次PDO实例，并在Injector的上下文中共享它

<?php
$pdo = new PDO('sqlite:some_sqlite_file.db');
$pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

$injector = new Amp\Injector\Injector;

$injector->share($pdo);
$mapper = $injector->make('SomeService');

在上面的代码中，DIC实例化了我们的服务类。更重要的是，它为了这样做而生成的数据映射器类是注入了我们最初共享的同一个数据库连接实例。

当然，我们不必手动实例化我们的PDO实例。我们也可以在容器中注入一个如何创建PDO对象的定义，让它为我们处理事情

<?php
$injector->define('PDO', [
    ':dsn' => 'sqlite:some_sqlite_file.db'
]);
$injector->share('PDO');
$service = $injector->make('SomeService');

在上面的代码中，注入器会将字符串定义作为$dsn参数传递给PDO::__construct方法，并在它实例化的类中需要PDO实例时自动生成共享的PDO实例！

应用引导

DIC应该用于将您应用程序的不同对象连接成一个统一的单元（通常在引导或前端控制器阶段）。这种用法为面向对象（OO）Web应用程序中一个棘手的问题提供了一个优雅的解决方案：如何在依赖关系未知的环境中实例化类。

考虑以下前端控制器代码，其任务是

  1. 加载应用程序路由列表并将其传递给路由器
  2. 生成客户端HTTP请求的模型
  3. 根据应用程序的路由列表路由请求实例
  4. 实例化路由控制器并调用适合HTTP请求的方法
<?php

define('CONTROLLER_ROUTES', '/hard/path/to/routes.xml');

$routeLoader = new RouteLoader();
$routes = $routeLoader->loadFromXml(CONTROLLER_ROUTES);
$router = new Router($routes);

$requestDetector = new RequestDetector();
$request = $requestDetector->detectFromSuperglobal($_SERVER);

$requestUri = $request->getUri();
$requestMethod = strtolower($request->getMethod());

$injector = new Amp\Injector\Injector;
$injector->share($request);

try {
    if (!$controllerClass = $router->route($requestUri, $requestMethod)) {
        throw new NoRouteMatchException();
    }

    $controller = $injector->make($controllerClass);
    $callableController = array($controller, $requestMethod);

    if (!is_callable($callableController)) {
        throw new MethodNotAllowedException();
    } else {
        $callableController();
    }

} catch (NoRouteMatchException $e) {
    // send 404 response
} catch (MethodNotAllowedException $e) {
    // send 405 response
} catch (Exception $e) {
    // send 500 response
}

我们还有各种控制器类，每个类都请求它自己的特定依赖

<?php

class WidgetController {
    private $request;
    private $mapper;
    public function __construct(Request $request, WidgetDataMapper $mapper) {
        $this->request = $request;
        $this->mapper = $mapper;
    }
    public function get() {
        // do something for HTTP GET requests
    }
    public function post() {
        // do something for HTTP POST requests
    }
}

在上面的例子中，注入器DIC允许我们编写完全可测试的、完全OO的控制器，它们请求它们的依赖。因为DIC递归实例化它创建的对象的依赖，所以我们不需要传递Service Locator。此外，这个例子还展示了我们如何利用注入器DIC的共享功能来消除邪恶的单例。在前端控制器代码中，我们共享请求对象，以便任何由Amp\Injector\Injector实例化的、请求Request的类都会接收到相同的实例。这个功能不仅有助于消除单例，还有助于消除难以测试的static属性。