PHPackages                             zaeem2396/runtime-insight - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. zaeem2396/runtime-insight

ActiveLibrary

zaeem2396/runtime-insight
=========================

AI-Augmented PHP Runtime Error Analyzer & Explainer for Laravel and Symfony applications

v0.1.0(1mo ago)10MITPHPPHP ^8.2CI passing

Since Apr 7Pushed 1mo agoCompare

[ Source](https://github.com/zaeem2396/runtime-insight)[ Packagist](https://packagist.org/packages/zaeem2396/runtime-insight)[ Docs](https://github.com/zaeem2396/runtime-insight)[ RSS](/packages/zaeem2396-runtime-insight/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (10)Versions (2)Used By (0)

Runtime Insight
===============

[](#runtime-insight)

 [![PHP Version](https://camo.githubusercontent.com/aa1b7e892437f6cb1a9ee2c6aa9b26589c8071c28741c0b5ca2241ad98504e6d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f7a6165656d323339362f72756e74696d652d696e7369676874)](https://camo.githubusercontent.com/aa1b7e892437f6cb1a9ee2c6aa9b26589c8071c28741c0b5ca2241ad98504e6d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f7a6165656d323339362f72756e74696d652d696e7369676874) [![Build Status](https://camo.githubusercontent.com/9584688c7286d8d93c4710dc201123c4dce7a89457012c02186c0663fb0c044e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7a6165656d323339362f72756e74696d652d696e73696768742f74657374732e796d6c3f6272616e63683d6d61696e)](https://camo.githubusercontent.com/9584688c7286d8d93c4710dc201123c4dce7a89457012c02186c0663fb0c044e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7a6165656d323339362f72756e74696d652d696e73696768742f74657374732e796d6c3f6272616e63683d6d61696e) [![Latest Version](https://camo.githubusercontent.com/c945dd1cc40ae6d19c3ccc92fc47e310a01bc644ed8a54a2d269844b6e10b9f7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7a6165656d323339362f72756e74696d652d696e7369676874)](https://camo.githubusercontent.com/c945dd1cc40ae6d19c3ccc92fc47e310a01bc644ed8a54a2d269844b6e10b9f7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7a6165656d323339362f72756e74696d652d696e7369676874) [![License](https://camo.githubusercontent.com/9ea31dc7e144e9d56fd58b7f431913d37bf621f552c14913ccc3ca73ba8d496e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f7a6165656d323339362f72756e74696d652d696e7369676874)](https://camo.githubusercontent.com/9ea31dc7e144e9d56fd58b7f431913d37bf621f552c14913ccc3ca73ba8d496e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f7a6165656d323339362f72756e74696d652d696e7369676874)

**AI-Augmented PHP Runtime Error Analyzer & Explainer** for Laravel and Symfony applications.

Transform cryptic runtime errors into human-readable explanations with actionable fix suggestions.

---

Documentation
-------------

[](#documentation)

DocumentWhat it covers**This README**Install, quick start, high-level features, configuration sketch, architecture overview, links to deeper topics**[USAGE.md](USAGE.md)**Laravel and Symfony integration, all Artisan/console commands, full configuration reference, caching, database and performance context, **root cause analysis** (metadata, `diagnostics`, custom analyzer), **events and `EventDispatcherInterface`**, **webhooks** (env vars, payload, security), AI providers, production hardening, troubleshooting**[CHANGELOG.md](CHANGELOG.md)**Notable changes by version (see **v0.1.0** for root cause Phase 2, events, webhooks, Symfony wiring)**[CONTRIBUTING.md](CONTRIBUTING.md)**Local setup, tests, PHPStan, code style, documentation expectations for contributors---

🎯 What is Runtime Insight?
--------------------------

[](#-what-is-runtime-insight)

Runtime Insight intercepts runtime exceptions and errors in your PHP applications, analyzes them using structured context and AI reasoning, and produces:

- **Plain-English explanations** of what went wrong
- **Root cause analysis** explaining *why* it happened
- **Actionable fix suggestions** to resolve the issue
- **Confidence scores** for AI-generated insights

### The Problem

[](#the-problem)

Typical PHP runtime errors provide:

```
Call to a member function id() on null

```

This tells you **what** failed, but not **why**.

### The Solution

[](#the-solution)

Runtime Insight explains:

```
❗ Runtime Error Explained

Error:
  Call to a member function id() on null

Why this happened:
  The `$user` variable is null because this route can be accessed
  without authentication, but the controller assumes a logged-in user.

Where:
  App\Http\Controllers\OrderController.php:42

Called from (fix here):
  App\Http\Controllers\OrderController.php:38

Code block (to update):
  →  42 |   return $user->id;

Suggested Fix:
  - Add authentication middleware to this route
  - OR guard access using:
    if ($request->user() === null) { ... }

Confidence: 0.92

```

---

✨ Features
----------

[](#-features)

- 🔍 **Smart Error Interception** - Hooks into Laravel & Symfony exception handling
- 📍 **Code Block to Update** - Shows the exact code snippet and call site so you know where to fix (file:line + snippet)
- 🧠 **AI-Powered Analysis** - Optional AI reasoning for complex errors
- 📚 **Rule-Based Patterns** - Fast, deterministic matching for common errors
- 🎨 **Multiple Output Formats** - Console, logs, or debug UI
- 🔌 **Framework Agnostic Core** - Shared logic between Laravel & Symfony
- 🛡️ **Privacy First** - Sanitized request data, environment-aware
- ⚡ **Non-Blocking** - Never interferes with your application's flow
- 💾 **Explanation Caching** - Cache repeated errors to reduce API calls
- 🗄️ **Database Query Context** - Optional recent queries in context (Laravel)
- 📊 **Memory & Performance Context** - Optional peak memory at time of error
- 🔄 **Runtime Intelligence Pipeline** - Signal collectors, root cause analyzer, and pattern analyzer (e.g. N+1, validation hints) enrich explanations via metadata
- 📜 **Log Analysis** - `runtime:analyze` summarizes error types and counts, highlights top failures by signature
- ⏱️ **Runtime Timeline** - `runtime:timeline` reconstructs events before the last failure (T+ seconds from log)
- 🔔 **Webhooks** - Optional HTTP POST to your URLs after each analysis (`AfterAnalysisEvent`), for Slack or internal alerts (failures logged only; see [USAGE.md](USAGE.md#webhooks-after-analysis))

---

🎯 Supported Error Types
-----------------------

[](#-supported-error-types)

Runtime Insight supports **all error types** with descriptive explanations (fixes [\#25](https://github.com/zaeem2396/runtime-insight/issues/25)):

- **Dedicated strategies** for common PHP errors (high confidence, specific cause and suggestions).
- **Descriptive fallback** for any other exception type (RuntimeException, LogicException, InvalidArgumentException, etc.) so you never get a generic “exception was thrown” message.

Error TypeExampleConfidence**Null Pointer**`Call to member function on null`0.85**Undefined Index**`Undefined array key "user_id"`0.88**Type Error**`Argument #1 must be of type string, int given`0.90**Argument Count**`Too few arguments to function`0.92**Class Not Found**`Class 'App\Models\User' not found`0.88**Division by Zero**`Division by zero`0.90**Parse Error**`syntax error, unexpected "}"`0.88**Value Error**`first(): Argument #1 must be a non-empty array`0.85Unmatched exceptions (e.g. `RuntimeException`, `InvalidArgumentException`) receive a **descriptive fallback** (cause + suggestions) instead of a generic message.

Each strategy provides:

- **Cause explanation** - Why the error occurred
- **Suggestions** - Actionable fixes
- **Context-aware hints** - Based on your source code

---

📋 Requirements
--------------

[](#-requirements)

- **PHP 8.2+**
- **Laravel 10+** or **Symfony 6.4+** (7.x also supported)
- **Guzzle 7** (already required) is used for optional webhook POST delivery

---

📦 Installation
--------------

[](#-installation)

```
composer require zaeem2396/runtime-insight
```

**Laravel:** After installing, add the OpenAI API key to your `.env` (used by default):

```
php artisan runtime:install
```

This appends `OPEN_AI_APIKEY=` to your `.env` if it is not already there. Set your [OpenAI API key](https://platform.openai.com/api-keys) as the value (you can also use `RUNTIME_INSIGHT_AI_KEY`). If you run `php artisan runtime:explain` without a key, you will see: *No OpenAI API key found. Set OPEN\_AI\_APIKEY or RUNTIME\_INSIGHT\_AI\_KEY in your .env file.*

🚀 Quick Start (Standalone)
--------------------------

[](#-quick-start-standalone)

```
use ClarityPHP\RuntimeInsight\RuntimeInsightFactory;

// Create an instance with default configuration
$insight = RuntimeInsightFactory::create();

try {
    // Your code that might throw an exception
    $user->getName(); // Throws: Call to member function on null
} catch (Throwable $e) {
    $explanation = $insight->analyze($e);

    echo $explanation->getMessage();     // The error message
    echo $explanation->getCause();       // Why it happened
    echo $explanation->getConfidence();  // 0.85

    foreach ($explanation->getSuggestions() as $suggestion) {
        echo "- $suggestion\n";
    }
}
```

### Laravel

[](#laravel)

The package auto-registers via Laravel's package discovery.

1. Publish the config (optional):

```
php artisan vendor:publish --tag=runtime-insight-config
```

2. Add your OpenAI API key (default AI provider):

```
php artisan runtime:install
```

Then set `OPEN_AI_APIKEY` or `RUNTIME_INSIGHT_AI_KEY` in `.env` to your key. If it is missing when you run the explain command, you will see *No OpenAI API key found.*

**Automatic Exception Analysis:**

Add the trait to your exception handler:

```
// app/Exceptions/Handler.php
use ClarityPHP\RuntimeInsight\Laravel\Traits\HandlesRuntimeInsight;

class Handler extends ExceptionHandler
{
    use HandlesRuntimeInsight;

    public function report(Throwable $e): void
    {
        $this->analyzeWithRuntimeInsight($e);
        parent::report($e);
    }
}
```

**Artisan Commands:**

```
# Add OPEN_AI_APIKEY to .env (run once after install)
php artisan runtime:install

# Explain the last error
php artisan runtime:explain

# Validate setup
php artisan runtime:doctor
```

### Symfony

[](#symfony)

Register the bundle in `config/bundles.php`:

```
return [
    // ...
    ClarityPHP\RuntimeInsight\Symfony\RuntimeInsightBundle::class => ['all' => true],
];
```

Create configuration in `config/packages/runtime_insight.yaml`:

```
runtime_insight:
    enabled: true
    ai:
        enabled: true
        provider: openai
        model: gpt-4.1-mini
    webhooks:
        enabled: false
        urls: []
```

---

⚙️ Configuration
----------------

[](#️-configuration)

```
// config/runtime-insight.php (Laravel)
return [
    'enabled' => true,

    'ai' => [
        'enabled' => true,
        'provider' => 'openai',      // openai (default), anthropic, ollama
        'model' => 'gpt-4.1-mini',
        // Set OPEN_AI_APIKEY in .env (or run php artisan runtime:install)
        'timeout' => 5,
    ],

    'context' => [
        'source_lines' => 10,        // Lines of code around error
        'include_request' => true,   // Include request context
        'sanitize_inputs' => true,   // Scrub sensitive data
        'include_database_queries' => false,  // Recent queries (Laravel query log)
        'max_database_queries' => 5,
        'include_performance_context' => false,  // Peak memory at time of error
    ],

    'cache' => [
        'enabled' => true,           // Cache repeated error explanations
        'ttl' => 3600,               // Seconds (default: 1 hour)
    ],

    // Optional: POST JSON after each analysis (Slack, internal HTTP). Off by default.
    'webhooks' => [
        'enabled' => false,
        'urls' => [],
        'timeout' => 3,
        'headers' => [],
    ],

    'environments' => ['local', 'staging'],  // Where to enable
];
```

---

🚀 Usage
-------

[](#-usage)

### Automatic Mode

[](#automatic-mode)

Once installed, Runtime Insight automatically intercepts exceptions and logs explanations.

### Artisan Commands (Laravel)

[](#artisan-commands-laravel)

```
# Explain the most recent runtime error
php artisan runtime:explain

# Explain a specific log entry (exception type is parsed from the log for accurate strategy matching)
php artisan runtime:explain --log=storage/logs/laravel.log --line=243

# Batch: explain all (or last N) exceptions in a log file
php artisan runtime:explain --log=storage/logs/laravel.log --all
php artisan runtime:explain --log=storage/logs/laravel.log --all --limit=5

# Write explanation to a file
php artisan runtime:explain --log=storage/logs/laravel.log --output=explanation.txt

# Analyze log file: summarize error counts and top failures
php artisan runtime:analyze storage/logs/laravel.log
php artisan runtime:analyze --top=20

# Show runtime timeline (events before last failure, T+ seconds)
php artisan runtime:timeline storage/logs/laravel.log
php artisan runtime:timeline --last=30

# Run diagnostics
php artisan runtime:doctor
```

### Console Commands (Symfony)

[](#console-commands-symfony)

```
# Explain the last exception
php bin/console runtime:explain

# Analyze log file: summarize error counts and top failures
php bin/console runtime:analyze var/log/dev.log

# Show runtime timeline (events before last failure)
php bin/console runtime:timeline var/log/dev.log
php bin/console runtime:timeline --last=30

# Validate setup
php bin/console runtime:doctor
```

See [USAGE.md](USAGE.md) for detailed documentation.

---

🏗️ Architecture
---------------

[](#️-architecture)

The runtime intelligence **pipeline** (inside `RuntimeInsight`) runs in a fixed order for `analyze()`, `analyzeFromLog()`, and `analyzeContext()`:

1. **Context** — `ContextBuilderInterface` builds `RuntimeContext` (exception, stack, source, framework context).
2. **Collectors** — Optional `CollectorRegistry` enriches context (queries, request snapshot, memory, queue, cache, etc.).
3. **`BeforeAnalysisEvent`** — Dispatched after enrichment, before the explanation engine runs. Listeners receive the current `RuntimeContext` (readonly DTO; copy/transform in your own code if you extend behaviour).
4. **Explanation** — `ExplanationEngineInterface` produces the core `Explanation` (strategies + optional AI).
5. **Root cause & pattern** — `RootCauseAnalyzerInterface` and `PatternAnalyzerInterface` attach metadata to the explanation when configured.
6. **`AfterAnalysisEvent`** — Dispatched with the final `Explanation` and `RuntimeContext`. Built-in **webhooks** (if enabled in config) register here as an `AfterAnalysisEvent` listener.
7. **Output** — Framework layers (Laravel `ExceptionHandler`, Symfony subscriber, Artisan/console commands) render or log results using renderers or plain logging.

```
┌──────────────────────┐
│ Framework / CLI      │  Laravel, Symfony, or RuntimeInsightFactory (standalone)
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│ ContextBuilder       │  RuntimeContext
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│ CollectorRegistry    │  Enriched RuntimeContext
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│ BeforeAnalysisEvent  │  EventDispatcherInterface
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│ ExplanationEngine    │  Explanation
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│ RootCause + Pattern  │  Explanation + metadata
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│ AfterAnalysisEvent   │  (+ optional HTTP webhooks to configured URLs)
└──────────┬───────────┘
           ▼
┌──────────────────────┐
│ Return / log / UI    │  Renderers, logs, commands
└──────────────────────┘

```

**Key types (PHP namespaces under `ClarityPHP\RuntimeInsight`):**

PieceType / classAnalyzer entrypoint`RuntimeInsight` (`AnalyzerInterface`)Events`Event\BeforeAnalysisEvent`, `Event\AfterAnalysisEvent`Dispatcher contract`Contracts\EventDispatcherInterface` (`dispatch`, `addListener`)Default dispatcher`Event\InMemoryEventDispatcher`Dispatcher construction`Event\InMemoryEventDispatcherFactory::create(Config, ?LoggerInterface)` — used by Laravel, Symfony, and `RuntimeInsightFactory::createWithConfig()` when no custom dispatcher is passedWebhook delivery`Contracts\WebhookSenderInterface`, `Webhook\GuzzleWebhookSender`, `Webhook\AfterAnalysisWebhookListener`Root cause analysis`Engine\RootCauseAnalyzer` (and `Engine\RootCause\*` helpers) attach structured `root_cause` metadata (primary cause, fixes, stack diagnostics)For **listener registration examples**, webhook **payload schema**, **root cause metadata**, and **every config key**, see [USAGE.md — Events and event dispatcher](USAGE.md#events-and-event-dispatcher), [USAGE.md — Root cause analysis](USAGE.md#root-cause-analysis), and [USAGE.md — Webhooks](USAGE.md#webhooks-after-analysis).

---

🔌 Extensibility
---------------

[](#-extensibility)

Runtime Insight is designed for extensibility:

- **AI Provider Factory** - `ProviderFactory` creates the configured provider (openai, anthropic, ollama) with optional fallback chain
- **Custom AI Providers** - Implement the `AIProviderInterface`
- **Explanation Caching** - When `cache.enabled` is true, the engine caches explanations by error signature (class, message, file, line) to avoid repeated AI calls
- **Events** - `EventDispatcherInterface` dispatches `BeforeAnalysisEvent` (after context enrichment) and `AfterAnalysisEvent` (after explanation, root cause, and pattern). The same dispatcher instance is injected into `RuntimeInsight` in Laravel and Symfony; use `addListener()` early in the container lifecycle (e.g. Laravel `AppServiceProvider::boot`) so listeners are registered before exceptions are analyzed. See [USAGE.md](USAGE.md#events-and-event-dispatcher).
- **Webhooks** - When `webhooks.enabled` is true and `urls` is non-empty, each URL receives a POST after `AfterAnalysisEvent`. Configure under `webhooks` in Laravel config or `runtime_insight.webhooks` in Symfony YAML. Environment: `RUNTIME_INSIGHT_WEBHOOKS_ENABLED`, `RUNTIME_INSIGHT_WEBHOOK_URLS`, `RUNTIME_INSIGHT_WEBHOOK_TIMEOUT`. Details: [USAGE.md](USAGE.md#webhooks-after-analysis).
- **Custom Explanation Strategies** - Add domain-specific patterns
- **Output & Rendering** - `RendererFactory::forFormat()` supports text, json, markdown, html, ide. Use `RendererInterface` for custom renderers.
- **Custom Renderers** - Output to JSON, HTML, Slack, etc.

```
// app/Providers/AppServiceProvider.php (excerpt) — register listeners in boot() so they
// exist before any exception is analyzed. Symfony: resolve EventDispatcherInterface from
// the container in a similar early service (e.g. an EventSubscriber on kernel.request).
namespace App\Providers;

use ClarityPHP\RuntimeInsight\Contracts\EventDispatcherInterface;
use ClarityPHP\RuntimeInsight\Event\AfterAnalysisEvent;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $this->app->make(EventDispatcherInterface::class)
            ->addListener(AfterAnalysisEvent::class, static function (AfterAnalysisEvent $e): void {
                // Read $e->explanation and $e->context; avoid heavy I/O on the exception path
            });
    }
}
```

```
use ClarityPHP\RuntimeInsight\Contracts\AIProviderInterface;

class CustomAIProvider implements AIProviderInterface
{
    public function getName(): string
    {
        return 'custom';
    }

    public function analyze(RuntimeContext $context): Explanation
    {
        // Your custom AI integration
    }

    public function isAvailable(): bool
    {
        return true;
    }
}
```

---

🚫 What This Package Does NOT Do
-------------------------------

[](#-what-this-package-does-not-do)

❌ Does NOT✅ DoesTrack errors (like Sentry)Explain errorsModify your codeSuggest fixesBlock requestsRun non-blockingExfiltrate dataKeep data localReplace error trackersComplement them---

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) before submitting a Pull Request.

```
# Clone the repository
git clone https://github.com/zaeem2396/runtime-insight.git
cd runtime-insight

# Install dependencies
composer install

# Run tests
composer test

# Run static analysis
composer analyse

# Check code style
composer cs-check
```

---

📄 License
---------

[](#-license)

Runtime Insight is open-sourced software licensed under the [MIT license](LICENSE).

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance94

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

32d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c2da070ec066ea427f578b46c3ae6a1f97220e75daeaa4c8a9456ffad75fa5bb?d=identicon)[zaeem2396](/maintainers/zaeem2396)

---

Top Contributors

[![zaeem2396](https://avatars.githubusercontent.com/u/31367343?v=4)](https://github.com/zaeem2396 "zaeem2396 (372 commits)")

---

Tags

phpsymfonylaravelaidebuggingexceptionerrorruntimewebhookanalyzerdeveloper-experienceexplainer

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/zaeem2396-runtime-insight/health.svg)

```
[![Health](https://phpackages.com/badges/zaeem2396-runtime-insight/health.svg)](https://phpackages.com/packages/zaeem2396-runtime-insight)
```

###  Alternatives

[aporat/store-receipt-validator

PHP receipt validator for Apple App Store and Amazon Appstore

6503.9M9](/packages/aporat-store-receipt-validator)[shopify/shopify-api

Shopify API Library for PHP

4634.8M16](/packages/shopify-shopify-api)[theodo-group/llphant

LLPhant is a library to help you build Generative AI applications.

1.5k311.5k5](/packages/theodo-group-llphant)[deepseek-php/deepseek-php-client

deepseek PHP client is a robust and community-driven PHP client library for seamless integration with the Deepseek API, offering efficient access to advanced AI and data processing capabilities.

47073.9k5](/packages/deepseek-php-deepseek-php-client)[cognesy/instructor-php

The complete AI toolkit for PHP: unified LLM API, structured outputs, agents, and coding agent control

310107.9k1](/packages/cognesy-instructor-php)[dragon-code/support

Support package is a collection of helpers and tools for any project.

238.7M101](/packages/dragon-code-support)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)