ZF Apigility

Repository abandoned 2019-12-31

This repository has moved to laminas-api-tools/api-tools.

Introduction

Meta-module for Zend Framework combining features from:

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

in order to provide a cohesive solution for exposing web-based APIs.

Also features database-connected REST resources.

Requirements

Please see the composer.json file.

Installation

Run the following composer command:

$ composer require zfcampus/zf-apigility

Alternately, manually add the following to your composer.json, in the require section:

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

And then run composer update to ensure the module is installed.

Finally, add the module name to your project's config/application.config.php under the modules key:

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

zf-component-installer

If you use zf-component-installer, that plugin will install zf-apigility, and all modules it depends on, as a module in your application configuration for you.

Assets

If you are using this module along with the admin and/or the welcome screen, this module contains assets that you will need to make web accessible. For that, you have two options:

• rwoverdijk/assetmanager is a ZF module that provides advanced capabilities around web asset management, and is the original tool used by this module. At its current release (1.6.0), however, it does not support v3 components from Zend Framework. An upcoming 1.7.0 release will likely support them.
• zfcampus/zf-asset-manager is a Composer plugin that acts during installation and uninstallation of packages, copying and removing asset trees as defined using the configuration from rwoverdijk/assetmanager. To use this, however, you will need to install the plugin first, and then this module. (If you have already installed this module, remove it using composer remove zfcampus/zf-apigility.)

Configuration

User Configuration

The top-level configuration key for user configuration of this module is zf-apigility.

db-connected

db-connected is an array of resources that can be built via the TableGatewayAbstractFactory and the DbConnectedResourceAbstractFactory when required to fulfill the use case of database table-driven resource use cases. The following example enumerates all of the required and optional configuration necessary to enable this.

Example:

'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',
    ],
],

System Configuration

The following configuration is required to ensure the proper functioning of this module in Zend Framework applications, and is provided by the module:

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 Events

Listeners

ZF\Apigility\MvcAuth\UnauthenticatedListener

This listener is attached to MvcAuthEvent::EVENT_AUTHENTICATION_POST at priority 100. The primary purpose fo this listener is to override the zf-mvc-auth unauthenticated listener in order to be able to respond with an API-Problem response (vs. a standard HTTP response) on authentication failure.

ZF\Apigility\MvcAuth\UnauthorizedListener

This listener is attached to MvcAuthEvent::EVENT_AUTHORIZATION_POST at priority 100. The primary purpose of this listener is to override the zf-mvc-auth unauthorized listener in order to be able to respond with an API-Problem response (vs a standard HTTP response) on authorization failure.

ZF\Apigility\Module

This listener is attached to MvcEvent::EVENT_RENDER at priority 400. Its purpose is to conditionally attach ZF\ApiProblem\RenderErrorListener when an MvcEvent's result is a HalJsonModel or JsonModel, ensuring zf-api-problem can render a response in situations where a rendering error occurs.

ZF Services

Factories

ZF\Apigility\DbConnectedResourceAbstractFactory

This factory uses the requested name in addition to the zf-apigility.db-connected configuration in order to produce ZF\Apigility\DbConnectedResource based resources.

ZF\Apigility\TableGatewayAbstractFactory

This factory uses the requested name in addition to the zf-apigility.db-connected configuration in order to produce correctly configured Zend\Db\TableGateway\TableGateway instances. These instances of TableGateways are configured to use the proper HydratingResultSet and produce the configured entities with each row returned when iterated.

Models

ZF\Apigility\DbConnectedResource

This instance serves as the base class for database connected REST resource classes. This implementation is an extension of ZF\Rest\AbstractResourceListener and can be routed to by Apigility as a RESTful resource.