README

仓库弃用 2019-12-31

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

简介

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

要求

请参阅 composer.json 文件。

安装

运行以下 composer 命令

$ composer require zfcampus/zf-hal

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

"require": {
    "zfcampus/zf-hal": "^1.4"
}

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

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

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

zf-component-installer

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

配置

用户配置

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

键: renderer

这是一个配置数组，用于配置 zf-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 - 布尔值；当使用代理时设置为 true（用于使用 HTTP_X_FORWARDED_PROTO、HTTP_X_FORWARDED_HOST 和 HTTP_X_FORWARDED_PORT 而不是 SSL_HTTPS、HTTP_HOST, SERVER_PORT）。

系统配置

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

// Creates a "HalJson" selector for use with zfcampus/zf-content-negotiation
'zf-content-negotiation' => [
    'selectors' => [
        'HalJson' => [
            'ZF\Hal\View\HalJsonModel' => [
                'application/json',
                'application/*+json',
            ],
        ],
    ],
],

ZF2 事件

事件

ZF\Hal\Plugin\Hal 事件管理器

ZF\Hal\Plugin\Hal 在其生命周期中触发几个事件。从集成到 HAL 插件中的 EventManager 实例，您可以订阅以下事件

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

例如，您可以通过以下方式监听 renderEntity 事件（以下是在 ZF2 模块和/或 Apigility 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(\ZF\Hal\Link\Link::factory([
            'rel' => 'describedBy',
            'route' => [
                'name' => 'my/api/docs',
            ],
        ]));
    }
}

有关单个事件的说明

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

监听器

ZF\Hal\Module::onRender

此监听器连接到 MvcEvent::EVENT_RENDER，优先级为 100。如果控制器服务结果为 HalJsonModel，则此监听器将 ZF\Hal\JsonStrategy 连接到视图，优先级为 200。

ZF2 服务

模型

ZF\Hal\Collection

Collection 负责将通用集合建模为 HAL 集合，并组合关系链接。

ZF\Hal\Entity

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

ZF\Hal\Link\Link

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

ZF\Hal\Link\LinkCollection

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

ZF\Hal\Metadata\Metadata

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

ZF\Hal\Metadata\MetadataMap

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

提取器

ZF\Hal\Extractor\LinkExtractor

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

ZF\Hal\Extractor\LinkCollectionExtractor

LinkCollectionExtractor 负责提取一组 Link 实例。它还组合一个 LinkExtractor 来提取单个链接。

控制器插件

ZF\Hal\Plugin\Hal (俗称 "Hal")

该类同时作为视图辅助工具和控制器插件运行。它负责为控制器提供生成 HAL 数据模型以及渲染关联链接和 HAL 数据结构的便利。

视图层

ZF\Hal\View\HalJsonModel

HalJsonModel 是一个视图模型，当作为控制器服务响应的结果时，表示给 zf-hal 模块，模型中的数据应被用来生成 JSON HAL 表示。

ZF\Hal\View\HalJsonRenderer

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

ZF\Hal\View\HalJsonStrategy

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