Laminas API Tools in 2026: Keep, Freeze, or Replace (and How to Document APIs Either Way)

Laminas API Tools in 2026: Keep, Freeze, or Replace (and How to Document APIs Either Way)

Your API works. The question is how long you can maintain the framework behind it.

Laminas API Tools (the project formerly known as Apigility) gave PHP teams a structured way to build REST and RPC APIs on top of Laminas MVC. The admin interface, the content negotiation, the HAL support, the OAuth2 integration, and the built-in documentation generator made it possible to ship an API quickly with conventions that covered the boring parts.

In 2026, the maintenance picture for API Tools is uncertain. The admin interface has not kept pace with modern PHP. Some of the underlying packages have limited maintainer bandwidth. If you are running API Tools in production, you need a plan, and that plan starts with an honest assessment of three options: keep it running, freeze it in place, or replace it.

Assessing Your Current API Tools Installation

Before deciding, understand what you actually use. Laminas API Tools is not a single package. It is a collection of modules:

  • api-tools-admin - the web-based admin interface for managing API resources
  • api-tools-rest - the REST resource abstraction layer
  • api-tools-rpc - the RPC endpoint abstraction
  • api-tools-hal - HAL+JSON response formatting
  • api-tools-content-negotiation - content type handling
  • api-tools-oauth2 - OAuth2 server integration
  • api-tools-documentation - auto-generated API documentation
  • api-tools-content-validation - input filter integration

Most production API Tools applications use the REST and RPC modules heavily but may have abandoned the admin interface after initial setup. Some use HAL formatting while others return plain JSON. Some depend on the OAuth2 module while others use a custom authentication layer.

Map your actual dependency surface. The modules you actively rely on determine which path makes sense.

Option 1: Keep Running

When this makes sense:

  • Your API is stable with infrequent changes
  • You have developers who understand the API Tools internals
  • The modules you depend on are compatible with your target PHP version
  • You are willing to patch issues yourself when they arise

What “keep running” requires:

  • Pin all API Tools packages to their current versions in composer.lock
  • Test against each PHP version upgrade before deploying
  • Monitor the API Tools GitHub repositories for community patches
  • Be prepared to fork and patch individual modules if PHP compatibility breaks

The risk:
API Tools modules were built for a Laminas MVC architecture that is itself entering reduced maintenance. As the MVC layer’s maintenance status changes, the API Tools layer built on top of it inherits those risks.

Option 2: Freeze in Place

Freezing is the “keep it running” option with a hard boundary: no new API endpoints go through API Tools. New functionality goes through a separate API layer (Mezzio handlers, Slim routes, or a standalone microservice). The existing API Tools endpoints remain operational but receive no feature changes.

When this makes sense:

  • You need to add new API endpoints but do not want to invest in API Tools for them
  • The existing API surface is stable and well-documented
  • You have a longer-term plan to migrate away from API Tools entirely
  • The team is building new services in a different stack

What freezing requires:

  • Document every existing API endpoint thoroughly (see the documentation section below)
  • Set up monitoring for the frozen endpoints so you know immediately when something breaks
  • Establish a reverse proxy or routing configuration that sends new paths to the new stack and old paths to the API Tools application
  • Accept that the frozen endpoints will eventually need migration or retirement

