szepeviktor/injector-php-7

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

维护者

详细信息

github.com/szepeviktor/injector-php-7

主页

源代码

问题

安装: 5

依赖者: 0

建议者: 0

安全性: 0

星标: 5

关注者: 2

分支: 1

公开问题: 0

v1.5.1 2021-04-07 22:35 UTC

Requires

  • php: ^7.4

Requires (Dev)

MIT 1c3d5c133e65275dcfde1a32868716c552faf60a

dependency injectiondicioc

This package is auto-updated.

Last update: 2024-09-08 06:07:50 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
递归依赖实例化

注入器的一个关键属性是它递归地遍历类依赖项树以实例化对象。这只是一个花哨的说法，“如果你实例化了请求对象B的对象A，注入器将实例化对象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 透明度。

让我们考虑一下，如何通过使用注入器将应用程序连接起来，轻松解决面向对象网络应用程序中遇到的一个典型问题。在这里，我们想在应用程序的多个层之间注入单个数据库连接实例。我们有一个控制器类，它要求一个需要 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 数据库连接实例。这个例子是人为的并且过于简单，但其含义应该是明确的

通过共享类的实例，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 应该是服务定位器的完全相反。

注入器 NOT 是服务定位器！

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

当你将 SL 传递给构造函数时，它使确定类依赖项变得困难。一个 House 对象依赖于 Door 和 Window 对象。无论 ServiceLocator 是否可以提供 Door 和 Window 对象，House 对象 DO NOT 依赖于 ServiceLocator 的实例。

在现实生活中，你不会把整个五金店（希望不是）运到建筑工地，以便可以获取所需的任何部分。相反，工头（__construct()）会询问所需的特定部件（Door 和 Window）并着手采购它们。你的对象应该以相同的方式运行；它们应该只请求完成工作所需的特定依赖项。让 House 访问整个五金店，至多是一种糟糕的面向对象风格，在最坏的情况下是一个维护噩梦。这里得到的启示是：

重要：不要像服务定位器一样使用注入器！

避免邪恶的单例

在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 允许我们编写完全可测试的、完全面向对象的控制器，这些控制器要求其依赖项。由于 DIC 递归实例化它创建的对象的依赖项，所以我们不需要传递 Service Locator。此外，这个示例展示了我们如何使用注入器 DIC 的共享功能来消除邪恶的单例。在前端控制器代码中，我们共享请求对象，以便任何由 Amp\Injector\Injector 实例化的并要求 Request 的类都将收到相同的实例。这个功能不仅有助于消除单例，而且还有助于消除难以测试的 static 属性。