README

仓库弃用 2019-12-31

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

简介

Zend Framework的元模块，结合了以下功能

• zf-api-problem
• zf-content-negotiation
• zf-content-validation
• zf-hal
• zf-mvc-auth
• zf-rest
• zf-rpc
• zf-versioning

以提供统一的解决方案，用于公开基于Web的API。

还包含与数据库连接的REST资源。

需求

请参阅composer.json文件。

安装

运行以下composer命令

$ composer require zfcampus/zf-apigility

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

"require": {
    "zfcampus/zf-apigility": "^1.3"
}

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

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

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

zf-component-installer

如果您使用zf-component-installer，则该插件将为您在应用程序配置中安装zf-apigility及其所有依赖模块。

资源

如果您正在使用此模块与admin和/或欢迎屏幕一起使用，则此模块包含您将需要使其可访问Web的资源。为此，您有两个选项

• rwoverdijk/assetmanager是一个提供高级Web资产管理功能的ZF模块，也是此模块最初使用的工具。然而，在其当前版本（1.6.0）中，它不支持Zend Framework的v3组件。即将发布的1.7.0版本可能会支持它们。
• zfcampus/zf-asset-manager是一个Composer插件，在安装和卸载包期间执行操作，使用rwoverdijk/assetmanager配置复制和删除资源树。但是，要使用此插件，您需要首先安装插件，然后才是此模块。（如果您已经安装了此模块，请使用composer remove zfcampus/zf-apigility将其移除。）

配置

用户配置

此模块用户配置的最高级别配置键为zf-apigility。

db-connected

db-connected 是一个资源数组，可以通过 TableGatewayAbstractFactory 和 DbConnectedResourceAbstractFactory 构建，以满足数据库表驱动资源用例的需求。以下示例列举了启用此功能所需的全部和可选配置。

示例

'db-connected' => [
    /**
     * This is sample configuration for a DB-connected service.
     * Each such service requires an adapter, a hydrator, an entity, and a
     * collection.
     *
     * The TableGateway will be called "YourDBConnectedResource\Table" should
     * you wish to retrieve it manually later.
     */
    'YourDBConnectedResource' => [
        'table_service'    => 'Optional; if present, this service will be used as the table gateway',
        'resource_class'   => 'Optional; if present, this class will be used as the db-connected resource',
        'table_name'       => 'Name of DB table to use',
        'identifier_name'  => 'Optional; identifier field in table; defaults to table_name_id or id',
        'adapter_name'     => 'Service Name for DB adapter to use',
        'hydrator_name'    => 'Service Name for Hydrator to use',
        'entity_class'     => 'Name of entity class to which to hydrate',
        'collection_class' => 'Name of collection class which iterates entities; should be a Paginator extension',
    ],
],

系统配置

以下配置是确保该模块在 Zend Framework 应用程序中正常工作的必要条件，并由该模块提供。

namespace ZF\Apigility;

use Zend\Db\Adapter\AdapterAbstractServiceFactory as DbAdapterAbstractServiceFactory;
use Zend\ServiceManager\Factory\InvokableFactory;

return [
    'asset_manager' => [
        'resolver_configs' => [
            'paths' => [
                __DIR__ . '/../asset',
            ],
        ],
    ],
    'router' => [
        'routes' => [
            'zf-apigility' => [
                'type'  => 'literal',
                'options' => [
                    'route' => '/apigility',
                ],
                'may_terminate' => false,
            ],
        ],
    ],
    'service_manager' => [
        'factories' => [
            MvcAuth\UnauthenticatedListener::class => InvokableFactory::class,
            MvcAuth\UnauthorizedListener::class => InvokableFactory::class,
        ],
        'abstract_factories' => [
            DbAdapterAbstractServiceFactory::class, // so that db-connected works "out-of-the-box"
            DbConnectedResourceAbstractFactory::class,
            TableGatewayAbstractFactory::class,
        ],
    ],
];

ZF 事件

监听器

ZF\Apigility\MvcAuth\UnauthenticatedListener

此监听器在优先级 100 下连接到 MvcAuthEvent::EVENT_AUTHENTICATION_POST。此监听器的主要目的是覆盖 zf-mvc-auth 的 未认证 监听器，以便在认证失败时能够以 API-Problem 响应（而不是标准 HTTP 响应）进行响应。

ZF\Apigility\MvcAuth\UnauthorizedListener

此监听器在优先级 100 下连接到 MvcAuthEvent::EVENT_AUTHORIZATION_POST。此监听器的主要目的是覆盖 zf-mvc-auth 的 未授权 监听器，以便在授权失败时能够以 API-Problem 响应（而不是标准 HTTP 响应）进行响应。

ZF\Apigility\Module

此监听器在优先级 400 下连接到 MvcEvent::EVENT_RENDER。其目的是在 MvcEvent 的结果为 HalJsonModel 或 JsonModel 时条件性地附加 ZF\ApiProblem\RenderErrorListener，以确保 zf-api-problem 能够在渲染错误发生时渲染响应。

ZF 服务

工厂

ZF\Apigility\DbConnectedResourceAbstractFactory

此工厂除了使用请求的名称外，还使用 zf-apigility.db-connected 配置来生成基于 ZF\Apigility\DbConnectedResource 的资源。

ZF\Apigility\TableGatewayAbstractFactory

此工厂除了使用请求的名称外，还使用 zf-apigility.db-connected 配置来生成正确配置的 Zend\Db\TableGateway\TableGateway 实例。这些 TableGateway 实例配置为使用正确的 HydratingResultSet，并在迭代时为每一行返回配置的实体。

模型

ZF\Apigility\DbConnectedResource

此实例作为数据库连接的 REST 资源类的基类。此实现是 ZF\Rest\AbstractResourceListener 的扩展，并且可以被 Apigility 作为 RESTful 资源路由。