raffaelecarelle / php-error-insight-symfony-bundle
Symfony Bundle for PHP Error Insight - AI-powered error handling for Symfony applications
Installs: 75
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Type:symfony-bundle
pkg:composer/raffaelecarelle/php-error-insight-symfony-bundle
Requires
- php: >=8.1
- raffaelecarelle/php-error-insight: ^1.0
- symfony/framework-bundle: ^5.4|^6.4|^7.0
- symfony/runtime: ^5.4|^6.4|^7.0
Requires (Dev)
- ergebnis/phpunit-slow-test-detector: ^2.20
- friendsofphp/php-cs-fixer: ^3.87
- phpstan/extension-installer: ^1.4
- phpstan/phpstan: ^1.10
- phpstan/phpstan-phpunit: ^1.4
- phpstan/phpstan-symfony: ^1.3
- phpunit/phpunit: ^10.5
- rector/rector: ^1.2
- symfony/browser-kit: ^5.4|^6.4|^7.0
- symfony/css-selector: ^5.4|^6.4|^7.0
- symfony/dom-crawler: ^5.4|^6.4|^7.0
- symfony/phpunit-bridge: ^5.4|^6.4|^7.0
- symfony/security-bundle: ^5.4|^6.4|^7.0
README
A Symfony bundle that integrates PHP Error Insight to provide AI‑assisted explanations and richer error pages for HTTP and Console errors.
Features
- 🔍 AI‑assisted error explanations (optional, multiple backends)
- 🎨 Enhanced HTML/text/JSON rendering provided by the core library
- ⚡ Seamless Symfony integration for HTTP exceptions and Console errors
- 🔧 Highly configurable: choose backend, model, output, verbosity and paths
Requirements
- PHP >= 8.1
- Symfony >= 5.4
- Composer
Installation
Install the bundle (typically in dev/test):
composer require --dev raffaelecarelle/php-error-insight-symfony-bundle
Configure Symfony Runtime error handler (required)
To enable the bundle's PHP error handling, you must tell Symfony Runtime to use this bundle's error handler. Add the following to your application's composer.json under the extra.runtime section, then regenerate the autoloader:
{
  "extra": {
    "runtime": {
      "error_handler": "PhpErrorInsightBundle\\Handler\\ErrorHandler"
    }
  }
}
After editing composer.json, run:
composer dump-autoload
Notes:
- The configuration must live in your application root composer.json(not in a dependency).
- This requires the symfony/runtimeComposer plugin to be allowed in your project (seeconfig.allow-plugins["symfony/runtime"]).
Configuration
The bundle exposes a single configuration root: php_error_insight.
Basic configuration
Create or update config/packages/php_error_insight.yaml:
php_error_insight: enabled: true backend: 'none' # or: local, api, openai, anthropic, google, gemini language: 'en' output: 'auto' # or: html, text, json
Advanced configuration
php_error_insight: enabled: true backend: 'local' model: 'llama3:instruct' api_url: 'http://localhost:11434' language: 'en' output: 'html' verbose: false # Absolute path of your project inside the running environment # (e.g. "/app" inside a Docker container) project_root: '%kernel.project_dir%' # Optional: absolute path of the project on the host machine to map # container paths to host paths when rendering links host_root: '/absolute/path/on/host' # Optional: custom HTML template supported by the core library template: null # Optional: editor URL pattern, e.g. "phpstorm://open?file=%file%&line=%line%" editor_url: null # API key for external backends (openai, anthropic, google/gemini, custom api) api_key: null
Notes:
- backendsupports:- none,- local,- api,- openai,- anthropic,- google,- gemini.
- When using local backends (e.g. Ollama), set api_urlto your local endpoint.
- Use project_rootand optionallyhost_rootto make editor links and paths resolve correctly across containers/hosts.
- editor_urlplaceholders supported by the core renderer are typically- %file%and- %line%.
Environment variables
You can configure via environment variables as well (e.g. in .env.local):
PHP_ERROR_INSIGHT_ENABLED=true
PHP_ERROR_INSIGHT_BACKEND=local
PHP_ERROR_INSIGHT_MODEL=llama3:instruct
PHP_ERROR_INSIGHT_API_URL=http://localhost:11434
PHP_ERROR_INSIGHT_LANG=en
PHP_ERROR_INSIGHT_OUTPUT=html
PHP_ERROR_INSIGHT_VERBOSE=false
PHP_ERROR_INSIGHT_PROJECT_ROOT=/app
PHP_ERROR_INSIGHT_HOST_ROOT=/Users/you/Projects/acme
PHP_ERROR_INSIGHT_EDITOR="phpstorm://open?file=%file%&line=%line%"
PHP_ERROR_INSIGHT_API_KEY=your-key-if-needed
Backend configuration examples
1) Local AI (Ollama)
php_error_insight: backend: 'local' model: 'llama3:instruct' api_url: 'http://localhost:11434'
2) OpenAI
php_error_insight: backend: 'openai' model: 'gpt-4o-mini' api_key: 'sk-your-openai-api-key'
3) Anthropic Claude
php_error_insight: backend: 'anthropic' model: 'claude-3-5-sonnet-20240620' api_key: 'your-anthropic-api-key'
4) Google (Generative AI)
php_error_insight: backend: 'google' model: 'gemini-1.5-flash' api_key: 'your-google-api-key'
5) Gemini (alias backend)
php_error_insight: backend: 'gemini' model: 'gemini-1.5-flash' api_key: 'your-google-api-key'
Usage
HTTP exceptions
The bundle registers a high‑priority listener for kernel.exception. When enabled is true, exceptions are rendered using PHP Error Insight’s renderer. If rendering fails or produces empty output, Symfony’s default error handling is used.
Console errors
A console event subscriber listens to ConsoleEvents::ERROR and, when enabled, prints the rendered output to the console. If rendering fails or produces empty output, normal console error output is preserved.
Programmatic usage
You can call the service directly:
use PhpErrorInsightBundle\Service\ErrorInsightService; final class YourController { public function __construct(private ErrorInsightService $errorInsightService) {} public function someAction(): Response { try { // ... your code } catch (\Throwable $e) { if ($this->errorInsightService->isEnabled()) { $html = $this->errorInsightService->renderException($e); // do something with $html (log, email, custom response, ...) } throw $e; // keep default handling flow } } }
Service IDs:
- PhpErrorInsightBundle\Service\ErrorInsightService(autowired)
- Alias: php_error_insight.service
How it works
- Exception interception (HTTP) via kernel.exceptionlistener
- Error interception (Console) via ConsoleEvents::ERRORsubscriber
- The bundle builds a Config and delegates rendering to the core library
- Graceful fallback to Symfony’s default error handling when needed
Environment considerations
It’s recommended to enable the bundle only in dev and/or test. You control this through:
- config/bundles.php(register the bundle for specific environments)
- php_error_insight.enabledsetting per environment config
Customization
- template: path to a custom HTML template supported by the core renderer
- editor_url: URL pattern to open files in your editor (e.g. PhpStorm)
- project_root/- host_root: map paths correctly between container and host
Troubleshooting
- Ensure the bundle is registered for the environment you’re using
- Verify php_error_insight.enabledis true for that environment
- For local backends, ensure your local service (e.g. Ollama) is running
- For API backends, verify api_keyand reachability ofapi_urlif applicable
- Check your logs for errors from the renderer or backend
Development
Run tests:
composer install
composer test
Quality tools:
composer quality composer fix-all
License
This bundle is licensed under the GPL-3.0-or-later license. See LICENSE for details.