Download the PHP package martinkup/symfony-profiler-optimization-advisor-bundle without Composer

Symfony Profiler Optimization Advisor Bundle

Detect N+1 queries, slow SQL, low cache hit rates, hot Twig templates, and 10 more performance anti-patterns — automatically, on every request. Each finding is scored by impact, effort, and confidence, with a ready-to-use AI prompt for guided fixes. Queryable directly from Claude Code and other MCP-compatible AI agents via AI Mate integration.

A meta data collector for Symfony Profiler — it reads data from other profiler collectors (Doctrine, Cache, Twig, Events, HTTP Client, Messenger, Stopwatch), analyzes per-request signals across 7 categories, and produces scored, actionable optimization opportunities with impact/effort/confidence ratings, ROI ranking, and ready-to-use AI agent prompts.

Table of Contents

• Features
• Why This Bundle?
• How It Works
• Requirements
• Installation
• Configuration
• Signal Categories
• Detected Opportunity Codes
• Opportunity Scoring Model
• Origin Classification
• Optional Integrations
• AI Mate Integration
• Architecture
• Testing
• Documentation
• Contributing
• License

Features

• 7 signal categories — Database, Cache, Twig, Events, HTTP Client, Messenger, and Stopwatch
• 14 detection rules — N+1 queries, duplicate queries, slow templates, low cache hit rates, heavy sync handlers, and more
• Scored opportunities — Each finding carries impact (1-5), effort (1-5), confidence (1-5), ROI, and risk level
• AI agent prompts — Every opportunity includes a ready-to-use prompt for AI coding assistants
• MCP tool — Queryable directly from Claude Code, Cursor, and other MCP-compatible AI agents via AI Mate
• Origin classification — Separates your app code signals from framework/infrastructure noise
• Zero configuration — Works out of the box with sensible defaults; every threshold is customizable
• Late collector — Runs at priority -100 to ensure all other profiler collectors have finished first

Why This Bundle?

Unlike generic APM tools, this bundle:

• Runs inside the Symfony Profiler — no external service needed
• Analyzes 7 signal categories in a single per-request pass
• Scores each finding (impact/effort/confidence/ROI) instead of just listing warnings
• Generates AI-ready prompts for every opportunity
• Directly queryable from Claude Code, Cursor, and other MCP-compatible agents via AI Mate
• Classifies signals by origin (app vs. framework noise)
• Works with zero configuration out of the box

How It Works

1. The OptimizationAdvisorDataCollector runs as a late data collector (priority -100) after all other Symfony profiler collectors have completed.
2. Seven specialized analyzers process raw profiling data from Doctrine, Cache, Twig Profiler, EventDispatcher, HttpClient, Messenger, and Stopwatch.
3. Each analyzer classifies signals by origin (app, infrastructure, or profiler) so you only see findings relevant to your code.
4. The AdvisorEngine evaluates all signals against configurable thresholds and produces scored optimization opportunities.
5. Opportunities are deduplicated by fingerprint, sorted by ROI descending, and capped at max_items.
6. The profiler panel renders a rich dashboard with summary scores, quick wins, high-impact findings, and detailed signal breakdowns.
7. Every opportunity includes a pre-filled AI agent prompt — copy it into your AI coding assistant for guided, step-by-step implementation.

Requirements

Installation

If you use Symfony Flex, the bundle is registered automatically. Otherwise, add it manually:

Note: Register the bundle only in dev and test environments. It depends on debug services (twig.profile, data_collector.cache) that are not available in production. Optional services (doctrine.debug_data_holder, data_collector.http_client, debug.stopwatch) are wired with nullOnInvalid() and degrade gracefully when absent.

Configuration

All options have sensible defaults. No configuration file is needed to get started.

To customize, create config/packages/optimization_advisor.yaml:

Security Redaction

When AI Mate integration is active, all profiler data passes through SecurityRedactor before being exposed via MCP channels (both the collector formatter and the MCP tool apply redaction for defense-in-depth). The redactor uses pattern-based matching to selectively redact sensitive values while preserving non-sensitive context (pagination, sorting, IDs).

Fail-closed regex behavior: Invalid regex patterns in sensitive_value_patterns cause values to be redacted rather than skipped. This ensures misconfigured patterns cannot leak sensitive data.

What gets redacted:

Example:

• email key → redacted by sensitive_param_patterns (substring match)
• 0: '[email protected]' → redacted by sensitive_value_patterns (email regex)
• 1: 42 → preserved (no pattern match)
• name: 'John' → preserved (no pattern match)
• token query param → redacted by sensitive_query_params (exact match)
• page, sort query params → preserved

To add custom patterns (e.g. for SSN or national ID numbers):

Note: Setting any of these arrays replaces the defaults entirely. Include all patterns you need.

In query strings, redacted values are URL-encoded (%2A%2A%2AREDACTED%2A%2A%2A). The examples above show the decoded form for readability.

Configuration Reference

Thresholds

Origin classification

Security redaction (AI Mate / MCP output)

Signal Categories

Database (DatabaseAnalyzer)

Analyzes Doctrine DBAL debug data. Groups queries by SQL fingerprint (normalized pattern), classifies origin, and computes per-group metrics.

