docs: add PHP SDK across all guides, fix Python mode parameter, update nav with Packagist link

Author: Fabien83560

docs/.vitepress/config.js

@@ -21,12 +21,14 @@ export default defineConfig({
       { text: 'Features', link: '/features/insights' },
       { text: 'API Reference', link: '/guide/configuration' },
       {
-        text: 'v2.0.0',
+        text: 'SDKs',
         items: [
           { text: 'Changelog (Node.js)', link: 'https://github.com/APIForge-Organisation/sdk-nodejs/blob/main/CHANGELOG.md' },
           { text: 'Changelog (Python)', link: 'https://github.com/APIForge-Organisation/sdk-python/blob/main/CHANGELOG.md' },
+          { text: 'Changelog (PHP)', link: 'https://github.com/APIForge-Organisation/sdk-composer/blob/main/CHANGELOG.md' },
           { text: 'npm — apiforgejs', link: 'https://www.npmjs.com/package/apiforgejs' },
           { text: 'PyPI — apiforgepy', link: 'https://pypi.org/project/apiforgepy/' },
+          { text: 'Packagist — apiforgephp', link: 'https://packagist.org/packages/apiforge/apiforgephp' },
         ],
       },
     ],

docs/features/insights.md

@@ -46,9 +46,9 @@ Identifies endpoints that have received no traffic for an extended period — sa
 
 Compares performance metrics before and after a deployment, when a `release` tag is configured.
 
-> **PERF** — *"`POST /orders` P99 latency increased by 40% after deploying v1.3.0 (14h32 yesterday). Before: 230ms — After: 322ms."*
+> **PERF** — *"`POST /orders` P99 latency increased by 40% after deploying v1.3.0. Before: 230ms — After: 322ms."*
 
-> **OK** — *"Deploy v1.4.0 (3 hours ago) introduced no detectable regression. Latency stable, error rate unchanged."*
+> **OK** — *"Deploy v1.4.0 improved `GET /products` by 12%. Before: 85ms — After: 75ms."*
 
 **Triggers when:** A `release` value is set in the config and at least 30 minutes of post-deploy data is available.
 
@@ -62,10 +62,12 @@ Identifies routes declared in your router that have never received a single requ
 
 > *"`POST /admin/export` is declared in the router but has never received any traffic."*
 
-**Triggers when:** A route appears in the Express / FastAPI router but has zero entries in the metrics database.
+**Triggers when:** A route appears in the router registry but has zero entries in the metrics database.
 
-::: tip Node.js only
-UNTRACKED insights require that the SDK can inspect the Express router at startup. They are not generated for routes registered after the first request.
+::: tip Available on all SDKs
+- **Node.js** — scans the Express router automatically on the first request
+- **Python** — scans the Starlette/FastAPI router automatically on the first request
+- **PHP / Laravel** — syncs the Laravel route registry via the ServiceProvider on boot
 :::
 
 ---
@@ -89,7 +91,6 @@ Set the `release` option to activate `PERF` and `OK` insights:
 
 ```js [Node.js]
 app.use(apiforge({
-  mode: 'local',
   release: process.env.npm_package_version,
 }))
 ```
@@ -98,11 +99,14 @@ app.use(apiforge({
 import os
 app.add_middleware(
     ApiForgeMiddleware,
-    mode="local",
     release=os.environ.get("RELEASE"),
 )
 ```
 
+```bash [PHP / Laravel (.env)]
+APIFORGE_RELEASE=v1.4.0
+```
+
 :::
 
 Each time the value changes (i.e. on a new deploy), APIForge creates a comparison baseline automatically.

docs/features/release-tracking.md

@@ -10,7 +10,6 @@ Pass the current version as the `release` option:
 
 ```js [Node.js]
 app.use(apiforge({
-  mode: 'local',
   release: process.env.npm_package_version,
 }))
 ```
@@ -19,23 +18,32 @@ app.use(apiforge({
 import os
 app.add_middleware(
     ApiForgeMiddleware,
-    mode="local",
     release=os.environ.get("RELEASE"),
 )
 ```
 
+```bash [PHP / Laravel (.env)]
+APIFORGE_RELEASE=v1.4.0
+# or use APP_VERSION which is read by default
+```
+
 :::
 
 Or hardcode it during the deploy process:
 
 ::: code-group
 
 ```js [Node.js]
-app.use(apiforge({ mode: 'local', release: 'v1.4.0' }))
+app.use(apiforge({ release: 'v1.4.0' }))
 ```
 
 ```python [Python]
-app.add_middleware(ApiForgeMiddleware, mode="local", release="v1.4.0")
+app.add_middleware(ApiForgeMiddleware, release="v1.4.0")
+```
+
+```php [PHP / Laravel]
+// config/apiforge.php
+'release' => env('APIFORGE_RELEASE', config('app.version')),
 ```
 
 :::
@@ -54,9 +62,7 @@ Most CI/CD systems expose the version or git tag as an environment variable. Inj
 
 | Metric | Compared |
 |---|---|
-| P50 latency | Before vs after |
 | P90 latency | Before vs after |
-| P99 latency | Before vs after |
 | Error rate (4xx + 5xx) | Before vs after |
 
 ## Example insights generated
@@ -65,7 +71,7 @@ Most CI/CD systems expose the version or git tag as an environment variable. Inj
 ✅ OK   v1.4.0 (deployed 3h ago) — No regression detected.
          Latency stable across 12 endpoints. Error rate unchanged.
 
-⚠️ PERF  POST /checkout — P99 +38% after v1.4.0
+⚠️ PERF  POST /checkout — P90 +38% after v1.4.0
          Before: 210ms · After: 290ms
          Consider reviewing changes to the checkout handler.
 

docs/guide/cloud-mode.md

@@ -8,7 +8,7 @@ Cloud mode sends your metrics to the APIForge SaaS instead of storing them local
 |---|---|---|
 | Setup | Zero config | Requires an API key |
 | Data storage | SQLite on your server | APIForge SaaS |
-| Dashboard | Embedded (port 4242) | Cloud dashboard |
+| Dashboard | Embedded (port 4242 / `/_apiforge`) | Cloud dashboard |
 | Multi-service | One DB per machine | Unified across all services |
 | Internet required | No | Yes |
 
@@ -55,6 +55,18 @@ app.add_middleware(
 )
 ```
 
+```php [PHP / Laravel]
+// .env
+// APIFORGE_CLOUD_URL=https://api.apiforge.fr
+// APIFORGE_API_KEY=af_...
+// APIFORGE_SERVICE=my-api
+
+// bootstrap/app.php — no code change vs local mode
+->withMiddleware(function (Middleware $middleware) {
+    $middleware->append(\ApiForge\Laravel\ApiForgeMiddleware::class);
+})
+```
+
 :::
 
 ### 3. Set environment variables
@@ -66,10 +78,14 @@ APIFORGE_API_KEY=af_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
 ## How it works
 
-1. The SDK intercepts each request and records route, method, status code, and latency in memory.
-2. Every `flushInterval` milliseconds (default: 60s), the buffer is aggregated into per-route statistics and sent to `POST /ingest` on the SaaS API.
+1. The SDK intercepts each request and records route, method, status code, and latency.
+2. Every `flushInterval` (default: 60 s), the buffer is aggregated into per-route statistics and sent to `POST /ingest` on the SaaS API.
 3. The SaaS stores the metrics in TimescaleDB and makes them available through the cloud dashboard.
 
+::: info PHP buffering
+PHP does not have a long-running process, so the SDK uses a file-based buffer (`/tmp/apiforgephp_*.jsonl`). Events accumulate per request and are flushed on the first request after `APIFORGE_FLUSH_INTERVAL` seconds.
+:::
+
 ## Circuit breaker
 
 If the SaaS API is unreachable, the SDK automatically backs off:
@@ -78,11 +94,13 @@ If the SaaS API is unreachable, the SDK automatically backs off:
 - During the pause, flush calls are silently skipped — your application is never blocked.
 - After the pause, the SDK resumes sending normally.
 
-A warning is printed to stdout when the circuit opens:
+A warning is logged when the circuit opens:
 
 ```
-[apiforgejs] Cloud flush failures — pausing for 60s. Error: ...
-[apiforgepy] Cloud flush failures — pausing for 60s. Error: ...
+[apiforgejs]  Cloud flush failures — pausing for 60s. Error: ...
+[apiforgepy]  Cloud flush failures — pausing for 60s. Error: ...
+[apiforgephp] Cloud flush error: HTTP 503 — ...
+[apiforgephp] Circuit open — pausing for 60s.
 ```
 
 ## Rotating an API key