Download the PHP package darkwood/ia-exception-bundle without Composer

Darkwood IaExceptionBundle

Augments HTTP 500 errors with AI-based exception analysis using Symfony AI. Instead of a raw stack trace, you get a clear explanation, probable causes, and suggested fixes—generated by an LLM.

Requirements

• PHP 8.5+
• Symfony 8.x
• symfony/ai-bundle (with a configured platform and agent)

Installation

Register the bundle in config/bundles.php (if not auto-registered):

Configure Symfony AI (e.g. OpenAI):

Configuration

Async AI analysis (Symfony UX–style)

When async: true, the exception page is returned immediately with standard content and a placeholder “AI analysis loading…”. No blocking AI call during kernel.exception. A small inline script then fetches the analysis from GET /__ai_exception/{error_id} and injects the result. If the request fails or times out (30s), a graceful fallback message is shown.

• Requirement: Your app must import the bundle routes so the async endpoint is registered. In config/routes.yaml (or equivalent):

• Production-safe: Async is configurable; leave async: false in production if you prefer synchronous behavior or do not expose the route.

Enforcing Timeout

To enforce the timeout at the HTTP level, configure a scoped HTTP client for your AI platform:

Output Formats

JSON (Accept: application/json)

Returns a structured JSON response:

HTML (default)

The HTML template shows:

• Error ID
• AI-generated explanation
• Probable causes
• Suggested next steps
• Confidence score
• Original exception class and message
• Disclaimer that results are hypotheses

Security Considerations

• Never send secrets to the AI. The bundle sends only:
  • Exception class, message, file, line
  • Optionally: stack trace (when include_trace: true)
• No environment variables, cookies, headers, or request payloads are ever sent.
• include_trace should be true only in dev; traces can reveal paths and structure.
• Use in production only with sanitized input (exception context) and after reviewing your exception messages for sensitive data.

Reliability

• Fail-safe: If the AI fails, times out, or throws any error, the bundle does not set a response. Symfony’s default 500 handling runs as usual.
• 500 is always returned: The response status remains 500; the bundle only augments the body.
• Caching: Results are cached by a fingerprint (exception class, message, top frames hash) with configurable TTL to limit cost and repetition.

License

MIT - Mathieu Ledru 2026