Git Debug Bundle Laravel Package

Getting Started

Read this first: leek/git-debug-bundle is a Symfony 2.x bundle, not a Laravel package. There is no service provider, no publishable config, and no composer require path into a Laravel app — its integration points (Bundle boot cycle, Symfony\Component\HttpKernel\DataCollector\DataCollectorInterface, the Symfony toolbar contract) do not exist in Laravel and have changed twice since Symfony 2.x EOL'd in 2018. Treat the repo as a reference implementation of an idea, not a dependency.

Where to look first: open the bundle's DataCollector class. That is the entire value of the package — a handful of git invocations wrapped in a collector that renders branch, short SHA, and working-tree dirty/clean state. Everything else (DI wiring, toolbar registration, templating) is Symfony-2-era plumbing you will not reuse.

The actual first use case — "which commit is running on staging right now, without SSH or asking in Slack?" — is worth solving once and cheaply. On Laravel, the minimal working setup is:

1. Install barryvdh/laravel-debugbar (which provides php-debugbar/php-debugbar and the collector contract).
2. Write one GitCollector implements DataCollectorInterface with getName(), collect(), and getWidgets().
3. In collect(), shell out once via Symfony\Component\Process\Process (already a Laravel dependency) with a batched command:

   $process = new Process(['git', 'status', '--porcelain=v2', '--branch']);
   $process->setTimeout(2);
   $process->run();
   

   Parse the # branch.head, # branch.oid, and presence-of-any-non-#-line (dirty) from that single output.
4. Register it conditionally in a service provider guarded by $this->app->isLocal() || config('app.debug').
5. Verify the widget renders in the debugbar on a dev request, then confirm it is a no-op with APP_DEBUG=false.

If you are genuinely on a surviving Symfony 2.x app, install from VCS (no reliable tag exists; the repo is archived), register the bundle in AppKernel.php inside the dev/test branch only, and accept that you are pinning dev-master of an abandoned repo.

Implementation Patterns

Pattern 1 — Debugbar collector (the direct port). The lowest-effort path is a single collector that reads Git state and adds a small toolbar panel. Keep the field set tight: current branch, short SHA, dirty flag, and (optionally) git describe --tags. Drop remote URLs unless you have a specific need — they are the highest-leak field and least useful in a toolbar.

Pattern 2 — /version endpoint + X-App-Commit header. A middleware that appends the SHA to every response header in non-production, plus a /version route returning JSON. This serves the same "what's running?" question for API consumers, curl, and automated smoke tests — not just for humans staring at a toolbar.

Pattern 3 — Build-time SHA injection. The most robust pattern and the one to prefer for anything beyond local dev: write the SHA into config during CI (composer post-install script, Docker build arg, or a generated resources/version.json). This eliminates runtime git subprocesses entirely and works in artifact/tarball deployments where .git is absent.

Pattern 4 — Release tagging for observability. Feed the same commit SHA into Sentry/New Relic release tags. This is where the same metadata delivers far more value than a toolbar: incident response can bisect by release without any per-request cost.

Integration tips.

• Batch git commands. Do not spawn one subprocess per data point. A single git status --porcelain=v2 --branch yields branch, SHA, ahead/behind counts, and dirty state in one call. Cache the parsed result per-request (or per-boot with a short TTL) so slow disks or network-mounted workspaces don't drag on debug page loads.
• Use Process, not shell_exec. You get a timeout, non-zero-exit handling, and stderr capture — all of which you need for graceful degradation.
• Guard on APP_DEBUG and APP_ENV !== 'production' in the provider, and assert it with a test. Debug mode accidentally enabled in staging is the primary risk in this whole exercise.
• Fail silent, never throw. An exception inside a data collector breaks the entire debugbar render. Wrap every Git call in try/catch and degrade to "Git: unavailable."
• Pin barryvdh/laravel-debugbar at a major version and assert the collector interface in a unit test — php-debugbar v2 changed collector signatures.

Gotchas and Tips

• Archived with zero dependents. No CVEs patched, no PHP 8.x work, no upstream bug fixes, no community to lean on. All ownership is yours the moment you adopt the pattern. Budget roughly an engineer-week including tests and docs.
• git binary not on PATH. Common in slim container images. Detect and report "git: not found" rather than throwing.
• .git absent. Tarball and artifact deployments strip it. The collector must no-op cleanly. If you need provenance in those environments, fall back to build-time SHA injection (Pattern 3).
• Detached HEAD in CI. branch.head will not be a branch name — report detached @ <short-sha> instead of an empty branch field, or you will confuse every developer who sees it.
• "dubious ownership" refusals. Docker bind mounts frequently trigger Git's ownership check (fatal: detected dubious ownership). Surface the raw stderr string in the toolbar; it is the single biggest time-saver for a developer who has never seen the error before.
• shell_exec / proc_open disabled or open_basedir restricting the workspace. Catch and degrade. This is a recurring "works on my machine" class of incident.
• Information disclosure. Remote URLs in legacy CI configs often embed credentials. Redact them, and hard-gate the whole collector behind APP_DEBUG. Treat branch/SHA as internal-but-non-sensitive, and remote URLs as a potential secret leak.
• php-debugbar v2 signature drift. Historically major versions ship every ~18–24 months and break collector signatures. Pin the major and keep the assertion test, or you will discover the break in production staging.
• Do not shim the Symfony bundle. A compatibility layer costs more than the ~50-line rewrite by an order of magnitude, and you would inherit the archived code's Symfony-2 idioms in a modern Laravel tree.
• Write a short ADR. Every new engineer eventually notices the collector was derived from an archived Symfony2 bundle. A paragraph recording the build-vs-adopt decision on day one is cheaper than that conversation every quarter.