README

仓库于2019-12-31废弃

此仓库已迁移至 laminas-api-tools/api-tools-doctrine。

此模块提供了将Doctrine与Apigility集成的类。

安装

此模块的安装使用composer。有关composer文档，请参阅 getcomposer.org。

$ composer require zfcampus/zf-apigility-doctrine

此库提供两个模块。第一个，ZF\Apigility\Doctrine\Server提供了由第二个模块ZF\Apigility\Doctrine\Admin创建的数据的服务类。Admin模块用于创建apigility资源，而Server提供这些创建的资源。通常，您会在config/development.config.php中包含Admin，并在config/application.config.php中包含Server。

ZF\Apigility\Doctrine\Server依赖于Phpro\DoctrineHydrationModule来处理实体数据加载。有关如何设置此模块的文档和说明。

zend-component-installer

如果您使用zend-component-installer，该插件将安装zf-apigility-doctrine及其所有依赖模块，并将其作为您的应用程序配置中的一个模块安装。

对于Apache安装，建议将AllowEncodedSlashes指令设置为On，以便读取配置。

API资源

注意！本节是为zf-apigility-admin-ui的作者准备的。虽然可以使用这些说明手动创建Apigility Doctrine资源，但强烈建议使用UI。

/apigility/api/doctrine[/:object_manager_alias]/metadata[/:name]

这将返回名为实体成员的命名对象管理器的元数据。不指定名称的查询将返回对象管理器的所有元数据。

/apigility/api/module[/:name]/doctrine[/:controller_service_name]

这是一个类似于Apigility Rest /apigility/api/module[/:name]/rest[/:controller_service_name]的Doctrine资源路由。要创建资源，请不要包含[/:controller_service_name]。

POST参数

{
    "objectManager": "doctrine.entitymanager.orm_default",
    "serviceName": "Artist",
    "entityClass": "Db\\Entity\\Artist",
    "routeIdentifierName": "artist_id",
    "entityIdentifierName": "id",
    "routeMatch": "/api/artist",
    "pageSizeParam": "limit", // optional, default null
    "hydratorName": "DbApi\\V1\\Rest\\Artist\\ArtistHydrator", // optional, default generated
    "hydrateByValue": true // optional, default true
}

通过值或引用数据加载实体

默认情况下，管理工具通过将$config['doctrine-hydrator']['hydrator_class']['by_value']设置为false来通过引用数据加载实体。

自定义事件

可以通过钩入特定类型的DoctrineResourceEvent doctrine事件来实现。这样，可以在执行特定操作之前或之后修改doctrine实体或集合。

支持的事件

EVENT_FETCH_PRE = 'fetch.pre';
EVENT_FETCH_POST = 'fetch.post';
EVENT_FETCH_ALL_PRE = 'fetch-all.pre';
EVENT_FETCH_ALL_POST = 'fetch-all.post';
EVENT_CREATE_PRE = 'create.pre';
EVENT_CREATE_POST = 'create.post';
EVENT_UPDATE_PRE = 'update.pre';
EVENT_UPDATE_POST = 'update.post';
EVENT_PATCH_PRE = 'patch.pre';
EVENT_PATCH_POST = 'patch.post';
EVENT_PATCH_LIST_PRE = 'patch-all.pre';
EVENT_PATCH_LIST_POST = 'patch-all.post';
EVENT_DELETE_PRE = 'delete.pre';
EVENT_DELETE_POST = 'delete.post';
EVENT_DELETE_LIST_PRE = 'delete-list.pre';
EVENT_DELETE_LIST_POST = 'delete-list.post';

通过共享事件管理器附加到事件

use ZF\Apigility\Doctrine\Server\Event\DoctrineResourceEvent;

$sharedEvents = $this->getApplication()->getEventManager()->getSharedManager();

$sharedEvents->attach(
    'ZF\Apigility\Doctrine\DoctrineResource',
    DoctrineResourceEvent::EVENT_CREATE_PRE,
    function(DoctrineResourceEvent $e) {
        $e->stopPropagation();
        return new ApiProblem(400, 'Stop API Creation');
    }
);

