README

🇷🇺 俄罗斯公民

我们是Laminas的参与者，来自不同的国家。我们中许多人既有俄罗斯也有乌克兰的朋友、亲属和同事。其中一些人出生在俄罗斯。一些人现在住在俄罗斯。一些人祖父母在二战中与法西斯战斗过。在这里，没有人支持法西斯主义。

我们中有一个乌克兰亲属，她和儿子一起逃离了家园。火车因前方道路上的轰炸而延误。我们有朋友在防空洞里躲避。我们在空袭后焦急地等待他们的消息，空袭无差别地轰炸医院、学校、幼儿园和住宅。我们不是从任何媒体上得知这些。这是我们的亲身经历。

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

🇺🇸 致俄罗斯公民

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

我们团队中有一个乌克兰亲属，她和儿子一起逃离了家园。火车因前方道路上的轰炸而延误。我们有朋友在防空洞里躲避。我们在空袭后焦急地等待他们的消息，空袭无差别地轰炸医院、学校、幼儿园和住宅。我们不是从任何媒体上得知这些。这是我们的亲身经历。

您足够信任我们使用我们的软件。我们要求您信任我们说出真相。我们需要您的帮助。走出家门，抗议这场无意义的战争。停止杀戮。说“停止战争！”

简介

本模块提供了生成Hypermedia Application Language JSON表示的能力。

需求

请参阅composer.json文件。

安装

运行以下composer命令

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

或者，手动将以下内容添加到您的composer.json文件中的require部分

"require": {
    "laminas-api-tools/api-tools-hal": "^1.4"
}

然后运行composer update以确保安装该模块。

最后，将模块名称添加到您的项目配置文件config/application.config.php中的modules键下

return [
    /* ... */
    'modules' => [
        /* ... */
        'Laminas\ApiTools\Hal',
    ],
    /* ... */
];

laminas-component-installer

如果您使用laminas-component-installer，该插件将为您安装api-tools-hal作为模块。

配置

用户配置

此模块使用顶级键api-tools-hal进行用户配置。

键：renderer

这是一个用于配置api-tools-hal Hal视图助手/控制器插件的配置数组。它包含以下键

• default_hydrator - 如果存在，则此命名的 hydrator 服务将作为默认 hydrator 由 Hal 插件使用，当为实体类配置没有 hydrator 时。
• render_embedded_entities - 布尔值，默认 true，用于在 HAL 响应中渲染完整的嵌入式实体；如果 false，则嵌入式实体将仅包含它们的关联链接。
• render_embedded_collections - 布尔值，默认为 true，用于在 HAL 响应中渲染集合；如果为 false，则只渲染集合的关系链接。
• hydrators - 一个将实体类名称映射到 hydrator 服务名称的映射，HAL 插件在实体恢复时可以使用。

键：metadata_map

元数据映射用于提示 HAL 插件如何渲染特定类类型的对象。当 HAL 插件遇到元数据映射中找到的对象时，它将使用该类的配置来创建表示；此信息通常指示如何生成关系链接，如何序列化对象，以及是否表示集合。

元数据映射中的每个类可能包含以下配置键之一或多个

• entity_identifier_name - 用于标识符的类属性名称（在序列化后）。
• route_name - 用于生成集合或实体 self 关系链接的路线名称。
• route_identifier_name - 路线中使用的标识符名称，用于在 URI 路径中表示实体标识符。这通常与 entity_identifier_name 不同，因为路线中的每个变量段都必须具有唯一名称。
• hydrator - 序列化实体时使用的 hydrator 服务名称。
• is_collection - 布尔值；当类表示集合时设置为 true。
• links - 用于构建关系链接的配置数组；请参阅以下链接的结构。
• entity_route_name - 集合嵌入实体的路线名称。
• route_params - 用于链接生成的路线参数数组。
• route_options - 链接生成期间传递给路由器的选项数组。
• url - 如果不使用路线，则使用此资源的特定 URL。
• max_depth - 整数；限制渲染实体和集合的嵌套级别；如果达到限制，则仅渲染 self 链接。默认值为 null，表示没有限制：如果检测到无限循环引用，将抛出异常以避免无限循环。
• force_self_link - 布尔值；设置是否为实体自动生成自引用链接。默认值为 true（因为它被推荐）。

links 属性是一个数组，每个数组具有以下结构

