Download the PHP package zfcampus/zf-apigility-admin without Composer
On this page you can find all versions of the php package zfcampus/zf-apigility-admin. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package zf-apigility-admin
Apigility Admin
Repository abandoned 2019-12-31
This repository has moved to laminas-api-tools/api-tools-admin.
Introduction
The zf-apigility-admin
module delivers the backend management API and frontend Admin UI used to
manage APIs in Apigility.
NOTE
DO NOT enable this module in production systems.
Requirements
Please see the composer.json file.
Installation
Run the following composer
command:
And then run composer install
to ensure the module is installed.
Finally, add the module name to your project's config/application.config.php
under the modules
key:
Typically, this module should be used along with
zf-development-mode in order to conditionally
enable the module in your application. When doing so, you will add the module to your project's
config/development.config.php.dist
file instead of the config/application.config.php
file, and
enable it via php public/index.php development enable
.
Upgrading
We strive to make upgrading as simple as a composer update
; however, from time
to time, there may be other steps involved. This section documents those.
Initial upgrade to 1.5
If you are upgrading to version 1.5 or higher from a pre-1.5 version, there are a few changes to be aware of.
First, version 1.5 drops the requirement for rwoverdijk/assetmanager. However, in order to use the admin UI, you will need some way to access the public assets provided by the UI and zf-apigility modules. You have three options:
-
Install rwoverdijk/assetmanager:
composer require rwoverdijk/assetmanager
. Be aware, however, that as of the time of the 1.5.0 release, this module is not compatible with v3 releases of zend-mvc. If you are looking for a quick upgrade, and do not care what versions of Zend Framework components you install, this is the easiest path. -
Install zf-asset-manager. This is a Composer plugin, and operates when installing or uninstalling a package. If you add this, you will need to follow these steps:
composer require --dev zfcampus/zf-asset-manager
rm -Rf ./vendor
composer install
-
The additional steps are necessary in order for the plugin to pick up on the assets from the other components.
-
Manually copy or symlink in the assets required to your public directory. As examples:
ln -s vendor/zfcampus/zf-apigility/asset/zf-apigility public/zf-apigility
ln -s vendor/zfcampus/zf-apigility-admin-ui/dist/apigility-ui public/apigility-ui
Each of the three will accomplish the goal of making the assets publicly available via your application's web server.
Upgrading to v3 Zend Framework components from 1.5
After upgrading to version 1.5 of this module, you can then upgrade your application to take advantage of Zend Framework v3 components. The easiest way to do that is to use the provided script:
This script will update your Composer requirements and constraints, update your modules list to list ZF components and remove unneeded/obsolete components, and then re-install all dependencies.
If you do not wish to use the script, or the script fails, you may manually update your application using the following steps:
- Update your
composer.json
:- Remove:
require.zendframework/zendframework
require.rwoverdijk/assetmanager
require-dev.zendframework/zftool
- Update:
require.zfcampus/zf-development-mode
constraint becomes^3.0
require-dev.zendframework/zend-developer-tools
becomes^1.0
- Add:
require.zendframework/zend-cache
, with a constraint of2.7.1
require.zendframework/zend-log
, with a constraint of2.9
require.zendframework/zend-mvc-i18n
, with a constraint of1.0
require-dev.zfcampus/zf-asset-manager
, with a constraint of^1.0
- Update your
config/modules.config.php
:- Remove:
AssetManager
ZF\DevelopmentMode
- Add, at the top of the list:
Zend\Cache
Zend\Db
Zend\Filter
Zend\Hydrator
Zend\InputFilter
Zend\I18n
Zend\Log
Zend\Mvc\I18n
Zend\Paginator
Zend\Router
Zend\Validator
- Update your
config/development.config.php
andconfig/development.config.php.dist
files:- Remove from the modules list:
ZFTool
- Remove
composer.lock
- Remove, recursively, the
vendor/
subdirectory - Execute
composer install
Development Mode
Prior to 1.5 and running the upgrade script or following the upgrade instructions from above, Apigility used zf-development-mode v2 releases, which relied on the Console <-> MVC integration present by default in zend-mvc v2 releases.
zf-development-mode v3 operates differently, however, and instead ships as a Composer vendor binary, with no additional requirements. Invocation is now:
and
You can also query for status:
Configuration
Since this particular module is responsible for providing APIs and the Apigility Admin UI, it has a significant amount of configuration that it requires in order to function in a development environment. Since it is highly unlikely that developers would need to modify the system-level configuration, it is omitted in this README, but can be found within the repository.
Additionally, the module defines the following module-specific configuration,
under the top-level key zf-apigility-admin
:
Key: path_spec
By default, zf-apigility-admin will create new Apigility modules using
PSR-0 directory structure. You can switch
to PSR-4 using the
zf-apigility-admin.path_spec
configuration, which accepts one of the following
values:
ZF\Apigility\Admin\Model\ModulePathSpec::PSR_0
('psr-0')ZF\Apigility\Admin\Model\ModulePathSpec::PSR_4
('psr-4')
Routes
This module exposes HTTP accessible API endpoints and static assets.
API Endpoints
All routes are prefixed with /apigility
by default.
api/apigility-version
- Since 1.5.1
Returns the current Apigility version if it can be discovered, and the string
@dev
otherwise. The payload is in the version
key:
-
Accept
:application/json
-
Content-Type
:application/json
-
Methods:
GET
- Errors: none
api/config
This endpoint is for examining the application configuration, and providing
overrides of individual values in it. All overrides are written to a single
file, config/autoload/development.php
; you can override that location in your
configuration via the zf-configuration.config-file
key.
-
Accept
:application/json
,application/vnd.zfcampus.v1.config+json
application/json
will deliver representations as a flat array of key/value pairs, with the keys being dot-separated values, just as you would find in INI.application/vnd.zfcampus.v1.config+json
will deliver the configuration as a tree. -
Content-Type
:application/json
,application/vnd.zfcampus.v1.config+json
application/json
indicates you are sending key/value pairs, with keys being dot-separated values, as you would find in INI files.application/vnd.zfcampus.v1.config+json
indicates you are sending a nested array/object of configuration. -
Methods:
GET
,PATCH
- Errors:
application/problem+json
api/config/module?module={module name}
This operates exactly like the api/config
endpoint, but expects a known
module name. When provided, it allows you to introspect and manipulate the
configuration file for that module.
api/authentication
This REST endpoint is for creating, updating, and deleting the authentication configuration for your application. It uses the authentication resource.
-
Accept
:application/json
Returns an authentication resource on success.
-
Content-Type
:application/json
Expects an authentication resource with all details necessary for creating new, or updating existing, HTTP authentication.
-
HTTP methods:
GET
,POST
,PATCH
,DELETE
GET
returns a404
response if no authentication has previously been setup.POST
will return a201
response on success.PATCH
will return a200
response on success.DELETE
will return a204
response on success. - Errors:
application/problem+json
api/authentication[/:authentication_adapter] (API V2)
This REST endpoint is for fetching and updating the authentication adapters to be used in Apigility. It uses the authentication resource ver. 2.
This endpoint is only available for API version 2. You need to pass the following mediatype in the Appect header:
-
Accept
:application/json
Returns an authentication resource ver. 2 on success.
-
Content-Type:
application/json
Expects an authentication resource ver. 2 with all details necessary for creating new, or updating existing, HTTP authentication.
-
HTTP methods:
GET
,POST
,PUT
,DELETE
GET
returns a404
response if no authentication adapter has previously been setup.POST
will return a201
response on success.PUT
will return a200
response on success.DELETE
will return a204
response on success.
api/module/:name/authentication?version=:version (API V2)
This REST endpoint is for fetching and updating the authentication mapping for a specific API (module) and version, if specified.
This endpoint is only available for API version 2. You need to pass the following mediatype in the Appect header:
-
Accept
:application/json
Returns an { "authentication" : value } on success.
-
Content-Type:
application/json
Expects a JSON with authentication value containing the authentication adapter name.
-
HTTP methods:
GET
,PUT
,DELETE
GET
will return an { "authentication" : value } response. If no authentication adapter exists the value will be false.PATCH
will return a200
response on success, along with the updated authentication value.DELETE
will return a204
response on success.
api/module/:name/authorization?version=:version
This REST endpoint is for fetching and updating the authorization configuration for your application. It uses the authorization resource.
-
Accept
:application/json
Returns an authorization resource on success.
-
Content-Type:
application/json
Expects an authorization resource with all details necessary for specifying authorization rules.
-
HTTP methods:
GET
,PATCH
GET
will always return an entity; if no configuration existed previously for the module, or if any given service at the given version was not listed in the configuration, it will provide the default values.PATCH
will return a200
response on success, along with the updated entity. - Errors:
application/problem+json
api/db-adapter[/:adapter_name]
This REST endpoint is for creating, updating, and deleting named Zend\Db
adapters; it uses the db-adapter resource.
-
Accept
:application/json
Returns a db-adapter resource on success.
-
Content-Type
:application/json
Expects db-adapter resource with all details necessary for creating or updating a DB connection.
-
Collection Methods:
GET
,POST
-
Resource Methods:
GET
,PATCH
,DELETE
- Errors:
application/problem+json
api/module.enable
This endpoint will Apigility-enable (Apigilify?) an existing module.
-
Accept
:application/json
Returns a Module resource on success.
-
Content-Type
:application/json
Expects an object with the property "module" describing an existing ZF2 module.
-
Methods:
PUT
- Errors:
application/problem+json
The request payload should hav ethe following structure:
api/validators
This endpoint provides a sorted list of all registered validator plugins; the
use case is for building a drop-down of available plugins when creating an
input filter for a service. Any validator present in the ZF2 ValidatorPluginManager
service will be represented.
-
Accept
:application/json
Returns an
application/json
response on success. -
Methods:
GET
- Errors:
application/problem+json
The response payload for a successful request has the following format:
api/versioning
This endpoint is for adding a new version to an existing API. If no version is passed in the payload, the version number is simply incremented.
-
Accept
:application/json
Returns a JSON structure on success, an API-Problem payload on error.
-
Content-Type
:application/json
Expects an object with the property "module", providing the name of a ZF2, Apigility-enabled module; optionally, a "version" property may also be provided to indicate the specific version string to use.
-
Methods:
PATCH
- Errors:
application/problem+json
The request payload should have the following structure:
On success, the service returns the followings structure:
api/module[/:name]
This is the canonical endpoint for Module resources.
-
Accept
:application/json
Returns either a single Module resource (when a
name
is provided) or a collection of Module resources (when noname
is provided) on success. -
Content-Type
:application/json
Expects an object with the property "name" describing the module to create.
-
Collection Methods:
GET
,POST
-
Resource Methods:
GET
- Errors:
application/problem+json
When creating a new API module, use the following request payload:
api/module/:name/rpc[/:controller_service_name]
This is the canonical endpoint for RPC resources.
-
Accept
:application/json
Returns either a single RPC resource (when a
controller_service_name
is provided) or a collection of RPC resources (when nocontroller_service_name
is provided) on success. -
Content-Type
:application/json
Expects an object with the property "service_name" describing the endpoint to create.
You may also provide any other options listed in the RPC resource.
-
Collection Methods:
GET
,POST
-
Resource Methods:
GET
,PATCH
-
The query string variable
version
may be passed to the collection to filter results by version: e.g.,/admin/api/module/:name/rpc?version=2
. - Errors:
application/problem+json
The minimal request payload necessary will have the following structure:
api/module/:name/rpc/:controller_service_name/inputfilter[/:input_filter_name]
This service is for creating, updating, and deleting named input filters associated with a given RPC service.
-
Accept
:application/json
Returns either a single input filter (when an
input_filter_name
is provided) or a collection of input filters (when noinput_filter_name
is provided) on success. Typically, only one input filter will be associated with a given RPC service.Input filters returned will also compose a property
input_filter_name
, which is the identifier for the given input filter. -
Content-Type
:application/json
Expects an input filter.
-
Collection Methods:
GET
,POST
-
Resource Methods:
GET
,PUT
,DELETE
- Errors:
application/problem+json
api/module/:name/rest[/:controller_service_name]
This is the canonical endpoint for REST resources.
Can be used for any type of REST resource, including DB-Connected.
DB-Connected resources expect the following additional properties (and will return them as well):
adapter_name
: A named DB adapter service.table_name
: The database table associated with this service.hydrator_name
: Optional; the name of a hydrator service used to hydrate rows returned by the database; defaults toArraySerializable
.-
table_service
: Optional; this is auto-generated by default, but an alternate TableGateway service may be provided. -
Accept
:application/json
Returns either a single REST resource (when a
controller_service_name
is provided) or a collection of REST resources (when nocontroller_service_name
is provided) on success. -
Content-Type
:application/json
Expects an object with the property
resource_name
describing the REST service to create.You may also provide any other options listed in the REST resource.
-
Collection Methods:
GET
,POST
,DELETE
-
Resource Methods:
GET
,PATCH
-
The query string variable
version
may be passed to the collection to filter results by version: e.g.,/admin/api/module/:name/rest?version=2
. - Errors:
application/problem+json
The minimum structure for creating a new REST service will appear as follows:
api/package
This endpoint is for building a deploy package for APIs.
-
Accept
:application/json
Returns a JSON structure on success, an API-Problem payload on error.
-
Content-Type
:application/json
Expects an object with the property "format", for the file format ZIP, TAR, TGZ, and ZPK; an "apis" property with a list of the API to include in the package; a "composer" property that specify if execute composer or not and an optional "config" property containing the path to an application config folder to be used in the package.
-
Methods:
GET
,POST
- Errors:
application/problem+json
The request payload for POST
should have the following structure:
On success, the service returns the followings structure:
The fields of this response can be used in the GET
method to download
the package file. Basically, the token is a temporary file name stored in
the system temporary folder (/tmp
in GNU/Linux).
The request payload for GET
should have the following structure:
On success, the service returns the file as application/octet-stream
content type.
API Models
The following is a list of various models either returned via the API endpoints listed above, or expected for the request bodies.
authentication
HTTP Basic authentication:
HTTP Digest authentication:
OAuth2 authentication:
authentication2
HTTP Basic authentication:
HTTP Digest authentication:
OAuth2 authentication (with PDO):
OAuth2 authentication (with MongoDB):
authorization
REST services have an entry for each of their entity and collection instances.
RPC services have an entry per action name that is exposed (this will typically
only be one). Each service has a list of HTTP methods, with a flag. A false
value indicates that no authorization is required; a true
value indicates that
authorization is required.
Note: If the
deny_by_default
flag is set in the application, then the meaning of the flags is reversed;true
then means the method is public,false
means it requires authentication.
db-adapter
Additionally, any other properties used to create the Zend\Db\Adapter\Adapter
instance may be composed: e.g., "username", "password", etc.
inputfilter
An input filter may contain any number of inputs, and the format follows that
used by Zend\InputFilter\Factory
as described in the [Zend Framework 2 input filter documentation]
(http://framework.zend.com/manual/2.3/en/modules/zend.input-filter.intro.html).
Currently, we do not allow nesting input filters.
module
Additionally, the module
resource composes relational links for RPC
and REST resources; these use the relations "rpc" and "rest",
respectively.
rpc
rest
ZF2 Events
Listeners
ZF\Apigility\Admin\Module
This listener is attached to MvcEvent::EVENT_RENDER
at priority 100
. It is responsible for
conditionally attaching a listener depending on if the controller service result is that of
an entity or that of a collection. If either is detected, the listener is attached
to the ZF\Hal\Plugin\Hal
events renderEntity
and renderCollection.entity
, which
ensures they will be dispatched when the HAL plugin has an opportunity to start rendering.
ZF2 Services
Models
Many of the model services provided by zf-apigility-admin
either deal with the generation and
modification of PHP code, or the generation and modification of PHP based configuration files.
ZF\Apigility\Admin\Model\AuthenticationModel
- responsible for creating and modifying the authentication specific configuration of HTTP Basic, HTTP Digest and OAuth2 strategies. Sensitive information will be written to local configuration files while structural information is written to global and module files.ZF\Apigility\Admin\Model\AuthorizationModelFactory
- responsible for writing the authorization specific details (the ACL matrix of allow/disallow rules) to the module configuration file.ZF\Apigility\Admin\Model\ContentNegotiationModel
- responsible for writing custom content-negotiation selectors to the global configuration file.ZF\Apigility\Admin\Model\ContentNegotiationResource
- REST resource that consumes theContentNegotiationModel
in order to expose an API endpoint for content-negotiation configuration management.ZF\Apigility\Admin\Model\DbAdapterModel
- responsible for writing database adapter specific configuration between application level global and local configuration files. Sensitive information is written to local configuration files.ZF\Apigility\Admin\Model\DbAdapterResource
- REST resource that consumes theDbAdapterModel
in order to expose an API endpoint for database adapter configuration management.ZF\Apigility\Admin\Model\DbConnectedRestServiceModel
- responsible for writing the required configuration information necessary to expose a database table as a REST resource.ZF\Apigility\Admin\Model\DocumentationModel
- responsible for writing a special named file in the module's configuration directory that will contain all custom API documentation for requests, responses, and all other documentable elements of an API.ZF\Apigility\Admin\Model\InputFilterModel
- responsible for writing the input filter specification configuration for each module.ZF\Apigility\Admin\Model\FiltersModel
- responsible for providing, through the API, a list of built-in filters and their metadata.ZF\Apigility\Admin\Model\HydratorsModel
- responsible for configuring and managing the global list of hydrator service names.ZF\Apigility\Admin\Model\ModuleModel
- responsible for aggregating module information including REST and RPC services and exposing this information through the API. Additionally, when creating a new module, this will create the code artifacts necessary for an Apigility-enabled module.ZF\Apigility\Admin\Model\ModuleResource
- responsible for exposing theModuleModel
as a REST resource in the Apigility API.ZF\Apigility\Admin\Model\RestServiceModel
- responsible for presenting REST services, as they are defined inzf-rest
in a way that can be created and modified, to be used in the Admin UI.ZF\Apigility\Admin\Model\RestServiceResource
- responsible for consumingRestServiceModel
and exposing this model as a REST resource in the Apigility API.ZF\Apigility\Admin\Model\RestServiceModelFactory
- responsible for creatingRestServiceModel
s.ZF\Apigility\Admin\Model\RpcServiceModel
- responsible for presenting RPC services, as they are defined inzf-rpc
in a way that can be created and modified, to be used in the Admin UI.ZF\Apigility\Admin\Model\RpcServiceResource
- responsible for consumingRpcServiceModel
s and exposing this model as a REST resource in the Apigility API.ZF\Apigility\Admin\Model\RpcServiceModelFactory
- responsible for creatingRpcServiceModel
s.ZF\Apigility\Admin\Model\ValidatorsModel
- responsible for providing, through the API, a list of available validators.ZF\Apigility\Admin\Model\ValidatorMetadataModel
- responsible for providing metadata about validators provided through, and in conjunction with, theValidatorModel
and validator API.ZF\Apigility\Admin\Model\VersioningModel
- responsible for modeling the workflow and module code creation artifacts that are required to provide a new version of a particular Apigility-based REST or RPC service.ZF\Apigility\Admin\Model\ModuleVersioningModelFactory
- responsible for creatingModuleVersioningModel
s.
All versions of zf-apigility-admin with dependencies
zendframework/zend-code Version ^2.6.3 || ^3.2
zendframework/zend-eventmanager Version ^2.6.3 || ^3.0.1
zendframework/zend-filter Version ^2.8
zendframework/zend-http Version ^2.8
zendframework/zend-hydrator Version ^1.1 || ^2.4 || ^3.0
zendframework/zend-inputfilter Version ^2.8.1
zendframework/zend-modulemanager Version ^2.8.2
zendframework/zend-mvc Version ^2.7.15 || ^3.1.1
zendframework/zend-servicemanager Version ^2.7.10 || ^3.3.2
zendframework/zend-stdlib Version ^2.7.7 || ^3.2
zendframework/zend-validator Version ^2.10.2
zendframework/zend-view Version ^2.10
zfcampus/zf-apigility Version ^1.4
zfcampus/zf-apigility-admin-ui Version ^1.3.9
zfcampus/zf-apigility-provider Version ^1.3
zfcampus/zf-api-problem Version ^1.3
zfcampus/zf-configuration Version 1.3.3
zfcampus/zf-content-negotiation Version ^1.4
zfcampus/zf-content-validation Version ^1.4
zfcampus/zf-hal Version ^1.5
zfcampus/zf-oauth2 Version ^1.5
zfcampus/zf-mvc-auth Version ^1.5
zfcampus/zf-rest Version ^1.4
zfcampus/zf-rpc Version ^1.4
zfcampus/zf-versioning Version ^1.3