还可以为单个与Doctrine连接的资源配置添加自定义事件监听器。

'zf-apigility' => [
    'doctrine-connected' => [
        'Api\\V1\\Rest\\User\\UserResource' => [
            // ...
            'listeners' => [
                'key.of.aggregate.listener.in.service_manager',
            ],
        ],
    ],
],

查询单个实体

多键实体

您可以通过路由参数来分隔多键。默认分隔符是点 .（例如，1.2.3）。您可以通过设置 DoctrineResource::setMultiKeyDelimiter($value) 来更改分隔符。

通过路由参数执行复杂查询

不再支持。自版本2.0.4起，此功能已从该模块中删除。此模块的预期用途是实体到资源的1:1映射，使用子路由并不符合此意图。强烈建议您使用 zfcampus/zf-doctrine-querybuilder 进行复杂查询。

查询提供者

查询提供者适用于所有查找操作。查找查询提供者在所有DoctrineResource方法（除了创建方法）对实体执行操作之前用于获取实体。

查询提供者返回一个QueryBuilder对象。通过使用自定义查询提供者，您可以在不修改资源的情况下注入特定于资源或用户的条件。例如，您可以在返回创建在此处创建的QueryBuilder之前，在您的查询提供者中添加$queryBuilder->andWhere('user = ' . $event->getIdentity());。其他用途包括软删除，这样最终用户只能看到活动记录。

有一个自定义插件管理器可用于注册您自己的查询提供者。这可以通过以下配置完成

'zf-apigility-doctrine-query-provider' => [
    'aliases' => [
        'entity_name_fetch_all' => \Application\Query\Provider\EntityName\FetchAll::class,
    ],
    'factories' => [
        \Application\Query\Provider\EntityName\FetchAll::class => \Zend\ServiceManager\Factory\InvokableFactory::class,
    ],
],

当查询提供者被注册后，将其附加到与Doctrine连接的资源配置。如果没有设置特定的查询提供者，则使用默认查询提供者。您可以为此键设置查询提供者

• 默认
• 获取
• 获取全部
• 更新
• 部分更新
• 删除

'zf-apigility' => [
    'doctrine-connected' => [
        'Api\\V1\\Rest\\....' => [
            'query_providers' => [
                'default' => 'default_orm',
                'fetch_all' => 'entity_name_fetch_all',
                // or fetch, update, patch, delete
            ],
        ],
    ],
],

查询创建过滤器

为了在将其用于实体实体化之前过滤或更改发送到创建语句的数据，您可以使用查询创建过滤器。创建过滤器在其实现上与Query Providers非常相似。

创建过滤器接受数据作为参数，并返回修改后或过滤后的数据。

有一个自定义插件管理器可用于注册您自己的创建过滤器。这可以通过以下配置完成

'zf-apigility-doctrine-query-create-filter' => [
    'aliases' => [
        'entity_name' => \Application\Query\CreateFilter\EntityName::class,
    ],
    'factories' => [
        \Application\Query\CreateFilter\EntityName::class => \Zend\ServiceManager\Factory\InvokableFactory::class,
    ],
],

将您的查询创建过滤器注册为

'zf-apigility' => [
    'doctrine-connected' => [
        'Api\\V1\\Rest\\....' => [
            'query_create_filter' => 'entity_name',
            ...
        ],
    ],
],

使用实体工厂

默认情况下，Doctrine实体通过FQCN无参数实例化。如果您需要不同的实现，例如如果您的实体需要在构造函数中具有参数，您可以指定在服务管理器中注册的Doctrine\Instantiator\InstantiatorInterface工厂的名称，以便将实例化委托给该服务。目前这只能通过直接编辑资源的配置来完成，如下所示

'zf-apigility' => [
    'doctrine-connected' => [
        'Api\\V1\\Rest\\...Resource' => [
            'entity_factory' => 'key_in_service_manager',
            ...
        ],
    ],
],