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. 自定义定义是一个数组，其键与构造函数参数名称相匹配
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 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 数据库连接实例的 DataMapper

<?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');

在上面的代码中，DataMapper 实例将获得我们最初共享的相同 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 是一个服务定位器！

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

当您将SL传递给构造函数时，这将使您难以确定类依赖关系究竟是什么。一个House对象依赖于Door和Window对象。一个House对象并不依赖于一个ServiceLocator的实例，不管ServiceLocator是否可以提供Door和Window对象。

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

重要：不要像 Service Locator 一样使用 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');

在上面的代码中，注入器会将字符串定义作为 $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 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 递归地实例化它创建的对象的依赖项，所以我们不需要传递 Service Locator。此外，这个例子还展示了我们如何使用 auryn DIC 的共享功能消除邪恶的单例。在前端控制器代码中，我们共享请求对象，以便任何由 Auryn\Injector 实例化的并请求 Request 的类都将接收相同的实例。这个功能不仅有助于消除单例，而且消除了对难以测试的 static 属性的需求。