Download the PHP package tracegraph/laravel without Composer

tracegraph/laravel

TraceGraph instrumentation for Laravel. Auto-discovers via Composer and hooks into Laravel's existing event system to capture HTTP requests, database queries, authentication events, Gate/policy checks, and queue job lifecycle — all as structured trace events written to disk for offline analysis, baseline comparison, and security/reliability finding detection.

Zero overhead when disabled. Every hook in this package is gated on TRACEGRAPH_ENABLED=1. When the environment variable is absent or not '1', no listeners are registered and every method is a true no-op.

Requirements

• PHP 8.1 or later
• Laravel 10, 11, or 12

Installation

The service provider auto-discovers via Composer's extra.laravel.providers — no changes to config/app.php or bootstrap/providers.php are needed.

Quick start

1. Run your tests with tracing

Or use the Artisan command (delegates to the Node CLI when available):

2. Open the trace in your browser

3. Approve the current behaviour as a baseline

4. On subsequent runs, compare for regressions

What is captured automatically

When TRACEGRAPH_ENABLED=1, the service provider registers the following hooks at boot time. No code changes to your application are required.

All events include language: 'php', framework: 'laravel', and schemaVersion: 'tracegraph.event.v1'.

Manual instrumentation

Tracegraph::trace() — wrap a callable

Emits a function_call event with timing, and an error event if the callable throws.

Nested trace() calls produce nested events. The call stack is managed via a static context (src/Context.php) — PHP is synchronous, so no AsyncLocalStorage is needed.

Adding Tracegraph::trace() to key service methods upgrades the trace from capture level 1 (framework adapters only) to capture level 2 (manual wrappers).

Tracegraph::authCheck() — explicit auth gate

Emits an auth_check event. TraceGraph treats auth_check events as Critical baseline anchors — if one disappears between runs, a Critical finding is raised.

The Gate listener captures Laravel's built-in policy checks automatically, but authCheck() lets you mark custom authorisation logic that isn't routed through the Gate facade.

Tracegraph::captureException() — record an exception

Records a Throwable as an error event without interrupting the normal exception-handling pipeline. Vendor framework frames are stripped from the stack trace to reduce noise.

Helper functions (procedural aliases)

helpers.php is auto-loaded by Composer and provides procedural aliases for all three methods — useful in non-OOP contexts, scripts, and closures where importing a class is verbose.

PHPUnit extension (per-test trace isolation)

Add the extension to phpunit.xml to give every test case its own isolated trace file (capture level 5):

The extension is a no-op unless TRACEGRAPH_ENABLED=1 and TRACEGRAPH_RUN_DIR are set.

Each test produces:

• A test_file event for the test class/file
• A test_run event with the test name, pass/fail/skip status, and duration
• All function_call, db_query, http_request, and other events emitted during the test body

Trace files are written to {TRACEGRAPH_RUN_DIR}/tests/{traceId}.events.jsonl.tmp and finalised to .tracegraph/traces/{traceId}.trace.json by the TraceGraph CLI after the test run completes.

Artisan commands

All commands are registered regardless of TRACEGRAPH_ENABLED so you can run them in any environment.

Environment variables

Set these in your .env for local development:

Do not set TRACEGRAPH_ENABLED=1 in production. The adapters are safe but unnecessary overhead in a production environment.

CI integration

GitHub Actions

Xdebug integration

For deep function-call detail beyond what the Laravel hooks capture, run PHP with Xdebug in trace mode and import the resulting .xt file using the Node CLI.

1. Add correlation markers to your PHP code

Place tracegraph_xdebug_marker() calls just before key semantic events. This is a genuine no-op function (never add logic to it). Its presence in the Xdebug log gives the merger a confidence-1.0 correlation anchor.

2. Run PHP with Xdebug enabled

3. Import and merge with the Node CLI

The --include "app/" flag filters out vendor calls, keeping only application-level function calls. Use --max-events 2000 for large test suites.

4. Open the enriched trace

In the viewer, click any semantic node (e.g. an authorization_check). If correlated Xdebug calls exist, a Xdebug Call Stack section appears showing depth-indented function names with file:line and confidence badges.

What each event looks like

All events written by this package follow the tracegraph.event.v1 schema: