Symfony Profiler Optimization Advisor Bundle Laravel Package

Getting Started

The bundle is a meta-collector: it doesn't instrument anything itself, it reads what Symfony's Doctrine, Cache, Twig, Events, HTTP Client, Messenger and Stopwatch collectors already recorded for a request, then turns that into ranked anti-pattern findings. That means the first step is making sure the underlying collectors are actually producing data.

1. Install as a dev dependency so it never ships to production. Pin to ^0.1.1 — 0.1.0 shipped with a broken AI Mate profiler model accessor, so its prepared prompts could error or come back blank:

   composer require --dev martinkup/symfony-profiler-optimization-advisor-bundle:^0.1.1
   

2. Confirm registration is dev/test only in config/bundles.php (recipes usually do this):

   MartinKup\SymfonyProfilerOptimizationAdvisorBundle\...::class => ['dev' => true, 'test' => true],
   

3. Verify the collectors it reads from are enabled in config/packages/dev/framework.yaml / web_profiler.yaml. Doctrine, Twig, Cache, Events and Stopwatch are on by default in dev; the HTTP Client collector needs profiling turned on (framework.http_client.default_options + the http_client profiler integration), and Messenger ships its collector automatically in dev.
4. Profile a known-slow page in dev with the toolbar visible, open the Optimization Advisor panel, and read the findings list. If you upgraded from 0.1.0, expect the panel chrome to look different (styles were overhauled in 0.1.1) — that's cosmetic, not a config change.

Where to look first: the bundled panel for the request you already suspected. Pick your single worst endpoint (a listing page with relations, a dashboard with cache, anything fanning out HTTP calls), browse it, and read the top-ranked finding by ROI. That's your first real use case — not a project-wide audit, but "this one page, what's the cheapest high-impact fix."

If you want to drive it from an AI agent rather than the browser, discover the bundle's query surface first:

bin/console list | grep -i advisor

Each finding carries a prepared prompt specifically so you can hand it to Claude Code / an agent with the file paths and symptom already described. Sanity-check that a prompt actually renders for one finding before you build a workflow around it — that path was only fixed in 0.1.1.

Implementation Patterns

Per-request triage loop. Profile → open advisor → pick the highest ROI finding → copy its AI prompt into your agent → review the diff → re-profile the same URL and confirm the finding disappears. The scoring fields (impact, effort, confidence, ROI) are there to stop you from chasing a dramatic-looking N+1 in an admin page while the public listing does 40 queries.

Use the prepared prompts as the entry point to code changes. They are the bundle's real differentiator: instead of describing "there's an N+1 in the order list," paste the finding prompt and let the agent locate the repository call. Treat the prompt as a starting brief, not a spec — verify the entity associations and fetch strategy yourself. If prompts are empty or throw, you're on 0.1.0; bump to ^0.1.1.

Before/after comparison. Profile a change the same way you'd write a regression test: capture the URL, note the token, apply the fix, clear the old profiles (rm -rf var/cache/dev/profiler if you use the file profiler storage), re-request the URL, compare findings sets.

Scenario-targeted profiling. Findings only surface if the code path runs during the profiled request. Write a throwaway route or functional test that exercises the expensive branch (cold cache, large account, deep category tree), then profile that request rather than the happy path.

Agent-driven batch review. When you have a console/query command for findings, dump the report as JSON and feed it to your coding agent with a narrow instruction like "rank these five findings, propose the smallest patch for the top two, and flag any advice that assumes user-specific data can be cached."

PR-adjacent habit. Before merging a change that touches a hot endpoint, load that endpoint once in dev and glance at the advisor panel. It's a cheap second opinion that catches the query-in-a-loop you introduced while refactoring a template partial.

Integration tip — keep it passive. The advisor is a read-only observer over other collectors. Don't wire it into runtime services or attempt to gate application behaviour on its output; keep any CI use confined to parsing the dumped report and comparing thresholds between builds.

Gotchas and Tips

• Pin at least 0.1.1. 0.1.0's AI Mate profiler model accessor was wrong, which is exactly the code path that produces the finding prompts. If prompts are the reason you installed this, 0.1.0 is a degraded experience.
• php-http/discovery is now enabled (0.1.1). Composer's PSR-18/HTTPlug discovery plugin is active, so an outbound HTTP client can be auto-resolved. In apps with multiple PSR-18 implementations or a hand-rolled client, discovery may bind a different client than you assume — if the HTTP Client panel starts showing traffic you didn't expect (or stops showing it), check discovery before blaming the advisor.
• It's only as smart as the collectors feeding it. If the Cache panel is empty, the bundle can't report cache misses; if the HTTP Client collector isn't profiling, outbound fan-out is invisible. When a category of finding never appears, check the underlying panel before assuming the advisor is broken.
• Profile the worst-case request, not the first one. An N+1 that's masked by a warm cache or a small data set in your dev fixtures won't show up. Seed realistic volume for the page you care about.
• Findings are request-scoped and heuristic. "Cache this" is wrong for anything user- or permission-dependent, and a low-impact finding on your homepage can outweigh a high-impact one in a rarely-hit admin route. Re-score with real traffic in mind before acting.
• Empty or missing panel. Usual causes: bundle registered outside dev, web profiler toolbar disabled, or an old profiler profile loaded before the bundle was installed. Clear var/cache/dev and the profiler storage, then re-request.
• Don't register it in prod. Even though it's read-only, it adds work on top of an already-heavy dev toolchain; keep ['dev' => true, 'test' => true] and audit config/bundles.php if you deploy with APP_ENV=prod on a staging box.
• Long-running workers don't produce profiles. Messenger consumers under a worker process have no request lifecycle — profile the HTTP request that dispatches the message and look at the Messenger collector there, or check the dispatch path in isolation.
• Sensitive data in prompts. Prepared AI prompts can include SQL fragments, table names, template paths and occasionally query parameters. Strip customer data before pasting anywhere outside the repo or the team.
• Verify each recommendation against the actual association mapping. N+1 advice is only correct if the relation truly needs to be loaded; eager-loading a collection used nowhere is a regression the advisor can't see.
• Extension points worth checking first: the bundle's config tree (bin/console config:dump-reference <bundle-alias>) for severity thresholds or score weighting, and whether it lets you register extra collector sources — that's where you'd tune it if the default ranking doesn't match your app's hot paths.
• Dev-only overhead grows. On query-heavy pages the profiler plus this meta-pass can be noticeably slow. If dev browsing degrades, trim the collector set rather than dropping the advisor.
• Upgrading 0.1.0 → 0.1.1 is a straight patch bump. Only template styles, composer metadata, CI/security config and the prompt accessor changed — no config keys moved, so no migration is needed beyond composer update and a cache clear (bin/console cache:clear plus clearing profiler storage) so old profiles generated before the fix don't confuse you.