[
    'rel'   => 'link relation',
    'url'   => 'string absolute URI to use', // OR
    'route' => [
        'name'    => 'route name for this link',
        'params'  => [ /* any route params to use for link generation */ .,
        'options' => [ /* any options to pass to the router */ .,
    .,
.,
// repeat as needed for any additional relational links

键：options

选项键用于配置 HAL 插件的一般选项。目前我们只有一个选项可用，包含以下配置键

• use_proxy - 布尔值；当你使用代理（使用 HTTP_X_FORWARDED_PROTO、HTTP_X_FORWARDED_HOST 和 HTTP_X_FORWARDED_PORT 而不是 SSL_HTTPS、HTTP_HOST, SERVER_PORT）时设置为 true。

系统配置

以下配置用于确保在基于 Laminas 的应用程序中正确运行此模块。

// Creates a "HalJson" selector for use with laminas-api-tools/api-tools-content-negotiation
'api-tools-content-negotiation' => [
    'selectors' => [
        'HalJson' => [
            'Laminas\ApiTools\Hal\View\HalJsonModel' => [
                'application/json',
                'application/*+json',
            ],
        ],
    ],
],

Laminas 事件

事件

Laminas\ApiTools\Hal\Plugin\Hal 事件管理器

Laminas\ApiTools\Hal\Plugin\Hal 在其生命周期中触发多个事件。从 HAL 插件中组合的 EventManager 实例，您可以附加以下事件

• renderCollection
• renderCollection.post
• renderEntity
• renderEntity.post
• createLink
• renderCollection.entity
• getIdFromEntity

例如，您可以像以下那样监听 renderEntity 事件（以下是在 Laminas 模块和/或 Laminas API Tools API 模块中的 Module 类中执行的）（

class Module
{
    public function onBootstrap($e)
    {
        $app = $e->getTarget();
        $services = $app->getServiceManager();
        $helpers  = $services->get('ViewHelperManager');
        $hal      = $helpers->get('Hal');

        // The HAL plugin's EventManager instance does not compose a SharedEventManager,
        // so you must attach directly to it.
        $hal->getEventManager()->attach('renderEntity', [$this, 'onRenderEntity']);
    }

    public function onRenderEntity($e)
    {
        $entity = $e->getParam('entity');
        if (! $entity->getEntity() instanceof SomeTypeIHaveDefined) {
            // do nothing
            return;
        }

        // Add a "describedBy" relational link
        $entity->getLinks()->add(\Laminas\ApiTools\Hal\Link\Link::factory([
            'rel' => 'describedBy',
            'route' => [
                'name' => 'my/api/docs',
            ],
        ]));
    }
}

关于个别事件的说明

• renderCollection 定义一个参数，collection，它是正在渲染的 Laminas\ApiTools\Hal\Collection。
• renderCollection.post 定义了两个参数：collection，表示正在渲染的 Laminas\ApiTools\Hal\Collection，和 payload，它是一个表示集合的 ArrayObject，包括页数、大小、总项目和链接。
• renderEntity 定义了一个参数，entity，表示正在渲染的 Laminas\ApiTools\Hal\Entity。
• renderEntity.post 定义了两个参数：entity，表示正在渲染的 Laminas\ApiTools\Hal\Entity，和 payload，它是一个表示实体的 ArrayObject，包括链接。
• createLink 定义了以下事件参数
  • route，生成链接时使用的路由名称，如果有。
  • id，生成链接时使用的实体标识值，如果有。
  • entity，正在生成链接的实体，如果有。
  • params，生成链接时使用的任何附加路由参数。
• renderCollection.entity 定义了以下事件参数
  • collection，实体所属的 Laminas\ApiTools\Hal\Collection。
  • entity，当前正在渲染的实体；这可能或可能不是 Laminas\ApiTools\Hal\Entity。
  • route，当前实体的路由名称。
  • routeParams，生成当前实体链接时使用的路由参数。
  • routeOptions，生成当前实体链接时使用的路由选项。
• getIdFromEntity 定义了一个参数，entity，这是一个数组或对象，需要从中提取标识符。
• fromLink.pre（自 1.5.0 版本以来）定义了一个参数，linkDefinition，它是一个 Laminas\ApiTools\Hal\Link\Link 实例。这通常在 Laminas\ApiTools\Rest\RestController::create() 中有用，当你可能想要操纵自我关联的链接以生成 Link 标头时。

监听器

Laminas\ApiTools\Hal\Module::onRender

此监听器附加到 MvcEvent::EVENT_RENDER，优先级为 100。如果控制器服务结果为 HalJsonModel，则此监听器以优先级 200 将 Laminas\ApiTools\Hal\JsonStrategy 附加到视图。

Laminas 服务

模型

Laminas\ApiTools\Hal\Collection

Collection 负责将一般集合建模为 HAL 集合，并组成关系链接。

Laminas\ApiTools\Hal\Entity

Entity 负责将通用实体和普通对象建模为 HAL 实体，并组成关系链接。

Laminas\ApiTools\Hal\Link\Link

Link 负责建模关系链接。`Link` 类还有一个静态 factory() 方法，可以接受一个信息数组作为参数，以生成有效的 Link 实例。

Laminas\ApiTools\Hal\Link\LinkCollection

LinkCollection 是一个负责聚合一系列 Link 实例的模型。

Laminas\ApiTools\Hal\Metadata\Metadata

Metadata 负责收集创建 HAL 实体、链接或集合所需的所有必要依赖项、填充器和其它信息。

Laminas\ApiTools\Hal\Metadata\MetadataMap

MetadataMap 聚合了一个键为类名的 Metadata 实例数组，用于生成 HAL 实体、链接或集合。

提取器

Laminas\ApiTools\Hal\Extractor\LinkExtractor

LinkExtractor 负责从 Link 实例中提取链接表示。

Laminas\ApiTools\Hal\Extractor\LinkCollectionExtractor

LinkCollectionExtractor 负责提取一系列 Link 实例。它还组成一个 LinkExtractor 以提取单个链接。

控制器插件

Laminas\ApiTools\Hal\Plugin\Hal（又称“Hal”）

此类既作为视图助手也作为控制器插件运行。它负责为控制器提供生成 HAL 数据模型、渲染关系链接和 HAL 数据结构的工具。

视图层

Laminas\ApiTools\Hal\View\HalJsonModel

HalJsonModel 是一个视图模型，当它作为控制器服务响应的结果使用时，表示向 api-tools-hal 模块表明模型内部的数据应被用于生成 JSON HAL 表示。

Laminas\ApiTools\Hal\View\HalJsonRenderer

HalJsonRenderer 是一个视图渲染器，负责渲染 HalJsonModel 实例。反过来，这个渲染器将调用 Hal 插件/视图辅助器，以便将模型内容（一个 Entity 或 Collection）转换成 HAL 表示。

Laminas\ApiTools\Hal\View\HalJsonStrategy

HalJsonStrategy 负责在识别到控制器服务响应为 HalJsonModel 时选择 HalJsonRenderer。