Laradar Laravel Package

Getting Started

Laradar is a development-only inspection tool: it renders a dashboard of your Laravel app's architecture (routes, models, relationships, jobs, etc.), adds AI-generated commentary, and includes a migrations analyzer. Treat it like laravel/tinker or Telescope — install it in require-dev, never ship it to production.

composer require vcian/laradar --dev
php artisan laradar:install   # publishes config/assets — confirm the exact signature in the README
php artisan laradar           # or navigate to the registered dashboard route

Where to look first, in order:

1. config/laradar.php (after publishing) — this is where the AI provider/API key and analyzer toggles live. The AI insights feature is useless without it and will silently degrade if unset.
2. The dashboard landing page — the architecture graph is the headline feature; confirm it renders on a project of your size before wiring anything else in.
3. README.md at the v1.0.0 tag, not the GitHub default branch. This is the first public tag and the README was rewritten twice during the release cycle (PRs #1 and #3), so blog posts and older copies will disagree with the code.

First use case worth trying: run the migrations analyzer against a mature project you already know well. It's the fastest way to calibrate whether the tool's output is trustworthy — you can judge a false positive immediately, which you can't do with the architecture graph on an unfamiliar codebase.

Implementation Patterns

Local-only, gated by environment. The single most important pattern is constraining exposure. The dashboard reveals your entire schema and route surface, and the AI feature may send excerpts of that to a third-party API. Wrap the route registration in an environment check (or whatever gate the package exposes) so APP_ENV=production never serves it:

// config/laradar.php — verify the actual key name in the published config
'enabled' => env('LARADAR_ENABLED', false),

Then set LARADAR_ENABLED=true in .env.local only. Do not add it to .env.example as enabled.

Run it as a pre-refactor audit. The natural workflow is: before a large refactor, snapshot the architecture graph; do the work; re-run and diff. Because the output is generated rather than asserted, this is a human-reviewed comparison, not a CI gate. If you need a hard gate, complement it with something deterministic (Deptrac, PHPStan boundaries) — Laradar tells you what is, not what must be.

Pair the analyzer with an existing migration baseline. Run the migrations analyzer on a fresh clone after migrate:fresh so it sees a clean state, not a locally-drifted database. Developers with divergent local schemas will get different analyzer output for identical code, which produces confusing "it works on my machine" reports.

CI integration is limited to smoke-testing. The release ships a GitHub Actions workflow, but that workflow tests the package, not your app. A reasonable CI use is a single job that boots the dashboard route and asserts a 200 — catching the case where a package upgrade blows up the service provider. Don't attempt to diff AI insights in CI; the output is non-deterministic by nature.

Keep it out of the shared dependency graph. With --dev, Laradar won't reach production images, but it will reach every teammate's machine. If your team uses a shared lockfile, pin an exact version for the first few weeks rather than floating ^1.0 — see Gotchas.

Gotchas and Tips

v1.0.0 is a first public tag, not a stabilization milestone. The changelog shows five PRs in the release window, two of which are README/UI fixes and one of which fixes tests. Nothing here signals a mature, settled API. Expect config key names and artisan signatures to move in 1.x. Pin exactly:

composer require vcian/laradar:1.0.0 --dev

The AI feature is the sharpest edge. Three things to verify before trusting it: (a) which provider and model it calls, (b) whether it transmits code, schema, or both, and (c) what it does when the key is missing. "AI insights" that fail silently on a missing key are worse than ones that throw — you'll read an empty panel as "no issues found." Check the config's default provider and confirm there's an explicit error path. If your project has any restriction on sending source to external APIs, disable this subsystem entirely and use the graph and analyzer alone; they appear to be the parts that work offline.

Analyzer output depends on live database state. Anything that introspects migrations tends to conflate "migrations on disk" with "schema in the database." If a teammate has un-run migrations or hand-edited tables, results diverge. Standardize on migrate:fresh --seed before generating a report you intend to share.

Published assets are a fork, not a reference. Once you vendor:publish, upgrades to the package won't update your copy of the config or views. Keep the published config minimal — override only what you must — and diff it against the package's stub after each upgrade. This bites hardest right after 1.0.0 when the config is still churning.

Debugging a blank dashboard. Work outward: is the service provider registered (php artisan about or package:discover)? Is the config published and the env flag set? Are the compiled assets present (a vendor:publish --force on the assets tag usually fixes a white page)? Only then suspect the AI integration — in a fresh install it's the most likely cause of a partially-rendered dashboard, since the graph may draw while the insights panel fails.

Extension points are thin by design. This is an observability tool, not a framework. If you need custom analyzers, expect to fork rather than hook — the package exposes no documented analyzer registry at 1.0.0. Forking is viable but means you own upgrades; weigh that against just running it as a read-only diagnostic and keeping your own tooling for anything you need to enforce.

Watch the changelog automation, not just the changelog. PR #5 adds a git-cliff-based automated changelog. That's good hygiene, but it also means release notes will increasingly be commit-message-shaped. Read the actual PRs for anything touching config or routes — those are the changes that break your install, and they won't be labeled as breaking in a 1.x automated changelog.