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 服务将被 Hal 插件用作默认 hydrator，如果实体类未配置 hydrator，则将使用该 hydrator。
• render_embedded_entities - 布尔值，默认 true，用于在 HAL 响应中渲染完整的嵌入式实体；如果为 false，嵌入式实体将仅包含它们的关联链接。
• render_embedded_collections - 布尔值，默认为 true，用于在 HAL 响应中渲染集合；如果为 false，则仅渲染集合的关联链接。
• hydrators - 一个映射，将实体类名映射到 Hal 插件在实体补水时可以使用的补水服务名称。

键： metadata_map

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

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

• entity_identifier_name - 用于标识符的类属性名称（在序列化之后）。
• route_name - 用于生成集合或实体 self 关联链接的路由名称。
• route_identifier_name - 路由中使用的标识符名称，它将在 URI 路径中表示实体标识符。这通常与 entity_identifier_name 不同，因为路由中的每个变量段都必须有一个唯一的名称。
• 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 - 布尔值；当您使用代理时设置为 true（用于使用 HTTP_X_FORWARDED_PROTO、HTTP_X_FORWARDED_HOST 和 HTTP_X_FORWARDED_PORT 而不是 SSL_HTTPS、HTTP_HOST, SERVER_PORT）。

系统配置

以下配置存在以确保此模块在基于 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。