Collected metrics: query count, total/max/min/avg ms, query kind (SELECT/INSERT/UPDATE/DELETE), tables, connection name, fingerprint, app vs. infrastructure split.

Cache (CacheAnalyzer)

Analyzes Symfony Cache pool statistics. Computes per-pool hit rates, read/write/delete counts, and classifies pools by origin.

Collected metrics: calls, reads, writes, deletes, hits, misses, hit rate, total ms, app/infra/profiler split.

Twig (TwigAnalyzer)

Walks the Twig Profile tree and aggregates per-template render counts and durations.

Collected metrics: render count, total/max ms per template, app/infra/profiler render split.

Events (EventAnalyzer)

Analyzes called and not-called event listeners from TraceableEventDispatcher. Groups by event + listener class.

Collected metrics: call count, total/max/avg ms per listener, unique events, unique listeners, not-called count, app/infra/profiler split.

HTTP Client (HttpClientAnalyzer)

Analyzes HttpClientDataCollector traces. Groups by endpoint fingerprint (method + host + path pattern with numeric segments replaced by {id}).

Collected metrics: call count, total/max ms, status code buckets (2xx/3xx/4xx/5xx) per endpoint.

Messenger (OtherSignalsAnalyzer)

Analyzes synchronous Messenger handler executions from TraceRegistry records.

Collected metrics: handler class, message name, duration ms, app/infra split, total sync ms.

Stopwatch (PerformanceAnalyzer)

Analyzes Symfony Stopwatch section events for a performance timeline breakdown.

Collected metrics: event name, category, duration, memory, start/end time, period count, percent of total request duration, top 3 events.

Detected Opportunity Codes

Opportunity Scoring Model

Each detected opportunity is scored on three dimensions (1-5 scale):

Derived metrics:

• ROI = impact * confidence / effort — used for sorting (highest ROI first)
• Quick Win = effort <= 2 AND confidence >= 4
• High Impact = impact >= 4
• Risk = low, med, or high — safety risk of implementing the recommendation
• Fingerprint = md5(code + evidence) — used for deduplication

Optimization Score

A 0-100 score summarizing the overall request health. Starts at 100 and deducts impact * confidence * 0.5 per opportunity. Lower scores indicate more optimization potential.

AI Agent Prompt

Every opportunity includes a structured ai_prompt field containing:

• Problem description
• Evidence references
• Numbered recommended actions
• Safety notes

This prompt can be copied directly into an AI coding assistant (Claude, ChatGPT, Copilot) for guided implementation.

Origin Classification

All signals are classified into three origins to separate your application code from framework noise:

Only app signals are evaluated for opportunities. Infrastructure and profiler signals are collected for informational display but do not generate recommendations.

The app_namespace_prefix configuration option controls how event listeners and Messenger handlers are classified. Set it to your project's root namespace (e.g., Acme\ for a project using Acme\App\... namespaces).

Optional Integrations

The bundle gracefully degrades when optional components are not installed:

Messenger Integration

When symfony/messenger is installed, the bundle automatically registers its MessageTracingMiddleware on all configured Messenger buses via a CompilerPass. The middleware is inserted right after Symfony's traceable middleware (in debug mode) or as the outermost wrapper in the chain for accurate timing.

This approach works reliably even when the host project defines environment-specific middleware overrides (e.g., when@dev sections in messenger.yaml).

No manual configuration required — the middleware is auto-registered for every bus tagged with messenger.bus regardless of how middleware lists are defined in configuration files.

The middleware populates the bundle's TraceRegistry with per-handler trace records:

• is_handled_sync — whether the message was handled synchronously (HandledStamp present)
• handler_class — FQCN of the handler (from HandledStamp::getHandlerName())
• handler_duration_ms — wall-clock handler execution time
• message_short — short class name of the dispatched message

When symfony/messenger is not installed, the middleware definition is conditionally removed and the "Other" tab shows an empty Messenger section.

AI Mate Integration

When symfony/ai-symfony-mate-extension is installed, the bundle registers as an AI Mate MCP extension, exposing optimization data to AI assistants via two channels:

MCP Tool: optimization-advisor-opportunities

A dedicated tool that returns scored optimization opportunities with filtering support:

Each opportunity includes ai_prompt, recommended_actions, evidence_refs, and safety_notes — ready for AI-guided implementation.

Profiler Resource URI

The collector formatter makes optimization data available at:

This returns the full collector output: origin, opportunities, summary, and signals with sanitized data objects.

Setup

1. Install the extension as a dev dependency:

2. Discover the extension:

3. Use the tool from any MCP-compatible AI assistant (e.g., Claude Code):

The agent will automatically query the profiler for the matching request, evaluate all detected opportunities, and propose concrete code changes.

No additional configuration is required. The bundle's composer.json contains the extra.ai-mate section for automatic discovery.

Architecture

Key components: DataCollector (late collector, priority -100) → 7 Analyzers (Database, Cache, Twig, Events, HTTP Client, Messenger, Stopwatch) → AdvisorEngine (14 detection rules, scoring, deduplication). See the full component catalog for details.

Data Flow

Documentation

Full documentation is available in the docs/ directory.

Testing & Development

All available commands via composer run --list:

Contributing

See CONTRIBUTING.md for guidelines.

License

This bundle is released under the MIT License.

Author

Martin Kup · LinkedIn