The practical pattern:
Put Nginx or Apache in front of both applications. Route /api/v1/* to the API Tools application and /api/v2/* to the new stack. This is the same strangler pattern described in the Modernising Zend Framework Applications guide, applied to an API boundary.

Option 3: Replace

Replacing API Tools means migrating your API endpoints to a different framework or approach. The most common targets in 2026 are:

Mezzio with Custom Handlers

Mezzio’s PSR-15 pipeline is a natural fit for API development. Each endpoint becomes a handler that receives a ServerRequest and returns a Response. Content negotiation, authentication, and validation become middleware.

The migration path from an API Tools REST resource to a Mezzio handler is mechanical:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// API Tools resource (before)
class UserResource extends AbstractResourceListener
{
    public function fetchAll($params = [])
    {
        return $this->userRepository->findAll($params);
    }
}

// Mezzio handler (after)
class UserListHandler implements RequestHandlerInterface
{
    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        $params = $request->getQueryParams();
        $users = $this->userRepository->findAll($params);
        return new JsonResponse(['data' => $users]);
    }
}

The business logic is identical. The framework ceremony changes.

API Platform (Symfony-Based)

If your team is moving toward the Symfony ecosystem, API Platform provides a feature-rich API development framework with OpenAPI documentation, GraphQL support, and content negotiation built in. The learning curve is steeper but the long-term maintenance picture is stronger.

Slim 4

For lightweight APIs, Slim 4 with PSR-15 middleware provides a minimal but sufficient framework. It is easy to learn, well-maintained, and has a small dependency footprint.

API Documentation: Do This Regardless of Your Path

Whatever you decide about the API Tools framework, document your API endpoints thoroughly. API Tools’ built-in documentation generator is useful but may not survive the migration. You need documentation that outlives the framework.

OpenAPI Specification

Write an OpenAPI 3.1 specification for every endpoint. This is the industry standard and every API tool, client generator, and documentation renderer supports it:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
openapi: "3.1.0"
info:
  title: "My Application API"
  version: "1.0.0"
paths:
  /api/users:
    get:
      summary: "List users"
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        "200":
          description: "User list"
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/User"

Extracting Documentation from API Tools

If you are using the API Tools admin, export the configuration before freezing or replacing. The configuration files in config/autoload/ contain your resource definitions, input filters, and content negotiation settings. These are your documentation source of truth.

For each API module, capture:

  • The HTTP methods each resource supports
  • The input filters (which validate what data the endpoint accepts)
  • The hydrator configuration (which controls the response format)
  • The route configuration (which defines the URL pattern)

Convert this into OpenAPI spec, Markdown documentation, or both. The format matters less than having it in a framework-independent location.

Contract Testing

Once you have an OpenAPI spec, use it for contract testing. Tools like Dredd or Spectator can validate that your API implementation matches the specification. This gives you a safety net for any migration: if the contract tests pass against both the old and new implementation, the migration is functionally correct.

Migration Planning

If you choose to replace, migrate one endpoint at a time, not the entire API at once.

Step 1: Document the Endpoint

Write the OpenAPI spec for the endpoint. Write contract tests.

Step 2: Implement in the New Stack

Build the handler, middleware, and response formatting in your target framework. Run the contract tests against it.

Step 3: Route to the New Implementation

Update the reverse proxy or routing configuration to send traffic for that endpoint to the new stack.

Step 4: Monitor

Compare response times, error rates, and response bodies between the old and new implementations. Use the old implementation as a reference for at least two weeks.

Step 5: Remove the Old Implementation

Once the new implementation is stable, remove the API Tools resource class, its configuration, and its tests.

HAL Considerations

If your API uses HAL+JSON formatting (which API Tools enables by default for REST resources), you need to decide whether to preserve HAL in the new stack or switch to plain JSON.

Preserve HAL if:

  • API consumers depend on _links and _embedded properties for navigation
  • You have a significant number of external consumers who have built clients around HAL
  • You want to maintain backward compatibility during migration

Switch to plain JSON if:

  • Your API consumers parse the response body directly and ignore HAL metadata
  • You are versioning the API (v2 can use a different format)
  • HAL adds complexity without value for your use case

FAQ

Can I run API Tools on PHP 8.5?
It depends on which modules you use and the specific versions. Test it. Some modules may need patches for PHP 8.5 compatibility. The Zend to Laminas Migration Checklist covers the namespace side of the transition.

Is the API Tools admin interface still useful?
For initial API design and prototyping, yes. For ongoing maintenance of a production API, most teams have moved to managing configuration files directly and using OpenAPI specs for documentation.

Can I use API Tools modules individually without the full stack?
Yes. The content negotiation and HAL modules can be used independently in any Laminas MVC or Mezzio application.

Next Steps

Start with the dependency audit. Map which API Tools modules your application actually uses. Then choose your path based on your maintenance capacity and long-term plans. Regardless of the path, invest in OpenAPI documentation now. It will pay off whether you keep, freeze, or replace.

For the broader modernisation strategy, the Modernising Zend Framework Applications guide covers the incremental approach that applies to API migrations as well as web application migrations.