Apigility 1.4 Released!

We are pleased to announce the immediate availability of Apigility 1.4.0!

This is our first minor release in over a year, and our largest, feature-wise,
to date!

Zend Framework 3 Support

Six weeks ago, we announce Zend Framework 3 availablility.
Our efforts since then have been focused on making all Apigility modules
forwards compatible with version 3 releases of Zend Framework components. This
touched on every Apigility component, and required the addition of a couple new
components as well to help with migration.

This update also means that Apigility has adopted the same minimum supported PHP
version as Zend Framework itself: 5.6. If you are using an earlier version of
PHP, we recommend updating as soon as possible, as earlier versions are no
longer supported by the PHP project.

The main takeaway to know is: you can upgrade your existing Apigility
applications now, and they will continue to work, albeit with a number of
bugfixes and new features!

Upgrade script

Additionally, once you’ve verified your application is working, we have provided
a script to update your application to take advantage of Zend Framework v3
components and reduce the overall dependency footprint of your application!

$ ./vendor/bin/apigility-upgrade-to-1.5

(The 1.5 here refers to the internal version of the zf-apigility-admin
module, in which this script is defined.)

Once you’ve run that script, you will be pinned to version 3 Zend Framework
component releases, and no longer have a dependency on the full ZF metapackage.

There are other things you can do as well to modernize your application, and we
have created a comprehensive migration document for 1.4
detailing the changes.

New Apigility skeleton

We decided to mondernize the Apigility skeleton in the same way that we updated
the Zend Framework skeleton application. In particular:

  • Adopting PSR-4 directory structure for
    the shipped Application module.
  • Providing unit tests for the shipped Application module.
  • Removal of i18n features.
  • Enabling PSR-4 Apigility module structure by default.
  • Enabling usage of short array syntax in Apigility-generated configuration
    files by default.
  • Enabling usage of ::class notation in Apigility-generated configuration
    files by default.
  • Usage of zfcampus/zf-asset-manager
    for asset management by default.
  • Addition of zfcampus/zf-composer-autoloading
    as a development requirement, to facilitate enabling Composer-based
    autoloading of your Apigility (or Zend Framework) modules.
  • Addition of zendframework/zend-component-installer,
    to automate registration of ZF components and modules with Apigility
    applications.
  • Addition of several Composer scripts for working with development mode,
    serving your application via the PHP built-in web server, and running QA
    tools.
  • New vagrant and docker-compose configuration based on Ubuntu 16.04 and PHP 7.

The new skeleton updates Apigility applications to use modern approaches to PHP
application structure, and provides better tooling around usage of virtual
machines and containers in the development workflow.

Improvements

This release wraps new releases of every Apigility module. Notable features of
these modules include:

  • zf-apigility

    • Support in ZFApigilityApplication for handling PHP 7 Throwables.
  • zf-apigility-admin

    • Extracts all factories defined in the Module class to their own classes.
    • Extracts all listeners defined in the Module class to their own classes.
    • Adds a patchList() stub to the REST resource class template, so that it is
      present by default.
    • Adds support for working with modules using PSR-4 directory format, and the
      ability to generate PSR-4-style modules.
    • Adds a vendor script, apigility-upgrade-to-1.5, for upgrading an existing
      Apigility application so that it may use Zend Framework component v3
      releases.
    • Adds the ability to generate all configuration files using short array
      syntax and ::class notation.
    • Adds a new API endpoint for reporting the current Apigility skeleton
      version.
  • zf-apigility-admin-ui

    • Displays the current Apigility skeleton version as returned by the
      zf-apigility-admin API.
    • Uses full controller service names when interacting with the
      zf-apigility-admin API; this resolves some lingering UI issues due to
      version mismatch.
    • Adds a "field type" input to new field entries, allowing you to provide this
      information via the UI (previously the information could only be provided
      by manually updating configuration files). This allows communicating field
      type information to documentation systems such as Swagger.
    • Numerous UI fixes, particularly with regards to sidebar behavior.
  • zf-apigility-documentation

    • Adds support for displaying documentation of APIs in nested PHP namespaces.
    • Adds support for transforming Markdown documentation to HTML, and enables it
      by default.
    • Displays field types, if provided, by default.
  • zf-apigility-provider

    • Deprecates the Module class. You no longer need to list the
      ZFApigilityProvider module in your application module configuration.
  • zf-configuration

    • Adds a new configuration switch, zf-configuration.class_name_scalars,
      allowing you to configure whether or not generated configuration will use
      ::class notation.
  • zf-console

    • Adds the ability to substitute your own dispatcher via the
      ZFConsoleDispatcherInterface
    • Adds the ability to disable output of the application banner.
    • Adds the ability to compose a container-interop container with the
      dispatcher, which allows providing service names as console handlers.
    • The exception handler now catches PHP 7 Throwable instances as well.
  • zf-content-validation

    • Adds support for mapping input filters to GET requests. This feature is not
      yet supported in the admin UI, however.
  • zf-hal

    • Adds an interface, concrete classes, and configuration for allowing
      alternate "self" and generic link generation strategies. As such, usage of
      the server url and url helpers with the Hal plugin is now deprecated.
    • Adds service factories for the two link extraction services, allowing the
      ability to provide alternate facilities if needed.
    • Adds a new method to the Hal plugin, resetEntityHashStack(); this can be
      used when rendering multiple responses or payloads within the same request
      cycle to allow re-use of the same entity instances.
  • zf-http-cache

    • Adds ETag support, with configurable hashing.
    • Adds more capabilities aroudn matching routed controllers.
  • zf-oauth2

    • Adds support for the ext/mongodb extension.
    • Adds token revocation suport.

New modules

Two new modules were added to Apigility:

  • zfcampus/zf-asset-manager
    uses configuration from rwoverdijk/assetmanager to expose asset directories
    in the document root of your application. It acts as a Composer plugin, and
    copies configured asset directories under your public/ directory, adding an
    entry to that directory’s .gitignore file to prevent checking those files
    into version control. Updates to modules are honored, and removal of a module
    will remove the files from your source tree.
  • zfcampus/zf-composer-autoloading
    will add an autoloading entry to your Composer configuration for the module
    you specify, and then update autoloading rules locally. This package can be
    used with any Zend Framework application!

Doctrine support

At this time, Doctrine support for Apigility has not yet been updated.
Contributors and collaborators are working with the Doctrine team to ensure the
various Zend Framework modules they maintain are updated to work with Zend
Framework component v3 releases, while working in parallel on
zf-apigility-doctrine and zf-doctrine-querybuilder. We hope to announce support
for these in the next few weeks.

Upgrading to the latest versions of Apigility modules, however, should allow you
to continue using Doctrine features; you will simply be constrained to Zend
Framework component v2 releases.

Thank You!

We had a number of contributors to this release, but wish to call out two
individuals in particular:

  • Adam Grabek provided the initial pull requests
    implementing Zend Framework v3 support for around a half-dozen or more
    modules, and maintained a checklist monitoring progress.
  • Michal (webimpress) Bundyra provided a number
    of compatibility patches, bugfixes, features, and, most notably, innumerable
    hours of testing and collaboration towards finalizing the skeleton changes.

To everyone who has contributed patches, features, feedback, and documentation:
thank you!

Source: Zend feed