Download the PHP package fissible/drift without Composer

fissible/drift

OpenAPI drift detection and version analysis for PHP. Compares your live API routes against their spec, recommends semver bumps, and generates changelogs.

Part of the Fissible suite. Depends on: fissible/accord (reads specs via SpecSourceInterface).

Why drift detection matters

As an API evolves, its spec and its actual routes can quietly fall out of sync. A route gets added but never documented. A route gets removed but the spec still describes it. Clients that rely on the spec to understand your API get a false picture of what's actually available.

drift surfaces that gap before it causes problems. It compares the routes your application actually serves against the routes your OpenAPI spec describes, tells you exactly what has been added or removed, and recommends how to version the change — so clients always know what to expect.

Requirements

• PHP ^8.2
• OpenAPI 3.0.x spec files (YAML or JSON)
• fissible/accord ^1.0

Installation

Laravel auto-discovery

The service provider registers automatically. Console commands are registered with Artisan:

How it works

Drift enumerates your application's routes via a RouteInspectorInterface implementation and compares them against the paths defined in your OpenAPI spec. Each route is normalised to a canonical form (GET /v1/users/{param}) so that parameter names don't cause false positives.

The result is a DriftReport describing:

• Matched routes — present in both the app and the spec
• Added routes — live in the app but not yet documented
• Removed routes — in the spec but no longer served by the app

From that report, drift recommends a semver bump and generates a changelog entry.

Console commands

accord:validate

Checks for drift between your live routes and your OpenAPI spec:

Output is a table showing each route's status. Exits with a non-zero code if any drift is detected — useful in CI pipelines to catch undocumented or removed routes before they ship.

accord:version

Runs the full drift-analyse-changelog pipeline:

1. Detects drift for the given version
2. Reads the current info.version from the spec
3. Recommends a semver bump (major / minor / patch / none)
4. Confirms with you before writing any changes
5. Updates the spec's info.version in place
6. Prepends a changelog entry to CHANGELOG.md

When drift introduces breaking changes (removed routes), the command also notes that a new URI version (/v2/) should be considered.

drift:coverage

Checks that every registered route resolves to an existing controller class and method:

Output is a table showing each route's implementation status. Exits with a non-zero code if any routes are unimplemented, making it suitable for CI.

• IMPLEMENTED — controller class and method both exist
• MISSING — class or method cannot be found; the route would throw a server error if called
• UNKNOWN — route uses a closure or has no resolvable action string

Laravel

Route inspector

The bundled LaravelRouteInspector enumerates routes in your application's api middleware group, skipping HEAD routes:

To filter routes differently, bind your own RouteInspectorInterface implementation in a service provider:

Core API

DriftDetector

VersionAnalyser

ChangelogGenerator

Custom route inspectors

Implement RouteInspectorInterface to enumerate routes from any framework:

RouteDefinition normalises parameter syntax automatically — :id, {id}, and <id> all resolve to the same canonical path for comparison.

CI integration

Add both commands to your CI pipeline:

accord:validate fails the build if any routes are undocumented or have been removed from the spec without a version bump. drift:coverage fails the build if any route's controller or method is missing — catching spec-first development gaps before they reach production.

License

MIT