Runtracy Laravel Package

Getting Started

This is a Slim 3-era package: it wires Nette Tracy into a Slim 3 app and adds Slim-aware panels (routing, request, response, environment). Before writing a line of code, check what you actually got:

composer require runcmf/runtracy
ls vendor/runcmf/runtracy/src          # confirm real namespaces
composer show tracy/tracy slim/slim    # expect tracy ^2.x, slim ^3.x

The fork renames the upstream Slim\Middleware\... namespace, so verify the middleware FQCN in src/ rather than trusting blog posts.

Minimal bootstrap — enable Tracy before Slim boots so bootstrap fatals are caught, then register the middleware last so it wraps the entire stack:

<?php
// public/index.php
require __DIR__ . '/../vendor/autoload.php';

Tracy\Debugger::enable(Tracy\Debugger::DEVELOPMENT, __DIR__ . '/../log');
Tracy\Debugger::$maxDepth = 6;
Tracy\Debugger::$maxLen   = 600;

$app = new Slim\App(require __DIR__ . '/../src/container.php');
require __DIR__ . '/../src/routes.php';

// last add() === outermost middleware in Slim 3
$app->add(new RunTracy\Middlewares\TracyMiddleware($app));

$app->run();

First use case: a route returning 404 or hitting the wrong handler. Open the Routing panel — it shows the matched route pattern, name, arguments and the resolved middleware stack, which is faster than var_dump-ing the router. Second use case: the Request/Response panels show headers, status and body after all middleware ran, so you can spot a middleware silently rewriting the response.

Implementation Patterns

Environment-gated bootstrap. Never let the bar leak into production; gate on an env var, not on APP_DEBUG alone:

$debug = getenv('APP_DEBUG') === '1';
if ($debug) {
    Tracy\Debugger::enable(Tracy\Debugger::DEVELOPMENT, __DIR__ . '/../log');
    $app->add(new RunTracy\Middlewares\TracyMiddleware($app));
}

Staging mode without the bar. Set Tracy\Debugger::$showBar = false after enable() — you keep Debugger::log() file logging for exceptions and slow requests, but nothing is injected into HTML.

Middleware ordering is the main design decision. In Slim 3 the last add() is outermost. Register Tracy after auth/CORS middleware and it will decorate auth failures too (handy) — register it before them and the bar only appears on requests that pass auth (cleaner for shared staging).

Ad-hoc profiling. Use Tracy timers around the slow thing rather than guessing:

Tracy\Debugger::timer('repo');
$rows = $repo->findAll();
Tracy\Debugger::timer('repo');           // second call returns elapsed seconds

bdump($rows[0] ?? null, 'first row');    // shows in the bar for this request only

Custom panels are the real extension point. Anything implementing Tracy\IBarPanel (getTab() + getPanel()) can be appended from a service:

class QueriesPanel implements Tracy\IBarPanel
{
    public function __construct(private array $queries) {}

    public function getTab(): string
    {
        return '<span title="Queries">SQL (' . count($this->queries) . ')</span>';
    }

    public function getPanel(): string
    {
        return '<h1>Queries</h1><pre>' . htmlspecialchars(print_r($this->queries, true)) . '</pre>';
    }
}

Tracy\Debugger::getBar()->addPanel(new QueriesPanel($container->get('queryLog')));

Container integration. Put the $app (or router) in the container so panels and your own code resolve it consistently; the Slim panel reads routing state from the app instance passed to the middleware, and a mismatched instance (e.g. a second Slim\App built in a test) yields an empty panel.

Gotchas and Tips

• Slim 4 will not work. There is no PSR-15 middleware here. On Slim 4, drop this package and add tracy/tracy plus a ~30-line MiddlewareInterface that calls Debugger::getBar()->render() into an output buffer.
• Tracy 3 breaks it. Last release is 2017, targeting Tracy 2.x. Pin "tracy/tracy": "^2.4" or you get IBarPanel signature/Debugger::enable() mismatches. Likewise PHP 8 may surface deprecations in the 2017 code — test before adopting.
• Competing error handlers. Tracy installs its own exception/error handlers; Slim's ErrorMiddleware catches exceptions first inside the stack, so Tracy's blue-screen never appears. To get Tracy screens during development, set displayErrorDetails => true and/or remove/reorder the error middleware — otherwise you get the plain Slim 500 page and only the Response panel tells you the truth.
• Headers-already-sent / Content-Length truncation. Tracy injects the bar by buffering output. If a controller sets Content-Length, streams a file, or calls flush(), the bar gets chopped or corrupts the payload. Use Debugger::$showBar = false for those routes.
• JSON/API responses. The bar is meant for HTML; hitting /api/* with the bar enabled can append HTML to bodies (or break strict clients if a middleware re-encodes). Gate on route or on Accept.
• Tracy\Debugger::enable() needs a writable log dir that already exists. A missing log/ folder makes Tracy throw during bootstrap — a confusing "site is blank" symptom. Create it and chmod 0777 in dev only.
• Call enable() before any output, otherwise the session/headers fail and you get a half-working bar.
• Performance. The middleware snapshots request/response bodies; it is not free. Disable it for load tests and CI, and be aware Tracy\Debugger::$maxLen truncates large dumps (looks like your data is missing).
• Namespace collisions. The fork ships classes that clash with upstream slim/tracy; never have both installed — Composer will autoload whichever wins and produce "class not found" for the other's names.
• Maintenance risk. 72 stars, zero dependents, no release since 2017 (Apache-2.0, so forking is fine). Budget for vendoring the middleware into your own src/ if you stay on Slim 3, or treat it as a stopgap while migrating.