README

🇷🇺 俄罗斯公民

我们，Laminas的参与者，来自不同的国家。我们中的许多人都有在俄罗斯和乌克兰的朋友、亲戚和同事。我们中的一些人出生在俄罗斯。我们中的一些人目前住在俄罗斯。我们中的一些人的祖父母在第二次世界大战中与法西斯作战。在这里，没有人支持法西斯主义。

我们中的一位成员有一位乌克兰亲戚和她儿子一起逃离了家园。由于前方道路上的轰炸，火车延误了。我们有一些朋友在防空洞里藏身。在空袭后，我们焦虑地追踪他们的消息，这些空袭不分青红皂白地袭击医院、学校、幼儿园和房屋。我们不是从任何媒体上得知这些。这是我们亲身体验。

您足够信任我们使用我们的程序，我们请求您再次信任我们。我们需要您的帮助。走出来抗议这场毫无意义的战争。停止流血。说“不，战争！”

🇺🇸 致俄罗斯公民

我们Laminas来自世界各地。我们中的许多人都在俄罗斯和乌克兰有朋友、家人和同事。我们中的一些人出生在俄罗斯。我们中的一些人目前住在俄罗斯。我们中的一些人的祖父母在第二次世界大战中与纳粹作战。在这里，没有人支持法西斯主义。

我们的一位团队成员有一位乌克兰亲戚和她儿子一起逃离了家园。由于前方道路上的轰炸，火车延误了。我们有一些朋友在防空洞里藏身。在空袭后，我们焦虑地追踪他们的消息，这些空袭不分青红皂白地袭击医院、学校、幼儿园和房屋。我们不是从任何媒体上得知这些。这是我们亲身体验。

您足够信任我们使用我们的软件。我们请求您信任我们说出真相。我们需要您的帮助。走出来抗议这场不必要的战争。停止杀戮。说“停止战争！”

本模块提供了集成Doctrine与Laminas API Tools所需的类。

安装

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

$ composer require laminas-api-tools/api-tools-doctrine

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

Laminas\ApiTools\Doctrine\Server与Phpro\DoctrineHydrationModule有依赖关系，以处理实体注入。有关如何设置此模块的文档和说明。

laminas-component-installer

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

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

API资源

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

/api-tools/api/doctrine[/:object_manager_alias]/metadata[/:name]

这将返回指定实体的元数据，该实体是指定对象管理器的成员。如果没有指定名称进行查询，将返回对象管理器的所有元数据。

/api-tools/api/module[/:name]/doctrine[/:controller_service_name]

这是一个类似Laminas API Tools Rest /api-tools/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
}

通过值或引用实体化实体

默认情况下，admin工具通过引用来实体化实体，通过设置$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';

通过Shared Event Manager附加到事件

use Laminas\ApiTools\Doctrine\Server\Event\DoctrineResourceEvent;

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

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

还可以向单个doctrine连接资源配置中添加自定义事件监听器

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

查询单个实体

多键实体

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

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

不再支持。从版本2.0.4开始，此功能已从该模块中删除。该模块的预期用途是实体与资源的一对一映射，使用子路由不符合此意图。强烈建议您使用laminas-api-tools/api-tools-doctrine-querybuilder进行复杂的查询。

查询提供者

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

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

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

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

在注册查询提供者后，将其附加到doctrine连接资源配置。如果没有设置特定的查询提供者，则使用默认查询提供者。您可以为以下密钥设置查询提供者

• default
• fetch
• fetch_all
• update
• patch
• delete

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

查询创建过滤器

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

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

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

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

将查询创建过滤器注册为

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

使用实体工厂

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

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