apiforgephp

API observability & intelligence for Laravel — local-first, privacy-first.

Track latency, error rates, and behavioral trends of your APIs. Everything stays on your machine.

→ Full documentation

---

Install

composer require apiforge/apiforgephp

Requires PHP ≥ 8.2 and the pdo_sqlite extension (php8.x-sqlite3 package on Debian/Ubuntu).

Quick start

The service provider is auto-discovered by Laravel. Register the middleware in your bootstrap/app.php (Laravel 11+) or app/Http/Kernel.php (Laravel 10):

// Laravel 11+ — bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\ApiForge\Laravel\ApiForgeMiddleware::class);
})

// Laravel 10 — app/Http/Kernel.php
protected $middleware = [
    // ...
    \ApiForge\Laravel\ApiForgeMiddleware::class,
];

That's it. The local dashboard is now live at http://localhost:8000/_apiforge (adjust the port to match your Laravel app).

Dashboard

In local mode, the dashboard is served automatically at /_apiforge on your Laravel app's port — no separate process needed.

http://localhost:8000/_apiforge

• Health Score (0–100) — global API health at a glance
• Latency percentiles — P50 / P90 / P99 per route
• Error rates — 4xx and 5xx breakdown
• Automatic insights — latency anomalies, dead endpoints, release regressions
• Time series chart — click any route to see its latency over time

Configuration

Publish the config file (optional):

php artisan vendor:publish --tag=apiforge-config

Or configure via environment variables:

Variable	Default	Description
APIFORGE_ENV	APP_ENV	Environment label (production, staging…)
APIFORGE_RELEASE	APP_VERSION	Release/version tag for regression tracking
APIFORGE_SERVICE	APP_NAME	Service name
APIFORGE_SAMPLING	1.0	Sample rate 0.0–1.0
APIFORGE_DASHBOARD	true	Enable/disable the local dashboard routes
APIFORGE_DASHBOARD_PREFIX	_apiforge	URL prefix for the local dashboard
APIFORGE_CLOUD_URL	—	Cloud mode: SaaS API base URL
APIFORGE_API_KEY	—	Cloud mode: project API key (af_…)

Cloud mode

Send metrics to the APIForge SaaS platform instead of storing them locally:

APIFORGE_CLOUD_URL=https://api.apiforge.fr
APIFORGE_API_KEY=af_your_project_key

// bootstrap/app.php — same middleware registration, no code change needed
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\ApiForge\Laravel\ApiForgeMiddleware::class);
})

In cloud mode, events are buffered to a local temp file and flushed to the SaaS ingest API every 60 seconds. The local dashboard is disabled automatically.

Release tracking

Set the release tag to enable before/after deployment comparison:

APIFORGE_RELEASE=v1.4.0

Or dynamically in AppServiceProvider:

config(['apiforge.release' => config('app.version')]);

When a new release is detected, APIForge compares P90 latency before and after and surfaces regressions automatically.

What you get

• Per-route latency — P50, P90, P99 per endpoint
• Error rate by route — 2xx / 3xx / 4xx / 5xx breakdown
• API Health Score — a single 0–100 score summarising your API's health
• Ghost route detection — requests that match no declared Laravel route
• Latency anomaly alerts — Z-score detection against a 7-day baseline
• Dead endpoint detection — routes with no traffic for 21+ days
• Release regression analysis — automatic P90 comparison per deploy
• Progressive drift detection — slow latency increases over weeks
• Untracked route detection — declared routes that never received traffic
• Inflight concurrency tracking — approximate inflight_avg and inflight_max per route

Graceful shutdown

The middleware flushes automatically at the end of every request. No manual teardown is needed for standard PHP-FPM deployments.

For long-running processes (Laravel Octane, FrankenPHP, Swoole), call shutdown() on application termination if needed — the aggregator is otherwise request-scoped and carries no state between requests.

Known limitations

Limitation	Detail
TTFB = total duration	PHP-FPM sends responses atomically — true Time to First Byte cannot be measured at the middleware layer. lat_ttfb_* values equal lat_*.
Approximate inflight count	PHP workers are isolated; the inflight counter is shared via a file lock, which is accurate to the order of magnitude but not microsecond-precise.

Privacy by design

• Request and response bodies are never read
• No PII captured — only route patterns, HTTP methods, status codes, and timing
• Route parameters are normalised (/users/42 → /users/:id, UUIDs → /:uuid)
• SQLite database stays entirely on your server in local mode
• Sampling rate can be set below 1.0 to reduce storage footprint

Requirements

• PHP ≥ 8.2
• Laravel ≥ 10.0
• ext-pdo_sqlite — install with apt install php8.x-sqlite3 if not present

License

MIT — see LICENSE.