rdlowrey/auryn

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

维护者

详细信息

github.com/rdlowrey/auryn

主页

源代码

问题

安装次数: 1,963,278

依赖项: 96

建议者: 2

安全: 0

星标: 724

关注者: 30

分支: 65

公开问题: 3

v1.4.4 2021-03-04 20:26 UTC

Requires

  • php: >=5.3.0

Requires (Dev)

MIT dae57592229d313b59414a2c8334e61e6eb00928

dependency injectiondicioc

This package is not auto-updated.

Last update: 2024-09-14 12:39:30 UTC

README

auryn 是一个递归依赖注入器。使用 auryn 启动并连接 S.O.L.I.D.，面向对象的 PHP 应用程序。

工作原理

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

auryn 不是 服务定位器。不要通过将注入器传递到你的应用程序类中将其变成一个。服务定位器是一个反模式；它隐藏类依赖项，使代码更难以维护，并使你的 API 成为一个骗子！你应该 仅 在引导阶段使用注入器连接应用程序的不同部分。

指南

基本用法

高级用法

示例用例

要求和安装

  • auryn 需要 PHP 5.3 或更高版本。

安装

Github

你可以随时从 github 仓库克隆最新的 auryn 版本

$ git clone git://github.com/rdlowrey/auryn.git
Composer

你还可以使用 composer 将 auryn 作为项目 composer.json 中的依赖项。相关包是 rdlowrey/auryn。

或者使用 composer 命令行工具安装包

composer require rdlowrey/auryn
手动下载

归档的标记版本也可在项目的 标签页面 上手动下载

基本用法

要开始使用注入器，只需创建一个新的 Auryn\Injector ("注入器") 类实例

<?php
$injector = new Auryn\Injector;

基本实例化

如果一个类在其构造函数签名中没有指定任何依赖项，使用注入器生成它的意义不大。然而，为了完整性，考虑以下等效结果

<?php
$injector = new Auryn\Injector;
$obj1 = new SomeNamespace\MyClass;
$obj2 = $injector->make('SomeNamespace\MyClass');

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 Auryn\Injector;
$myObj = $injector->make('MyClass');

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 Auryn\Injector;
$car = $injector->make('Car');
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 Auryn\Injector;
$injector->define('Car', ['engine' => 'V8']);
$car = $injector->make('Car');

var_dump($car instanceof Car); // true

这里最重要的几点是

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

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

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

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

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

$myObj = $injector->make('MyClass');

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

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

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

<?php
interface SomeInterface {}

class SomeImplementation implements SomeInterface {}

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

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

$myObj = $injector->make('MyClass');

var_dump($myObj instanceof MyClass); // true

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

即时指定注入定义

你也可以使用Auryn\Injector::make在调用时指定注入定义

<?php
interface SomeInterface {}

class SomeImplementationClass implements SomeInterface {}

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

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

var_dump($myObj instanceof MyClass); // true

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

注意：即时实例化定义将覆盖为指定类预先定义的定义，但仅限于Auryn\Injector::make的特定调用上下文中。

类型提示别名

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

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

$injector = new Auryn\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 Auryn\Injector;
$injector->share('PDO');
$injector->define('PDO', [
    ':dsn' => 'mysql:dbname=testdb;host=127.0.0.1',
    ':username' => 'dbuser',
    ':passwd' => 'dbpass'
]);

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

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

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

全局参数定义

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

<?php
$myUniversalValue = 42;

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

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

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

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

高级用法

实例共享

在现代化的面向对象编程中，Singleton反模式是一个更为普遍的祸害。寻求将类限制为单个实例的程序员往往会陷入使用static Singleton实现配置类和数据库连接的陷阱。虽然通常有必要防止类的多个实例，但Singleton方法会对可测试性造成致命打击，通常应该避免使用。Auryn\Injector使得在上下文中共享类实例变得轻而易举，同时允许最大限度的可测试性和API透明度。

让我们考虑一下，如何通过使用auryn将你的应用程序连接起来，轻松解决面向对象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 Auryn\Injector;
$injector->share($db);

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

在上面的代码中，数据映射器实例将使用我们最初共享的同一个PDO数据库连接实例。这个例子是人为设计的，过于简单，但含义应该是清晰的

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

一个更简单的例子

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

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

$injector = new Auryn\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），而不是实际的实例。共享既可以是一个类名，也可以是一个类的实例。区别在于，当你指定一个类名时，注入器将在第一次被要求创建它时缓存共享实例。

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

实例化代表

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

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

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

    return $obj;
};

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

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

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

可用的代理类型

任何有效的PHP可调用都可以使用Auryn\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)

准备和设置注入

构造函数注入几乎总是优于setter注入。然而，一些API需要额外的后实例化突变。auryn通过其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)

尽管上面的例子是虚构的，但其用途应该是显而易见的。

执行注入

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

<?php
$injector = new Auryn\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 Auryn\Injector;

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

依赖项解析

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

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

示例用例

依赖注入容器（DIC）在PHP社区中通常被误解。其中一个主要原因是主流应用程序框架中对这种容器的不当使用。通常，这些框架将它们的DIC扭曲为服务定位器反模式。这是令人遗憾的，因为一个好的DIC应该与服务定位器正好相反。

auryn NOT A Service Locator!

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

当你将SL（服务定位器）传递给构造函数时，很难确定类的真正依赖关系。一个House对象依赖于Door和Window对象。一个House对象即使ServiceLocator可以提供Door和Window对象，也不依赖于ServiceLocator的实例。

在现实生活中，你不会把整个五金店（希望如此）都运到建筑工地，以便可以访问所需的任何部分。相反，工头（__construct()）会询问所需的特定部件（Door和Window），并着手采购。你的对象应该以相同的方式运行；它们应该只请求执行其工作所需的特定依赖项。给House提供整个五金店的使用方式，最多是糟糕的OOP风格，最坏的情况下是维护噩梦。这里的要点是

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

避免邪恶的单例

在Web应用程序中，限制数据库连接实例的数量是一个常见的困难。每次我们需要与数据库通信时打开新的连接是浪费时间和速度的。不幸的是，使用单例来限制这些实例会使代码脆弱且难以测试。让我们看看我们如何使用auryn将相同的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 Auryn\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');

在上面的代码中，注入器将传递字符串定义作为PDO::__construct方法中的$dsn参数，并在需要它的任何类实例化时自动生成共享的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 Auryn\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
    }
}

在上面的示例中，auryn DIC使我们能够编写完全可测试的、完全面向对象的控制器，这些控制器请求其依赖项。因为DIC递归地实例化它创建的对象的依赖项，所以我们不需要传递服务定位器。此外，这个示例展示了我们如何使用auryn DIC的共享功能消除恶性的单例。在前端控制器代码中，我们共享请求对象，以便任何由Auryn\Injector实例化的、请求Request的类将收到相同的实例。这个功能不仅有助于消除单例，而且还有助于消除难以测试的static属性。