---
url: 'https://app-dev-panel.github.io/app-dev-panel/api.md'
---
# API Overview

ADP exposes three API domains over HTTP: **Debug** (stored debug entries), **Inspector** (live application state), and **Ingestion** (external data intake).

## Base URLs

| Domain | Base Path | Purpose |
|--------|-----------|---------|
| Debug | `/debug/api` | Access stored debug entries and SSE stream |
| Inspector | `/inspect/api` | Query live application state (routes, config, database, files) |
| Ingestion | `/debug/api/ingest` | Accept debug data from external applications |

## Response Format

All responses (except SSE and MCP) are wrapped in a standard envelope:

```json
{
    "id": "debug-entry-id",
    "data": { ... },
    "error": null,
    "success": true,
    "status": 200
}
```

On error, `success` is `false`, `error` contains the error message, and `data` is `null`.

## Middleware Chain

Every API request passes through:

1. **AppDevPanel\Api\Middleware\IpFilterMiddleware** -- validates request IP against allowed IPs (default: `127.0.0.1`, `::1`)
2. **AppDevPanel\Api\Middleware\CorsMiddleware** -- adds permissive CORS headers
3. **AppDevPanel\Api\Debug\Middleware\ResponseDataWrapper** -- wraps responses in the standard envelope
4. **AppDevPanel\Api\Debug\Middleware\DebugHeaders** -- adds `X-Debug-Id` and `X-Debug-Link` response headers

Inspector endpoints additionally pass through:

5. **AppDevPanel\Api\Inspector\Middleware\InspectorProxyMiddleware** -- routes `?service=<name>` requests to registered external services

## Authentication

By default, the API is restricted to localhost via IP filtering. An optional `auth_token` can be configured for additional security.

## Transports

* **REST** -- standard JSON request/response ([reference](./rest))
* **SSE** -- real-time push notifications for new debug entries ([reference](./sse))
* **MCP** -- JSON-RPC 2.0 endpoint for AI assistant integration ([reference](./inspector))

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/architecture.md'
---

# Architecture

ADP follows a strict layered architecture where each layer has clear responsibilities and dependencies flow in one direction.

## Layers

### 1. Kernel

The core engine. **Framework-independent** — depends only on PSR interfaces and generic PHP libraries. Manages:

* **Debugger** — Lifecycle management (start, collect, flush)
* **Collectors** — Gather runtime data via AppDevPanel\Kernel\Collector\CollectorInterface
* **Storage** — Persist debug data (JSON files by default) via AppDevPanel\Kernel\Storage\StorageInterface
* **Proxies** — Intercept PSR interfaces transparently

### 2. API

HTTP layer built on PSR-7/15. Provides:

* **REST endpoints** — Fetch debug entries, collector data
* **SSE** — Real-time notifications for new entries
* **Inspector** — Runtime inspection endpoints (config, routes, database schema, etc.)
* **MCP** — AI assistant integration via Model Context Protocol
* **Ingestion** — Accept debug data from external (non-PHP) applications

### 3. Adapters

Framework bridges. Each adapter:

* Registers proxy services in the framework's DI container
* Maps framework lifecycle events to AppDevPanel\Kernel\Debugger`::startup()` / `::shutdown()`
* Configures collectors and storage with framework-appropriate settings
* Registers API routes (`/debug/api/*`, `/inspect/api/*`)
* Serves the debug panel frontend at `/debug`
* Implements framework-specific inspector providers (config, routes, database schema)

### 4. Frontend

React 19 SPA with:

* Material-UI 5 design system
* Redux Toolkit for state management
* Module system (Debug, Inspector, LLM, MCP, OpenAPI, Frames)

## Dependency Graph

```
┌────────────────────────────────────────────────────────┐
│                  Dependency Direction                    │
│                                                         │
│   Adapter ──▶ API ──▶ Kernel                            │
│      │                   ▲                              │
│      └───────────────────┘                              │
│                                                         │
│   Cli ──▶ API ──▶ Kernel                                │
│                                                         │
│   Frontend ──▶ API (via HTTP only)                      │
└────────────────────────────────────────────────────────┘
```

* **Kernel** depends on nothing (PSR interfaces only)
* **API** depends only on Kernel
* **Cli** depends on Kernel and API
* **Adapter** depends on Kernel, API, and the target framework
* **Frontend** communicates via HTTP — no PHP dependencies

## Dependency Rules

The core principle: **common modules must never depend on framework-specific code**.

| Module | Can depend on | Cannot depend on |
|--------|--------------|-----------------|
| **Kernel** | PSR interfaces only | API, Cli, Adapter, any framework |
| **API** | Kernel, PSR interfaces | Adapter, any framework |
| **Cli** | Kernel, API, Symfony Console | Adapter, any framework |
| **Adapter** | Kernel, API, Cli, framework packages | Other adapters |
| **Frontend** | Nothing (HTTP only) | Any PHP package |

::: warning
Adapters must not depend on other adapters. Each adapter is an independent bridge between the Kernel and a specific framework.
:::

## Abstractions

Storage and serialization remain behind interfaces to ensure pluggability:

| Concern | Abstraction | Implementations |
|---------|-------------|-----------------|
| Debug data storage | AppDevPanel\Kernel\Storage\StorageInterface | AppDevPanel\Kernel\Storage\FileStorage, AppDevPanel\Kernel\Storage\MemoryStorage |
| Object serialization | AppDevPanel\Kernel\Dumper | JSON-based (built-in) |
| Database inspection | AppDevPanel\Api\Inspector\Database\SchemaProviderInterface | Per-adapter: AppDevPanel\Adapter\Yii3\Inspector\DbSchemaProvider, AppDevPanel\Adapter\Symfony\Inspector\DoctrineSchemaProvider, AppDevPanel\Adapter\Laravel\Inspector\LaravelSchemaProvider, AppDevPanel\Adapter\Yii2\Inspector\NullSchemaProvider, AppDevPanel\Adapter\Cycle\Inspector\CycleSchemaProvider |

## Data Flow

1. Target app runs with an Adapter installed
2. Adapter registers proxies that intercept PSR interfaces
3. Proxies feed data to Collectors
4. On request completion, Debugger flushes collector data to Storage
5. API serves stored data; SSE notifies the frontend
6. Frontend renders the data

See [Data Flow](/guide/data-flow) for the full lifecycle details.

## Frontend Module System

The frontend uses a module system where each module implements `ModuleInterface`:

```typescript
interface ModuleInterface {
    routes: RouteObject[];
    reducers: Record<string, Reducer>;
    middlewares: Middleware[];
    standalone: boolean;
}
```

Current modules: Debug, Inspector, LLM, MCP, OpenAPI, Frames.

## Creating a New Adapter

When creating an adapter for a new framework:

1. Create `libs/Adapter/<FrameworkName>/`
2. The adapter **must** depend on app-dev-panel/kernel
3. The adapter **may** depend on app-dev-panel/api (for route and inspector registration)
4. The adapter **may** depend on app-dev-panel/cli (for CLI commands)
5. The adapter **must not** depend on other adapters
6. The adapter **must not** modify Kernel or API code — only wire into them via configuration

### Adapter Responsibilities

| Responsibility | Description |
|----------------|-------------|
| Lifecycle mapping | Map framework events → AppDevPanel\Kernel\Debugger`::startup()` / `::shutdown()` |
| Proxy wiring | Register Kernel PSR proxies as service decorators in the framework's DI |
| Framework-specific proxies | Create proxies for non-PSR APIs (e.g., AppDevPanel\Adapter\Symfony\Proxy\SymfonyEventDispatcherProxy) |
| Collector configuration | Configure active collectors and pass framework-specific settings |
| Storage setup | Wire AppDevPanel\Kernel\Storage\StorageInterface with framework-appropriate paths |
| Route registration | Register API routes for `/debug/api/*`, `/inspect/api/*` and serve the frontend at `/debug` |
| Inspector providers | Implement AppDevPanel\Api\Inspector\Database\SchemaProviderInterface, AppDevPanel\Api\Inspector\Elasticsearch\ElasticsearchProviderInterface, etc. |

### Reference Implementations

| Adapter | Framework | Pattern |
|---------|-----------|---------|
| Symfony | Symfony 6.4–8.x | Bundle + Extension + CompilerPass |
| Yii2 | Yii 2 | Module + BootstrapInterface |
| Yii 3 | Yii 3 | Config plugin + ServiceProvider |
| Laravel | Laravel 11.x–12.x | ServiceProvider (register + boot) |

### Minimal Checklist

1. `composer.json` with app-dev-panel/kernel + app-dev-panel/api dependencies
2. Lifecycle event mapping → AppDevPanel\Kernel\Debugger`::startup()` / `::shutdown()`
3. Register Kernel PSR proxies as service decorators (logger, events, HTTP client)
4. Wire AppDevPanel\Kernel\Storage\FileStorage with a framework-appropriate path
5. Register API controller routes
6. Create a [playground](/guide/playgrounds) for testing and demo

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/asset-bundle.md'
---

# AssetBundle Collector

Captures registered frontend asset bundles — CSS files, JavaScript files, dependencies, and configuration.

## What It Captures

| Field | Description |
|-------|-------------|
| `class` | Asset bundle class name |
| `sourcePath` | Source path for published assets |
| `basePath` | Published base path |
| `baseUrl` | Published base URL |
| `css` | CSS file list |
| `js` | JavaScript file list |
| `depends` | Bundle dependencies |
| `options` | Bundle options |

## Data Schema

```json
{
    "bundles": {
        "AppAsset": {
            "class": "App\\Assets\\AppAsset",
            "sourcePath": "/app/assets",
            "basePath": "/public/assets/abc123",
            "baseUrl": "/assets/abc123",
            "css": ["css/app.css"],
            "js": ["js/app.js"],
            "depends": ["yii\\web\\JqueryAsset"],
            "options": {}
        }
    },
    "bundleCount": 3
}
```

**Summary** (shown in debug entry list):

```json
{
    "assets": {
        "bundleCount": 3
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\AssetBundleCollector;

$collector->collectBundle(name: 'AppAsset', bundle: [
    'class' => 'App\\Assets\\AppAsset',
    'css' => ['css/app.css'],
    'js' => ['js/app.js'],
    'depends' => ['yii\\web\\JqueryAsset'],
]);

// Or collect all bundles at once
$collector->collectBundles(bundles: $allBundles);
```

::: info
\AppDevPanel\Kernel\Collector\AssetBundleCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface and depends on \AppDevPanel\Kernel\Collector\TimelineCollector. Primarily used with Yii frameworks.
:::

## Debug Panel

* **Bundle list** — all registered asset bundles with file counts
* **Asset files** — CSS and JS files per bundle
* **Dependency tree** — bundle dependency graph

---

---
url: >-
  https://app-dev-panel.github.io/app-dev-panel/guide/collectors/authorization.md
---

# Authorization Collector

Captures authentication and authorization data — user identity, roles, tokens, access decisions, guards, role hierarchy, and impersonation status.

![Authorization Collector panel](/images/collectors/authorization.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `username` | Authenticated user identifier |
| `roles` | Assigned roles |
| `effectiveRoles` | Roles after hierarchy resolution |
| `authenticated` | Whether the user is authenticated |
| `firewallName` | Active firewall/guard name |
| `token` | Auth token details (type, attributes, expiration) |
| `impersonation` | Impersonation data (original and impersonated user) |
| `guards` | Registered authentication guards |
| `roleHierarchy` | Role inheritance tree |
| `authenticationEvents` | Login/logout/failure events |
| `accessDecisions` | Authorization check results (granted/denied) |

## Data Schema

```json
{
    "username": "admin@example.com",
    "roles": ["ROLE_ADMIN"],
    "effectiveRoles": ["ROLE_ADMIN", "ROLE_USER"],
    "firewallName": "main",
    "authenticated": true,
    "token": {
        "type": "Bearer",
        "attributes": {},
        "expiresAt": "2026-03-31T23:59:59+00:00"
    },
    "impersonation": null,
    "guards": [
        {"name": "main", "provider": "users", "config": {}}
    ],
    "roleHierarchy": {"ROLE_ADMIN": ["ROLE_USER"]},
    "authenticationEvents": [
        {"type": "login", "provider": "form", "result": "success", "time": 1711878000.1, "details": {}}
    ],
    "accessDecisions": [
        {"attribute": "ROLE_ADMIN", "subject": "route:/admin", "result": "granted", "voters": [...], "duration": 0.0001, "context": {}}
    ]
}
```

**Summary** (shown in debug entry list):

```json
{
    "authorization": {
        "username": "admin@example.com",
        "authenticated": true,
        "roles": ["ROLE_ADMIN"],
        "accessDecisions": {"total": 3, "granted": 3, "denied": 0},
        "authEvents": 1
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\AuthorizationCollector;

$collector->collectUser(
    username: 'admin@example.com',
    roles: ['ROLE_ADMIN'],
    authenticated: true,
);
$collector->collectFirewall(firewallName: 'main');
$collector->collectToken(type: 'Bearer', attributes: [], expiresAt: '2026-03-31T23:59:59+00:00');
$collector->collectRoleHierarchy(hierarchy: ['ROLE_ADMIN' => ['ROLE_USER']]);
$collector->collectEffectiveRoles(effectiveRoles: ['ROLE_ADMIN', 'ROLE_USER']);

$collector->logAccessDecision(
    attribute: 'ROLE_ADMIN',
    subject: 'route:/admin',
    result: 'granted',
    voters: [...],
);
```

::: info
\AppDevPanel\Kernel\Collector\AuthorizationCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface. It has no dependencies on other collectors.
:::

## How It Works

Framework adapters extract authentication state from the security component:

* **Symfony**: Security token, firewall, voter results via event listeners
* **Laravel**: Auth guards, Gate authorization checks
* **Yii 3**: Identity interface and RBAC system

## Debug Panel

* **User identity** — username, authentication status, roles
* **Access decisions** — list of authorization checks with granted/denied results
* **Role hierarchy** — visual role inheritance tree
* **Auth events** — login, logout, and failure events
* **Token details** — token type, attributes, and expiration

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/inspector/authorization.md'
---

# Authorization Inspector

Inspect the security and authorization configuration of your application.

![Authorization Inspector](/images/inspector/authorization.png)

## What It Shows

| Section | Description |
|---------|-------------|
| Guards | Security guards/firewalls configuration |
| Role hierarchy | Role inheritance tree |
| Voters | Authorization voters/policies registered |
| Security config | Full security configuration dump |

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/inspect/api/authorization` | Guards, role hierarchy, voters, security config |

## Adapter Support

| Adapter | Provider |
|---------|----------|
| Symfony | AppDevPanel\Adapter\Symfony\Inspector\SymfonyConfigProvider (reads `security.yaml` config) |
| Others | AppDevPanel\Api\Inspector\Authorization\NullAuthorizationConfigProvider (returns empty) |

::: info
Authorization inspection requires framework-specific integration. Currently, only the Symfony adapter provides full security config introspection.
:::

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/cache.md'
---

# Cache Collector

Captures cache operations (get, set, delete) with hit/miss rates, timing, and per-pool breakdowns.

![Cache Collector panel](/images/collectors/cache.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `pool` | Cache pool name (e.g., `default`, `sessions`) |
| `operation` | Operation type (`get`, `set`, `delete`, `has`, `clear`) |
| `key` | Cache key |
| `hit` | Whether the operation was a cache hit |
| `duration` | Operation execution time in seconds |
| `value` | Cached value (for get/set operations) |

## Data Schema

```json
{
    "operations": [
        {
            "pool": "default",
            "operation": "get",
            "key": "user:42",
            "hit": true,
            "duration": 0.0003,
            "value": {"name": "John"}
        }
    ],
    "hits": 8,
    "misses": 2,
    "totalOperations": 10
}
```

**Summary** (shown in debug entry list):

```json
{
    "cache": {
        "hits": 8,
        "misses": 2,
        "totalOperations": 10
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\CacheCollector;
use AppDevPanel\Kernel\Collector\CacheOperationRecord;

$collector->logCacheOperation(new CacheOperationRecord(
    pool: 'default',
    operation: 'get',
    key: 'user:42',
    hit: true,
    duration: 0.0003,
    value: ['name' => 'John'],
));
```

::: info
\AppDevPanel\Kernel\Collector\CacheCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface and depends on \AppDevPanel\Kernel\Collector\TimelineCollector.
:::

## How It Works

Framework adapters intercept PSR-16 Psr\SimpleCache\CacheInterface operations through the `CacheInterfaceProxy` decorator. Every `get()`, `set()`, `delete()`, `has()`, and `clear()` call is automatically captured.

## Debug Panel

* **Hit rate summary** — total operations, hits, misses with percentage
* **Per-pool breakdown** — statistics grouped by cache pool when multiple pools are used
* **Operation list** — filterable list with operation type, key, hit/miss status, and timing
* **Color coding** — hits (green), misses (orange), deletes (yellow)
* **Value preview** — expandable cached values for get/set operations

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/inspector/cache.md'
---

# Cache Inspector

View, delete, and clear PSR-16 cache entries.

## What It Shows

| Feature | Description |
|---------|-------------|
| View | Retrieve a cached value by key |
| Delete | Remove a specific cache key |
| Clear | Flush the entire cache |

## How To Use

Enter a cache key to view its stored value. The inspector displays the deserialized value with type information.

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/inspect/api/cache?key=my_cache_key` | View cached value |
| DELETE | `/inspect/api/cache?key=my_cache_key` | Delete a cache key |
| POST | `/inspect/api/cache/clear` | Clear entire cache |

## Requirements

Requires a PSR-16 Psr\SimpleCache\CacheInterface implementation registered in the DI container.

::: warning
The **Clear** action is destructive — it removes all cache entries. Use with care in production.
:::

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/ci-and-tooling.md'
---

# CI & Tooling

ADP uses GitHub Actions for continuous integration and [Mago](https://mago.carthage.software/) for PHP code quality enforcement.

## Mago — PHP Toolchain

Mago is a Rust-powered toolchain that replaces PHPStan, PHP-CS-Fixer, and Psalm with a single binary. It provides three tools:

| Tool | Purpose | Command |
|------|---------|---------|
| **Formatter** | Enforces PSR-12 code style | `make mago-format` |
| **Linter** | Finds code smells, inconsistencies, anti-patterns | `make mago-lint` |
| **Analyzer** | Static analysis: type errors, null safety, logic bugs | `make mago-analyze` |

### Running Mago

```bash
make mago                 # Run all checks (format + lint + analyze)
make mago-fix             # Fix formatting, then lint + analyze
make mago-playgrounds     # Check all playground apps
make mago-playgrounds-fix # Fix formatting in playground apps
```

### Configuration

Mago is configured via `mago.toml` in the project root:

```toml
[source]
paths = ["libs/Kernel/src", "libs/API/src", ...]
includes = ["vendor"]     # Parsed for type info only

[formatter]
preset = "psr-12"

[linter]
default-level = "warning"
```

### Baselines

Existing lint issues in legacy code are suppressed via `mago-lint-baseline.php`. The analyzer has no baseline — rules that produce false positives are suppressed via `ignore` in `mago.toml`. New code must not introduce new issues.

```bash
composer lint:baseline    # Regenerate lint baseline
```

## PHPUnit — Testing

Tests are organized per-module with a unified root `phpunit.xml.dist`:

```bash
make test-php             # Run all PHP tests
```

### Test Suites

| Suite | Directory |
|-------|-----------|
| Kernel | `libs/Kernel/tests` |
| API | `libs/API/tests` |
| Cli | `libs/Cli/tests` |
| Adapter/Symfony | `libs/Adapter/Symfony/tests` |
| Adapter/Laravel | `libs/Adapter/Laravel/tests` |
| Adapter/Yii2 | `libs/Adapter/Yii2/tests` |
| Adapter/Cycle | `libs/Adapter/Cycle/tests` |
| McpServer | `libs/McpServer/tests` |

### Coverage

Coverage requires the PCOV extension:

```bash
pecl install pcov
php vendor/bin/phpunit --coverage-text          # Text summary
php vendor/bin/phpunit --coverage-html=coverage  # HTML report
```

## Frontend Checks

```bash
make frontend-check       # Prettier + ESLint
make frontend-fix         # Auto-fix issues
make test-frontend        # Vitest unit tests
make test-frontend-e2e    # Browser tests (requires Chrome)
```

## GitHub Actions

### CI Workflow (`ci.yml`)

Runs on every push and PR.

**Test matrix:**

| OS | PHP 8.4 | PHP 8.5 |
|----|:-------:|:-------:|
| Linux | ✅ | ✅ |
| Windows | ✅ | ✅ |

**Mago checks** run as separate parallel jobs:

* `mago fmt --check`
* `mago lint --reporting-format=github` (annotates PR files)
* `mago analyze --reporting-format=github` (annotates PR files)

### PR Report (`pr-report.yml`)

Runs on PRs only. Posts two comments:

1. **Coverage report** — Code coverage summary from PHPUnit
2. **Mago report** — Pass/fail status for format, lint, analyze with expandable output on failure

## Full Pipeline

Run the complete CI pipeline locally:

```bash
make ci                   # Full CI: all checks + all tests
make check                # Checks only (Mago + frontend)
make test                 # Tests only (PHP + frontend)
make all                  # Same as make check && make test
```

## Adding a New Library

When adding a new library under `libs/`:

1. Add its `src/` and `tests/` paths to `mago.toml` under `[source] paths`
2. Add its test directory to `phpunit.xml.dist` as a new `<testsuite>`
3. Add its `src/` directory to the `<source><include>` section of `phpunit.xml.dist`

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/cli.md'
---

# CLI Commands

ADP provides console commands for managing the debug system. All commands are built on Symfony Console and available through your framework's CLI runner or the standalone `debug:serve` server.

## Available Commands

### `dev` -- Debug Server

Starts a UDP socket server that receives real-time debug messages from the application.

```bash
php yii dev                         # Default: 0.0.0.0:8890
php yii dev -a 127.0.0.1 -p 9000   # Custom address and port
```

The server receives and displays three message types:

* Variable dumps (`MESSAGE_TYPE_VAR_DUMPER`)
* Log messages (`MESSAGE_TYPE_LOGGER`)
* Plain text messages

Supports graceful shutdown via `SIGINT` (Ctrl+C).

### `debug:reset` -- Clear Debug Data

Stops the debugger and clears all stored debug data.

```bash
php yii debug:reset
```

Internally calls AppDevPanel\Kernel\Debugger`::stop()` followed by AppDevPanel\Kernel\Storage\StorageInterface`::clear()`.

### `dev:broadcast` -- Broadcast Test Messages

Sends test messages to all connected debug server clients. Useful for verifying connectivity.

```bash
php yii dev:broadcast                    # Default: "Test message"
php yii dev:broadcast -m "Hello world"   # Custom message
```

### `debug:query` -- Query Debug Data

Query stored debug data from the command line.

```bash
debug:query list                          # List recent entries (default 20)
debug:query list --limit=5                # Limit entries
debug:query list --json                   # Raw JSON output
debug:query view <id>                     # Full entry data
debug:query view <id> -c <CollectorFQCN>  # Specific collector data
```

### `debug:serve` -- Standalone ADP Server

Starts a standalone HTTP server using PHP's built-in server, serving the ADP API directly. No framework required.

```bash
debug:serve                                       # Default: 127.0.0.1:8888
debug:serve --host=0.0.0.0 --port=9000            # Custom host/port
debug:serve --storage-path=/path/to/debug/data    # Custom storage directory
debug:serve --frontend-path=/path/to/built/assets # Serve frontend assets
```

### `mcp:serve` -- MCP Server (stdio)

Starts the MCP server in stdio mode for AI assistant integration. See the [MCP Server](./mcp-server.md) page for details.

```bash
php yii mcp:serve --storage-path=/path/to/debug-data
```

## Command Summary

| Command | Purpose |
|---------|---------|
| `dev` | Start real-time UDP debug server |
| `debug:reset` | Clear all stored debug data |
| `dev:broadcast` | Send test messages to debug server |
| `debug:query` | Query stored entries from CLI |
| `debug:serve` | Start standalone HTTP API server |
| `mcp:serve` | Start MCP server (stdio transport) |

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/inspector/coverage.md'
---

# Code Coverage

Collect and view PHP code coverage data in real-time.

![Code Coverage](/images/inspector/coverage.png)

## What It Shows

| Field | Description |
|-------|-------------|
| Driver | Coverage driver in use (`pcov` or `xdebug`) |
| Total files | Number of files with coverage data |
| Covered lines | Lines executed during the request |
| Executable lines | Total lines that can be executed |
| Percentage | Overall coverage percentage |

## Per-File Coverage

Click a file to see line-by-line coverage highlighting — which lines were executed (green) and which were missed (red).

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/inspect/api/coverage` | Collect coverage data with per-file stats |
| GET | `/inspect/api/coverage/file?path=/src/Service.php` | Read source file for coverage display |

## Requirements

Requires one of:

* **PCOV** extension (recommended, lightweight)
* **Xdebug** extension with coverage mode enabled

::: warning
Code coverage collection adds overhead. Enable only during development/testing.
:::

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors.md'
---

# Collectors

Collectors are the core data-gathering mechanism in ADP. Each collector implements AppDevPanel\Kernel\Collector\CollectorInterface and is responsible for capturing a specific type of runtime data during the application lifecycle.

## Built-in Collectors

### Core Collectors

| Collector | Data Collected | Guide |
|-----------|---------------|-------|
| AppDevPanel\Kernel\Collector\LogCollector | PSR-3 log messages (level, message, context) | [Log](/guide/collectors/log) |
| AppDevPanel\Kernel\Collector\EventCollector | PSR-14 dispatched events and listeners | [Event](/guide/collectors/event) |
| AppDevPanel\Kernel\Collector\ExceptionCollector | Uncaught exceptions with stack traces | [Exception](/guide/collectors/exception) |
| AppDevPanel\Kernel\Collector\HttpClientCollector | PSR-18 outgoing HTTP requests and responses | [HTTP Client](/guide/collectors/http-client) |
| AppDevPanel\Kernel\Collector\DatabaseCollector | SQL queries, execution time, transactions | [Database](/guide/collectors/database) |
| AppDevPanel\Kernel\Collector\ElasticsearchCollector | Elasticsearch requests, timing, hits count | [Elasticsearch](/guide/collectors/elasticsearch) |
| AppDevPanel\Kernel\Collector\CacheCollector | Cache get/set/delete operations with hit/miss rates | [Cache](/guide/collectors/cache) |
| AppDevPanel\Kernel\Collector\RedisCollector | Redis commands with timing and error tracking | [Redis](/guide/collectors/redis) |
| AppDevPanel\Kernel\Collector\MailerCollector | Sent email messages | [Mailer](/guide/collectors/mailer) |
| AppDevPanel\Kernel\Collector\TranslatorCollector | Translation lookups, missing translations | [Translator](/guide/collectors/translator) |
| AppDevPanel\Kernel\Collector\QueueCollector | Message queue operations (push, consume, fail) | [Queue](/guide/collectors/queue) |
| AppDevPanel\Kernel\Collector\ServiceCollector | DI container service resolutions | [Service](/guide/collectors/service) |
| AppDevPanel\Kernel\Collector\RouterCollector | HTTP route matching data | [Router](/guide/collectors/router) |
| AppDevPanel\Kernel\Collector\MiddlewareCollector | Middleware stack execution and timing | [Middleware](/guide/collectors/middleware) |
| AppDevPanel\Kernel\Collector\ValidatorCollector | Validation operations and results | [Validator](/guide/collectors/validator) |
| AppDevPanel\Kernel\Collector\AuthorizationCollector | Authentication and authorization data | [Authorization](/guide/collectors/authorization) |
| AppDevPanel\Kernel\Collector\TemplateCollector | Template/view rendering with timing, output capture, and duplicate detection | [Template](/guide/collectors/template) |
| AppDevPanel\Kernel\Collector\VarDumperCollector | Manual `dump()` / `dd()` calls | [VarDumper](/guide/collectors/var-dumper) |
| AppDevPanel\Kernel\Collector\TimelineCollector | Cross-collector performance timeline | [Timeline](/guide/collectors/timeline) |
| AppDevPanel\Kernel\Collector\EnvironmentCollector | PHP and OS environment info | [Environment](/guide/collectors/environment) |
| AppDevPanel\Kernel\Collector\DeprecationCollector | PHP deprecation warnings | [Deprecation](/guide/collectors/deprecation) |
| AppDevPanel\Kernel\Collector\OpenTelemetryCollector | OpenTelemetry spans and traces | [OpenTelemetry](/guide/collectors/opentelemetry) |
| AppDevPanel\Kernel\Collector\AssetBundleCollector | Frontend asset bundles (Yii) | [Asset Bundle](/guide/collectors/asset-bundle) |
| AppDevPanel\Kernel\Collector\Stream\FilesystemStreamCollector | Filesystem stream operations | [Filesystem Stream](/guide/collectors/filesystem-stream) |
| AppDevPanel\Kernel\Collector\Stream\HttpStreamCollector | HTTP stream wrapper operations | [HTTP Stream](/guide/collectors/http-stream) |
| AppDevPanel\Kernel\Collector\CodeCoverageCollector | Per-request PHP line coverage (requires pcov or xdebug) | [Coverage](/guide/inspector/coverage) |

### Web-Specific

| Collector | Data Collected | Guide |
|-----------|---------------|-------|
| AppDevPanel\Kernel\Collector\Web\RequestCollector | Incoming HTTP request and response details | [Request](/guide/collectors/request) |
| AppDevPanel\Kernel\Collector\Web\WebAppInfoCollector | PHP version, memory, execution time | [Web App Info](/guide/collectors/web-app-info) |

### Console-Specific

| Collector | Data Collected | Guide |
|-----------|---------------|-------|
| AppDevPanel\Kernel\Collector\Console\CommandCollector | Console command executions | [Command](/guide/collectors/command) |
| AppDevPanel\Kernel\Collector\Console\ConsoleAppInfoCollector | Console application metadata | [Console App Info](/guide/collectors/console-app-info) |

## CollectorInterface

Every collector implements five methods:

```php
interface CollectorInterface
{
    public function getId(): string;       // Unique ID (typically FQCN)
    public function getName(): string;     // Human-readable short name
    public function startup(): void;       // Called at request start
    public function shutdown(): void;      // Called at request end
    public function getCollected(): array; // Returns all collected data
}
```

The AppDevPanel\Kernel\Debugger calls `startup()` on all registered collectors at the beginning of a request, and `shutdown()` followed by `getCollected()` at the end.

## Creating a Custom Collector

```php
<?php

declare(strict_types=1);

namespace App\Debug;

use AppDevPanel\Kernel\Collector\CollectorInterface;

final class MetricsCollector implements CollectorInterface
{
    private array $metrics = [];

    public function getId(): string
    {
        return self::class;
    }

    public function getName(): string
    {
        return 'metrics';
    }

    public function startup(): void
    {
        $this->metrics = [];
    }

    public function shutdown(): void
    {
        // Finalize data if needed
    }

    public function getCollected(): array
    {
        return $this->metrics;
    }

    public function record(string $name, float $value): void
    {
        $this->metrics[] = ['name' => $name, 'value' => $value];
    }
}
```

Register the collector in your framework adapter's DI configuration so the `Debugger` picks it up automatically.

## Data Flow

Collectors receive data in two ways:

1. **Via proxies** -- PSR interface proxies (e.g., AppDevPanel\Kernel\Collector\LoggerInterfaceProxy) intercept calls and feed data to their paired collector automatically.
2. **Via direct calls** -- Adapter hooks or application code call methods on the collector directly (e.g., AppDevPanel\Kernel\Collector\DatabaseCollector receives query data from framework-specific database hooks).

## SummaryCollectorInterface

Collectors can also implement AppDevPanel\Kernel\Collector\SummaryCollectorInterface to provide summary data displayed in the debug entry list without loading full collector data.

## TranslatorCollector

Captures translation lookups during request execution, including missing translation detection. Implements AppDevPanel\Kernel\Collector\SummaryCollectorInterface.

See the dedicated [Translator](/guide/translator) page for full details: TranslationRecord fields, collected data structure, missing detection logic, framework proxy integrations, and configuration examples.

## Code Coverage Collector

AppDevPanel\Kernel\Collector\CodeCoverageCollector captures per-request PHP line coverage using [pcov](https://github.com/krakjoe/pcov) or [xdebug](https://xdebug.org/) as the coverage driver.

::: warning Prerequisites
Requires the **pcov** extension (recommended) or **xdebug** with coverage mode enabled. Without either, the collector returns an empty result with `driver: null`.
:::

### How It Works

1. On `startup()`, the collector detects the available driver and starts coverage collection
2. Your application code runs normally — every executed PHP line is tracked
3. On `shutdown()`, coverage is stopped and raw data is processed into per-file statistics
4. Files matching `excludePaths` (default: `vendor`) are filtered out

### Enabling

Code coverage is **opt-in** (disabled by default) due to performance overhead.

:::tabs key:framework
\== Symfony

```yaml
# config/packages/app_dev_panel.yaml
app_dev_panel:
    collectors:
        code_coverage: true
```

\== Laravel

```php
// config/app-dev-panel.php
'collectors' => [
    'code_coverage' => true,
],
```

\== Yii 2

```php
// config/web.php — modules.debug-panel
'collectors' => [
    'code_coverage' => true,
],
```

:::

### Output Format

```json
{
    "driver": "pcov",
    "files": {
        "/app/src/Controller/HomeController.php": {
            "coveredLines": 12,
            "executableLines": 15,
            "percentage": 80.0
        }
    },
    "summary": {
        "totalFiles": 42,
        "coveredLines": 340,
        "executableLines": 500,
        "percentage": 68.0
    }
}
```

### Inspector Endpoint

The inspector also provides a live coverage endpoint at `GET /inspect/api/coverage` that performs a one-shot coverage collection. See [Inspector Endpoints](/api/inspector) for details.

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/command.md'
---

# Command Collector

Captures console command executions — command name, input/output, arguments, options, exit code, and errors.

## What It Captures

| Field | Description |
|-------|-------------|
| `name` | Command name |
| `command` | Command object |
| `input` | Command input string |
| `output` | Command output |
| `exitCode` | Process exit code |
| `error` | Error message if command failed |
| `arguments` | Command arguments |
| `options` | Command options |

## Data Schema

```json
{
    "command": {
        "name": "app:import-users",
        "class": "App\\Command\\ImportUsersCommand",
        "input": "app:import-users --force",
        "output": "Imported 42 users.",
        "exitCode": 0,
        "error": null,
        "arguments": {},
        "options": {"force": true}
    }
}
```

**Summary** (shown in debug entry list):

```json
{
    "command": {
        "name": "app:import-users",
        "class": "App\\Command\\ImportUsersCommand",
        "input": "app:import-users --force",
        "exitCode": 0
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\Console\CommandCollector;

// Collect from Symfony Console events
$collector->collect(event: $consoleEvent);

// Or collect raw command data
$collector->collectCommandData([
    'name' => 'app:import-users',
    'input' => 'app:import-users --force',
    'exitCode' => 0,
]);
```

::: info
\AppDevPanel\Kernel\Collector\Console\CommandCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface and depends on \AppDevPanel\Kernel\Collector\TimelineCollector. Located in the `Console` sub-namespace.
:::

## How It Works

Framework adapters hook into console event lifecycle:

* **Symfony**: `ConsoleCommandEvent`, `ConsoleTerminateEvent`, `ConsoleErrorEvent`
* **Laravel**: Artisan command events
* **Yii 3**: Console application events

## Debug Panel

* **Command details** — name, class, input, and exit code
* **Output capture** — full command output
* **Error display** — error message and trace for failed commands

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/inspector/commands.md'
---

# Commands

Run application commands directly from the debug panel — tests, static analysis, and composer scripts.

![Commands](/images/inspector/commands.png)

## Available Command Types

| Type | Description |
|------|-------------|
| PHPUnit | Run unit tests with JSON-formatted output |
| Codeception | Run Codeception tests with JSON reporter |
| Psalm | Run Psalm static analysis with JSON report |
| Composer scripts | All scripts from `composer.json` (auto-discovered) |
| Bash | Execute arbitrary shell commands |

## How It Works

Commands are automatically discovered from two sources:

1. **Registered commands** — PHPUnit, Codeception, Psalm (if configured in the adapter)
2. **Composer scripts** — All `scripts` entries from `composer.json` are exposed as `composer/{scriptName}` commands

Click a command button to execute it. Output is displayed in real-time.

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/inspect/api/command` | List available commands |
| POST | `/inspect/api/command?command=composer/test` | Execute a command |

**Response format:**

```json
{
    "status": "ok",
    "result": "PHPUnit 11.0.0 ...\nOK (42 tests, 100 assertions)",
    "error": ""
}
```

::: tip
PHPUnit and Codeception commands use custom JSON reporters for structured output in the panel.
:::

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/inspector/composer.md'
---

# Composer Inspector

Browse installed packages, inspect package details, and install new dependencies from the panel.

![Composer Inspector](/images/inspector/composer.png)

## Tabs

### Packages

Lists all installed Composer packages with version info. Shows both `require` and `require-dev` dependencies. Click **Switch** to toggle between production and development packages.

### composer.json

View the raw `composer.json` contents.

### composer.lock

View the raw `composer.lock` contents (if present).

## Package Inspection

Click a package to see detailed info via `composer show --all --format=json`:

* Description, homepage, license
* All available versions
* Dependencies and conflicts
* Installation source

## Install Packages

Install new packages directly from the panel:

* Specify package name and optional version constraint
* Choose between `--dev` and production dependency
* Runs `composer require` in non-interactive mode

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/inspect/api/composer` | Get composer.json and composer.lock |
| GET | `/inspect/api/composer/inspect?package=vendor/name` | Package details |
| POST | `/inspect/api/composer/require` | Install a package |

**Install request body:**

```json
{
    "package": "vendor/package-name",
    "version": "^2.0",
    "isDev": false
}
```

::: warning
Package installation modifies `composer.json` and `composer.lock`. This runs `composer require` on the server.
:::

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/inspector/config.md'
---

# Configuration Inspector

Inspect your application's DI container configuration, service definitions, and parameters.

![Configuration Inspector](/images/inspector/config.png)

## Tabs

### Parameters

View all application parameters and their values. Includes framework-specific parameters (e.g., `kernel.project_dir` for Symfony, `app.debug` for Laravel).

### Definitions

Browse all service class definitions registered in the DI container. See which classes and interfaces are available for dependency injection.

### Container

Inspect individual container services. View how a service is configured, its dependencies, and runtime state.

## Container Entry Viewer

Click any service to see its full object dump — properties, dependencies, and configuration values resolved at runtime.

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/inspect/api/params` | Application parameters |
| GET | `/inspect/api/config` | DI configuration by group |
| GET | `/inspect/api/classes` | All declared classes/interfaces |
| GET | `/inspect/api/object?classname=App\Service\UserService` | Instantiate and dump a container object |

## Adapter Support

Each adapter maps its framework's DI container to the inspector interface:

* **Symfony**: Introspects `service_container` and compiler pass data
* **Laravel**: Maps service bindings and resolved instances
* **Yii 3**: Maps container definitions
* **Yii 2**: Maps component and service locator config

---

---
url: >-
  https://app-dev-panel.github.io/app-dev-panel/guide/collectors/console-app-info.md
---

# ConsoleAppInfo Collector

Collects console application performance metrics — processing time, memory usage, and adapter name. The console equivalent of [WebAppInfo Collector](/guide/collectors/web-app-info).

## What It Captures

| Field | Description |
|-------|-------------|
| `applicationProcessingTime` | Total application processing time |
| `requestProcessingTime` | Command execution time |
| `applicationEmit` | Output emit time |
| `preloadTime` | Bootstrap/preload time |
| `memoryPeakUsage` | Peak memory usage in bytes |
| `memoryUsage` | Current memory usage in bytes |
| `adapter` | Framework adapter name |

## Data Schema

```json
{
    "applicationProcessingTime": 1.250,
    "requestProcessingTime": 1.200,
    "applicationEmit": 0.001,
    "preloadTime": 0.049,
    "memoryPeakUsage": 16777216,
    "memoryUsage": 12582912,
    "adapter": "symfony"
}
```

**Summary** (shown in debug entry list):

```json
{
    "console": {
        "adapter": "symfony",
        "request": {
            "startTime": 1711878000.100,
            "processingTime": 1.200
        },
        "memory": {
            "peakUsage": 16777216
        }
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\Console\ConsoleAppInfoCollector;

$collector->markApplicationStarted();
// ... command execution ...
$collector->markApplicationFinished();
```

::: info
\AppDevPanel\Kernel\Collector\Console\ConsoleAppInfoCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface and depends on \AppDevPanel\Kernel\Collector\TimelineCollector. Located in the `Console` sub-namespace.
:::

## How It Works

Framework adapters call the `mark*()` methods at key points in the console command lifecycle. Memory metrics are captured via `memory_get_peak_usage()` and `memory_get_usage()`.

## Debug Panel

Console entry metadata (processing time, memory) is displayed in the debug entry header, similar to web entries.

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/contributing.md'
---

# Contributing

ADP is a monorepo containing PHP backend libraries and a React/TypeScript frontend. This guide covers setting up your development environment, code conventions, and how to add new components.

## Prerequisites

* PHP 8.4+
* Node.js 18+ and npm
* Composer

## Installation

```bash
make install              # Install ALL dependencies (PHP + frontend + playgrounds)
```

Or install selectively:

```bash
make install-php          # Composer install (root)
make install-frontend     # npm install (libs/frontend)
make install-playgrounds  # Composer install for each playground app
```

## Running Tests

```bash
make test                 # Run ALL tests in parallel (PHP + frontend)
make test-php             # PHP unit tests (PHPUnit)
make test-frontend        # Frontend unit tests (Vitest)
make test-frontend-e2e    # Frontend browser tests (requires Chrome)
```

For PHP coverage reports, install the PCOV extension:

```bash
pecl install pcov
php vendor/bin/phpunit --coverage-text
```

## Code Quality

ADP uses [Mago](https://mago.carthage.software/) for PHP (formatting, linting, static analysis) and Prettier + ESLint for TypeScript.

```bash
make check                # Run ALL code quality checks
make fix                  # Fix all auto-fixable issues

# PHP only
make mago                 # Check formatting + lint + analyze
make mago-fix             # Fix formatting, then lint + analyze

# Frontend only
make frontend-check       # Prettier + ESLint
make frontend-fix         # Fix frontend issues
```

### Mago Baselines

Existing lint issues in legacy code are suppressed via a baseline file. The analyzer has no baseline — rules that produce false positives are suppressed via `ignore` in `mago.toml`. New code must not introduce new issues.

```bash
composer lint:baseline    # Regenerate lint baseline after fixing existing issues
```

## Code Style

### PHP

* **PER-CS (PER-2)** via [Mago](https://mago.carthage.software/)
* `declare(strict_types=1)` in every file
* `final class` by default
* PSR interfaces for all abstractions

### TypeScript

* **Prettier 3.8+**: single quotes, trailing commas, 120 char width, 4-space indent, `objectWrap: "collapse"`
* **ESLint 9** with `@typescript-eslint`
* `type` over `interface` (`consistent-type-definitions: "type"`)
* Functional React components, Redux Toolkit patterns

## Module Dependencies

Strict dependency rules ensure framework-agnosticism:

```
Adapter → API → Kernel
  │               ↑
  └───────────────┘
Cli → Kernel
Frontend → API (HTTP only)
```

| Module | Can depend on | Cannot depend on |
|--------|--------------|-----------------|
| Kernel | PSR interfaces, generic PHP libs | API, Cli, Adapter |
| API | Kernel, PSR interfaces | Adapter, Cli |
| Cli | Kernel, Symfony Console | API, Adapter |
| Adapter | Kernel, API, framework packages | Other adapters |

## Testing Conventions

* One test class per source class: `src/Foo/Bar.php` → `tests/Unit/Foo/BarTest.php`
* Inline mocks only (`$this->createMock()`, anonymous classes)
* No shared test utilities, no test environment classes
* `assertSame()` over `assertEquals()`
* Data providers via `#[DataProvider('name')]` attribute
* Collectors extend `AbstractCollectorTestCase`

## Development Workflow

1. Create a feature branch
2. Write code and tests for your changes
3. Run checks: `make fix && make test`
4. Verify everything: `make all` (checks + tests combined)
5. Submit a pull request

All checks must pass before merging.

## Adding a Collector

1. Create a class implementing AppDevPanel\Kernel\Collector\CollectorInterface in `libs/Kernel/src/Collector/`
2. Implement `startup()`, `shutdown()`, `getCollected()`
3. Optionally implement AppDevPanel\Kernel\Collector\SummaryCollectorInterface for entry list metadata
4. Write a test extending `AbstractCollectorTestCase`
5. Register in adapter configs (e.g., `libs/Adapter/Yii3/config/params.php`)

See [Collectors](/guide/collectors) for the interface contract.

## Adding an Inspector Page

### Backend

1. Create a controller in `libs/API/src/Inspector/Controller/`
2. Add a route in `libs/API/config/routes.php`
3. Write a controller test extending `ControllerTestCase`

### Frontend

1. Create a page component in `packages/panel/src/Module/Inspector/Pages/`
2. Add an RTK Query endpoint in `packages/panel/src/Module/Inspector/API/`
3. Add a route to the inspector module's route config

## Project Structure

| Directory | Contents |
|-----------|----------|
| `libs/Kernel/` | Core engine: debugger, collectors, storage, proxies |
| `libs/API/` | HTTP API: REST endpoints, SSE, middleware |
| `libs/McpServer/` | MCP server for AI assistant integration |
| `libs/Cli/` | CLI commands |
| `libs/Adapter/` | Framework adapters (Yii 3, Symfony, Laravel, Yii 2, Cycle) |
| `libs/frontend/` | React frontend (panel, toolbar, SDK packages) |
| `playground/` | Demo applications per framework |

## CI Pipeline

GitHub Actions runs on every push and PR:

* PHP tests on PHP 8.4 and 8.5 (Linux + Windows)
* Mago format, lint, and static analysis
* Frontend checks and tests
* Coverage reports posted as PR comments

Run the full CI pipeline locally:

```bash
make ci
```

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/adapters/cycle.md'
---
# Cycle ORM Adapter

The Cycle ORM adapter is a lightweight adapter that provides database schema inspection only. Unlike full adapters, it has no collectors, event listeners, or lifecycle wiring.

## Installation

```bash
composer require app-dev-panel/adapter-cycle
```

## Usage

Register AppDevPanel\Adapter\Cycle\Inspector\CycleSchemaProvider as AppDevPanel\Api\Inspector\Database\SchemaProviderInterface in your framework's DI container:

```php
use AppDevPanel\Adapter\Cycle\Inspector\CycleSchemaProvider;
use AppDevPanel\Api\Inspector\Database\SchemaProviderInterface;
use Cycle\Database\DatabaseProviderInterface;

SchemaProviderInterface::class => static fn (DatabaseProviderInterface $db) => new CycleSchemaProvider($db),
```

## Capabilities

| Method | Status | Description |
|--------|--------|-------------|
| `getTables()` | Implemented | Lists all tables with columns, primary keys, row counts |
| `getTable()` | Implemented | Single table schema with paginated records |
| `explainQuery()` | Stub | Returns empty array |
| `executeQuery()` | Stub | Returns empty array |

## When to Use

Use the Cycle adapter when your application uses Cycle ORM and you want database schema inspection in the ADP panel. Combine it with a full framework adapter (Yii 3, Symfony, Laravel) that handles lifecycle, collectors, and API wiring.

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/data-flow.md'
---

# Data Flow

This page describes how debug data flows from your application to the ADP panel.

## Overview

```
Target App → Adapter → Proxies → Collectors → Debugger → Storage → API → Frontend
```

## Request Lifecycle

### Phase 1: Startup

When your application receives an HTTP request (or CLI command):

1. The adapter's event listener catches the framework's startup event
2. AppDevPanel\Kernel\Debugger`::startup()` is called, which:
   * Registers a shutdown function
   * Checks if the request/command should be ignored (via `$ignoredRequests` / `$ignoredCommands` patterns, `X-Debug-Ignore` header)
   * If not ignored: calls `startup()` on all registered collectors

### Phase 2: Data Collection

During request processing, proxies intercept calls and feed data to collectors:

```
Application Code
      │
      ├──▶  Logger::log()              ──▶  LoggerInterfaceProxy          ──▶  LogCollector
      ├──▶  EventDispatcher::dispatch() ──▶  EventDispatcherInterfaceProxy ──▶  EventCollector
      ├──▶  HttpClient::sendRequest()   ──▶  HttpClientInterfaceProxy      ──▶  HttpClientCollector
      ├──▶  Container::get()            ──▶  ContainerInterfaceProxy       ──▶  ServiceCollector
      ├──▶  VarDumper::dump()           ──▶  VarDumperHandlerInterfaceProxy──▶  VarDumperCollector
      └──▶  throw Exception             ──▶  ExceptionHandler              ──▶  ExceptionCollector
```

Each collector accumulates data in memory for the duration of the request. Proxies record metadata like timestamps, file:line info (via `debug_backtrace()`), and unique IDs for correlation.

### Phase 3: Shutdown and Flush

When the request completes (or a console command finishes), the AppDevPanel\Kernel\Debugger triggers shutdown:

1. Calls `shutdown()` on all collectors (resets internal state)
2. Calls `getCollected()` to retrieve accumulated data
3. Serializes objects using AppDevPanel\Kernel\Dumper (depth-limited to 30 levels, with circular reference detection)
4. Calls `flush()` on storage

AppDevPanel\Kernel\Storage\FileStorage writes three JSON files per debug entry:

| File | Contents |
|------|----------|
| `{id}/summary.json` | Entry metadata (timestamp, URL, status, collector summaries) |
| `{id}/data.json` | Full collector payloads |
| `{id}/objects.json` | Extracted unique PHP objects for deep inspection |

All writes use `file_put_contents()` with `LOCK_EX` for atomicity.

### Phase 4: Garbage Collection

After each flush, storage runs garbage collection:

* Acquires a non-blocking lock on `.gc.lock` (skips if another process holds it)
* Deletes entries beyond `historySize` (default 50), sorted by modification time

## Storage Format

```
runtime/debug/
├── YYYY-MM-DD/
│   ├── {entryId}/
│   │   ├── summary.json
│   │   ├── data.json
│   │   └── objects.json
│   ├── {entryId}/
│   │   └── ...
│   └── .gc.lock
└── .services.json
```

### Summary Format

```json
{
  "id": "1710520800123456",
  "collectors": ["LogCollector", "EventCollector", "RequestCollector"],
  "logger": {"total": 5},
  "event": {"total": 12},
  "http": {"count": 2, "totalTime": 0.45},
  "request": {"url": "/api/users", "method": "GET", "status": 200},
  "exception": null
}
```

Collectors that implement AppDevPanel\Kernel\Collector\SummaryCollectorInterface contribute their summary keys (e.g., `logger`, `event`, `http`) for display in the entry list without loading full data.

## API Serving

The API serves stored data through a middleware chain:

```
Frontend Request
      │
      ▼
  API Middleware Chain
  ┌────────────────────────────┐
  │ 1. CorsAllowAll            │
  │ 2. IpFilter                │
  │ 3. TokenAuthMiddleware     │
  │ 4. FormatDataResponseAsJson│
  │ 5. ResponseDataWrapper     │
  └────────────┬───────────────┘
               │
               ▼
  CollectorRepository
  ├── .getSummary()    → summary.json
  ├── .getDetail(id)   → data.json
  └── .getObject(id)   → objects.json
               │
               ▼
  JSON Response: {id, data, error, success, status}
```

## Real-Time Updates (SSE)

The frontend uses **SSE** (Server-Sent Events) to detect new entries in real-time:

1. Frontend subscribes to `GET /debug/api/event-stream`
2. API polls storage every second, computing an MD5 hash of current summaries
3. When a new entry appears, the hash changes and an event is emitted: `{"type": "debug-updated"}`
4. Frontend fetches the updated entry list

The frontend `ServerSentEventsObserver` uses exponential backoff on connection failures: 1s base delay, doubles per attempt, 30s max, resets on successful connection.

## Ingestion API (External Applications)

Non-PHP applications can send debug data via the **Ingestion API**, bypassing the proxy/collector pipeline entirely. Data is written directly to storage and appears in the panel alongside PHP debug entries.

| Endpoint | Description |
|----------|-------------|
| `POST /debug/api/ingest` | Single debug entry with collectors + optional context/summary |
| `POST /debug/api/ingest/batch` | Multiple entries (max 100). Returns `{ids: [...], count}` |
| `POST /debug/api/ingest/log` | Shorthand for single log entry: `{level, message, context?}` |
| `GET /debug/api/openapi.json` | OpenAPI specification for the Ingestion API |

Request body format for single entry:

```json
{
  "collectors": {
    "LogCollector": [{"level": "info", "message": "Hello"}]
  },
  "summary": {},
  "context": {}
}
```

## Inspector Proxy (Multi-App)

The Inspector proxy enables the frontend to inspect external applications (Python, Node.js, Go, etc.) through a unified API.

```
Frontend: /inspect/api/routes?service=python-app
      │
      ▼
InspectorProxyMiddleware
      ├── Extract service name from ?service= param
      ├── Resolve via ServiceRegistry → ServiceDescriptor
      ├── Check online status (lastSeenAt within 60s)
      ├── Map path to capability (e.g., /routes → "routes")
      ├── Verify service supports the capability
      │
      ▼ (all checks pass)
Proxy request to: {inspectorUrl}/inspect/api/routes
```

### Capability Map

| Path Prefix | Capability |
|-------------|-----------|
| `/config`, `/params` | `config` |
| `/routes`, `/route/check` | `routes` |
| `/files` | `files` |
| `/cache` | `cache` |
| `/table` | `database` |
| `/translations` | `translations` |
| `/events` | `events` |
| `/command` | `commands` |
| `/git` | `git` |
| `/composer` | `composer` |
| `/phpinfo` | `phpinfo` |
| `/opcache` | `opcache` |

### Error Responses

| Condition | Status |
|-----------|--------|
| Service not found | 404 |
| Service offline (heartbeat timeout) | 503 |
| Capability not supported | 501 |
| No inspector URL configured | 502 |
| Connection refused / host unresolved | 502 |
| Request timeout | 504 |

## Service Registry

External applications register with ADP and send periodic heartbeats to appear as online:

```
External App                              ADP
     │                                     │
     │  POST /debug/api/services/register  │
     │  {service, language, inspectorUrl,  │
     │   capabilities}                     │
     │ ──────────────────────────────────▶ │
     │                                     │
     │  POST /debug/api/services/heartbeat │
     │  {service}  (every <60s)            │
     │ ──────────────────────────────────▶ │
     │                                     │
     │  GET /debug/api/services/           │
     │ ◀────────────────────────────────── │ (lists all with online/offline)
```

AppDevPanel\Kernel\Service\ServiceDescriptor contains: `service`, `language`, `inspectorUrl`, `capabilities[]`, `registeredAt`, `lastSeenAt`. A service is considered online if `now() - lastSeenAt < 60s`.

## Console Command Flow

Console commands follow the same lifecycle as web requests, with these differences:

* AppDevPanel\Kernel\Collector\Console\ConsoleAppInfoCollector replaces AppDevPanel\Kernel\Collector\Web\WebAppInfoCollector
* AppDevPanel\Kernel\Collector\Console\CommandCollector replaces AppDevPanel\Kernel\Collector\Web\RequestCollector (both render under the unified "Request" panel in the UI)
* No middleware, router, or asset collectors
* Events: `ConsoleCommandEvent` triggers startup, `ConsoleTerminateEvent` triggers shutdown

## Debug Server (UDP Socket)

The `dev` CLI command starts a UDP socket server for real-time log/dump output in the terminal:

```bash
php yii dev -a 0.0.0.0 -p 8890
```

When your application calls `dump()` or logs a message, the broadcaster:

1. Discovers running server sockets via glob (`/tmp/yii-dev-server-*.sock`)
2. Sends the data as base64-encoded JSON with an 8-byte length header
3. The server displays the message as a formatted block in the terminal

Message types: `VarDumper`, `Logger`, and plain text.

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/database.md'
---

# Database Collector

Captures SQL queries, parameters, execution time, transactions, and duplicate query detection.

![Database Collector panel](/images/collectors/database.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `sql` | SQL query with parameter placeholders |
| `rawSql` | SQL query with parameters inlined |
| `params` | Bound parameters array |
| `line` | Source file and line of the query call |
| `status` | Query status (`success` or `error`) |
| `rowsNumber` | Number of affected/returned rows |
| `exception` | Exception if query failed |
| `transactionId` | Associated transaction ID |

## Data Schema

```json
{
    "queries": [
        {
            "position": 0,
            "transactionId": null,
            "sql": "SELECT * FROM users WHERE id = :id",
            "rawSql": "SELECT * FROM users WHERE id = 42",
            "params": {":id": 42},
            "line": "/app/src/UserRepository.php:35",
            "status": "success",
            "rowsNumber": 1,
            "exception": null,
            "actions": []
        }
    ],
    "transactions": {},
    "duplicates": {
        "groups": [],
        "totalDuplicatedCount": 0
    }
}
```

**Summary** (shown in debug entry list):

```json
{
    "db": {
        "queries": {"error": 0, "total": 3},
        "transactions": {"error": 0, "total": 1},
        "duplicateGroups": 0,
        "totalDuplicatedCount": 0
    }
}
```

## Contract

### Query lifecycle

```php
use AppDevPanel\Kernel\Collector\DatabaseCollector;

// Option A: start/end pattern
$collector->collectQueryStart(
    id: 'query-1',
    sql: 'SELECT * FROM users WHERE id = :id',
    rawSql: 'SELECT * FROM users WHERE id = 42',
    params: [':id' => 42],
    line: '/app/src/UserRepository.php:35',
);
$collector->collectQueryEnd(id: 'query-1', rowsNumber: 1);

// Option B: single record
use AppDevPanel\Kernel\Collector\QueryRecord;

$collector->logQuery(new QueryRecord(
    sql: 'SELECT * FROM users WHERE id = :id',
    rawSql: 'SELECT * FROM users WHERE id = 42',
    params: [':id' => 42],
    duration: 0.0023,
    line: '/app/src/UserRepository.php:35',
));
```

### Transactions

```php
$collector->collectTransactionStart(isolationLevel: 'READ COMMITTED', line: '...');
$collector->collectTransactionEnd(status: 'commit', line: '...');
```

::: info
\AppDevPanel\Kernel\Collector\DatabaseCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface, depends on \AppDevPanel\Kernel\Collector\TimelineCollector, and uses \AppDevPanel\Kernel\Collector\DuplicateDetectionTrait for detecting repeated queries.
:::

## How It Works

Framework adapters intercept database operations through framework-specific hooks:

* **Symfony**: Doctrine DBAL middleware
* **Laravel**: DB query listener
* **Yii 2**: Log target for DB profiling messages
* **Yii 3**: Query event listeners

## Debug Panel

* **Query count and total time** — summary header with aggregate stats
* **SQL syntax highlighting** — queries displayed with keyword coloring
* **Query type badges** — SELECT, INSERT, UPDATE, DELETE color-coded
* **Row count and timing** — per-query execution metrics
* **Explain plan** — visual EXPLAIN plan tree for SELECT queries
* **Duplicate detection** — highlights repeated identical queries
* **Transaction grouping** — queries grouped by transaction boundaries

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/inspector/database.md'
---

# Database Inspector

Browse database tables, view schema and records, execute SQL queries, and analyze query plans.

![Database Inspector — Tables list](/images/inspector/database.png)

## Table Browser

Lists all database tables with column count and record count. Click **View** to see the table's schema and records.

![Database Inspector — Table records](/images/inspector/database-table.png)

## What It Shows

| Feature | Description |
|---------|-------------|
| Tables list | All tables with column/record counts |
| Table schema | Column names, types, defaults, nullability |
| Records | Paginated data rows (default 50, max 1000) |
| SQL Query | Execute raw SQL against the database |
| EXPLAIN | Analyze query execution plans (with optional `ANALYZE`) |

## SQL Query Executor

Execute any SQL query directly from the panel. Supports parameterized queries for safety.

## EXPLAIN Plans

Run `EXPLAIN` or `EXPLAIN ANALYZE` on queries to see execution plans, useful for debugging slow queries.

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/inspect/api/table` | List all tables |
| GET | `/inspect/api/table/{name}?limit=50&offset=0` | Table schema + paginated records |
| POST | `/inspect/api/table/explain` | EXPLAIN a SQL query |
| POST | `/inspect/api/table/query` | Execute a raw SQL query |

**EXPLAIN request body:**

```json
{
    "sql": "SELECT * FROM users WHERE id = ?",
    "params": [1],
    "analyze": true
}
```

## Adapter Support

| Adapter | Provider |
|---------|----------|
| Symfony | AppDevPanel\Adapter\Symfony\Inspector\DoctrineSchemaProvider (Doctrine DBAL) |
| Laravel | AppDevPanel\Adapter\Laravel\Inspector\LaravelSchemaProvider (Eloquent) |
| Yii 2 | `Yii2DbSchemaProvider` |
| Cycle ORM | AppDevPanel\Adapter\Cycle\Inspector\CycleSchemaProvider |

::: warning
SQL queries execute against the live database. Use with care in production environments.
:::

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/debug-panel.md'
---

# Debug Panel

The ADP debug panel is a React SPA that provides a web UI for inspecting debug data collected from your application. When you install an adapter, the panel is automatically available at `/debug` on your application.

::: tip Live Demo
Try the panel without installing anything: [Live Demo](https://app-dev-panel.github.io/app-dev-panel/demo/). Enter your application's URL in the backend field to connect.
:::

## How It Works

Each adapter registers a `/debug` route that serves a minimal HTML page. This page:

1. Loads `bundle.js` and `bundle.css` from a static assets source (GitHub Pages by default)
2. Injects runtime configuration — backend URL (auto-detected from the current request), router basename, etc.
3. Mounts the React SPA which communicates with the `/debug/api/*` and `/inspect/api/*` endpoints

```
Browser → GET /debug → Adapter serves HTML → Loads bundle.js from CDN
                                            → React SPA mounts
                                            → Fetches data from /debug/api/*
```

No separate frontend server is needed. The panel works out of the box after installing an adapter.

## Accessing the Panel

After installing an adapter, open your application in the browser and navigate to:

```
http://your-app/debug
```

The panel supports client-side routing, so all sub-paths (e.g., `/debug/logs`, `/debug/inspector/routes`) are handled by the SPA.

::: tip PHP Built-in Server
When using PHP's built-in server, set `PHP_CLI_SERVER_WORKERS=3` or higher. ADP makes concurrent requests (SSE + data fetching); single-worker mode causes timeouts.

```bash
PHP_CLI_SERVER_WORKERS=3 php -S 127.0.0.1:8080 -t public
```

:::

## Static Assets Source

By default, the panel loads assets from GitHub Pages:

```
https://app-dev-panel.github.io/app-dev-panel/bundle.js
https://app-dev-panel.github.io/app-dev-panel/bundle.css
```

You can change the static URL to load assets from a different source:

### Option 1: GitHub Pages (Default)

No configuration needed. Assets are automatically served from the latest release on GitHub Pages.

### Option 2: Local Assets from Release

Download `panel-dist.tar.gz` from a [GitHub Release](https://github.com/app-dev-panel/app-dev-panel/releases), extract it to a public directory, and configure the static URL:

```bash
# Download and extract
curl -L https://github.com/app-dev-panel/app-dev-panel/releases/latest/download/panel-dist.tar.gz | tar xz -C public/adp-panel
```

Then configure the adapter to use the local path:

:::tabs key:framework
\== Symfony

```yaml
# config/packages/app_dev_panel.yaml
app_dev_panel:
    panel:
        static_url: '/adp-panel'
```

\== Laravel

```php
// config/app-dev-panel.php
'panel' => [
    'static_url' => '/adp-panel',
],
```

\== Yii 3

```php
// config/params.php
'app-dev-panel/yii3' => [
    'panel' => [
        'staticUrl' => '/adp-panel',
    ],
],
```

\== Yii 2

```php
// config/web.php
'modules' => [
    'debug-panel' => [
        'class' => \AppDevPanel\Adapter\Yii2\Module::class,
        'panelStaticUrl' => '/adp-panel',
    ],
],
```

:::

### Option 3: Vite Dev Server

During frontend development, you can point the panel to the local Vite dev server:

```bash
cd libs/frontend
npm start    # Starts Vite on http://localhost:3000
```

Then configure:

:::tabs key:framework
\== Symfony

```yaml
app_dev_panel:
    panel:
        static_url: 'http://localhost:3000'
```

\== Laravel

```php
'panel' => [
    'static_url' => 'http://localhost:3000',
],
```

\== Yii 3

```php
'app-dev-panel/yii3' => [
    'panel' => [
        'staticUrl' => 'http://localhost:3000',
    ],
],
```

\== Yii 2

```php
'modules' => [
    'debug-panel' => [
        'class' => \AppDevPanel\Adapter\Yii2\Module::class,
        'panelStaticUrl' => 'http://localhost:3000',
    ],
],
```

:::

## Panel Modules

The panel SPA includes the following modules:

| Module | Path | Description |
|--------|------|-------------|
| Debug | `/debug` | View collected debug entries — logs, database queries, events, exceptions, timeline, HTTP requests, cache, mail, etc. |
| Inspector | `/debug/inspector/*` | Live application state — routes, config, database schema, git, cache, files, translations, Composer packages |
| LLM | `/debug/llm` | AI-powered chat and analysis of debug data |
| MCP | `/debug/mcp` | MCP (Model Context Protocol) server configuration |
| OpenAPI | `/debug/openapi` | Swagger UI for the ADP REST API |

## Configuration Reference

| Parameter | Default | Description |
|-----------|---------|-------------|
| `static_url` | `https://app-dev-panel.github.io/app-dev-panel` | Base URL for panel static assets (bundle.js, bundle.css) |
| `viewer_base_path` | `/debug` | Route prefix where the panel is mounted |

## Architecture

The panel rendering is handled at the API layer (AppDevPanel\Api\Panel\PanelController), which is framework-agnostic. Each adapter simply routes `/debug` and `/debug/*` to the same AppDevPanel\Api\ApiApplication that handles API requests.

```
GET /debug/logs/detail
    → Adapter catches /debug/* (not /debug/api/*)
    → ApiApplication routes to PanelController
    → PanelController renders HTML with:
        - <link> to bundle.css
        - <script> injecting window['AppDevPanelWidget'] config
        - <script> loading bundle.js
    → Browser loads React SPA
    → SPA uses client-side routing for /debug/logs/detail
```

Panel routes skip the JSON response wrapper and token auth middleware — they only pass through CORS and IP filter.

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/deprecation.md'
---

# Deprecation Collector

Captures PHP deprecation notices with message, source location, category, and stack trace.

![Deprecation Collector panel](/images/collectors/deprecation.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `time` | Timestamp of the deprecation |
| `message` | Deprecation message |
| `file` | File where the deprecation was triggered |
| `line` | Line number |
| `category` | Deprecation category |
| `trace` | Stack trace |

## Data Schema

```json
[
    {
        "time": 1711878000.123,
        "message": "Method getData() is deprecated, use getResult() instead",
        "file": "/app/src/Legacy/Service.php",
        "line": 55,
        "category": "user",
        "trace": [...]
    }
]
```

**Summary** (shown in debug entry list):

```json
{
    "deprecation": {
        "total": 2
    }
}
```

## Contract

The collector registers a custom PHP error handler that intercepts `E_DEPRECATED` and `E_USER_DEPRECATED` notices. No explicit `collect()` method is needed — deprecations are captured automatically.

::: info
\AppDevPanel\Kernel\Collector\DeprecationCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface and depends on \AppDevPanel\Kernel\Collector\TimelineCollector.
:::

## How It Works

On `startup()`, the collector registers a PHP error handler via `set_error_handler()`. All deprecation warnings (`E_DEPRECATED`, `E_USER_DEPRECATED`) are captured with full stack traces. The original error handler is restored on `shutdown()`.

## Debug Panel

* **Deprecation list** — all deprecation notices with message and source location
* **Stack traces** — expandable trace for each deprecation
* **File links** — clickable source paths for IDE integration

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/editor-integration.md'
---

# Editor Integration

::: warning PLANNED FEATURE
Editor integration is planned but not yet implemented. This page describes the design and what to expect. Contributions are welcome — see [Contributing](/guide/contributing).
:::

ADP plans to support "Open in Editor" functionality, allowing you to click file references in the debug panel and jump directly to the source code in your IDE.

## Supported Editors

The following editors support custom URL protocols:

| Editor | Protocol | URL Format |
|--------|----------|-----------|
| PhpStorm | `phpstorm://` | `phpstorm://open?file={file}&line={line}` |
| VS Code | `vscode://` | `vscode://file/{file}:{line}` |
| VS Code Insiders | `vscode-insiders://` | `vscode-insiders://file/{file}:{line}` |
| Cursor | `cursor://` | `cursor://file/{file}:{line}` |
| Sublime Text | `subl://` | `subl://open?url=file://{file}&line={line}` |
| Zed | `zed://` | `zed://file/{file}:{line}` |
| Nova | `nova://` | `nova://open?path={file}&line={line}` |
| Netbeans | `netbeans://` | `netbeans://open?file={file}&line={line}` |

## Planned Features

### 1. Open in Editor (URL Protocol)

An "Open in Editor" button next to every file reference across all panels — exceptions, logs, events, HTTP client calls, var dumps, stack traces, routes, and more.

Settings will include editor preset selection and a custom URL template option.

### 2. Clickable Code Line Numbers

In the code viewer (`CodeHighlight` component), line numbers will become clickable to open that specific line in your editor.

### 3. Stack Trace Linking

Exception stack traces (currently plain text) will be parsed so each frame links to the file and line in both the ADP File Explorer and your editor.

### 4. Copy Path / Copy Editor URL

Context actions to copy:

* Absolute file path
* Editor protocol URL
* `file:line` reference

### 5. HTTP Callback (Remote/Docker)

For environments where URL protocols don't work (Docker, WSL, remote servers), an HTTP callback approach. The panel sends a POST request to a local editor plugin or the PhpStorm REST API (`http://localhost:63342/api/file/{file}:{line}`).

### 6. Path Mapping

For Docker/Vagrant/remote setups where server paths differ from local paths:

```typescript
type EditorConfig = {
    editor: 'phpstorm' | 'vscode' | 'cursor' | 'custom' | ...;
    customUrlTemplate: string;
    pathMapping: Record<string, string>;
    // e.g. {"/app": "/Users/me/project"}
};
```

## Priority

| Feature | Effort | Impact |
|---------|--------|--------|
| URL Protocol (Open in Editor) | Medium | High |
| Code line click | Low | Medium |
| Stack Trace linking | Medium | High |
| Copy path / Copy URL | Low | Medium |
| HTTP Callback (remote) | Medium | Medium |

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/elasticsearch.md'
---

# Elasticsearch

ADP provides an AppDevPanel\Kernel\Collector\ElasticsearchCollector for capturing Elasticsearch requests during application lifecycle and an inspector for live cluster inspection.

## Collector

AppDevPanel\Kernel\Collector\ElasticsearchCollector implements AppDevPanel\Kernel\Collector\SummaryCollectorInterface and captures all Elasticsearch requests — searches, indexing, deletions, bulk operations.

### Collection Patterns

Two patterns are supported:

**Paired pattern** — for proxy-based adapters that intercept the ES client:

```php
$collector->collectRequestStart($id, 'GET', '/users/_search', $body, $line);
// ... request executes ...
$collector->collectRequestEnd($id, 200, $responseBody, $responseSize);
// or on failure:
$collector->collectRequestError($id, $exception);
```

**Simple pattern** — for event-based adapters that measure timing externally:

```php
$collector->logRequest(new ElasticsearchRequestRecord(
    method: 'GET',
    endpoint: '/users/_search',
    body: '{"query":{"match_all":{}}}',
    line: __FILE__ . ':' . __LINE__,
    startTime: $start,
    endTime: $end,
    statusCode: 200,
    responseBody: '{"hits":{"total":{"value":42}}}',
    responseSize: 256,
));
```

### Collected Data

```php
[
    'requests' => [
        [
            'method' => 'GET',
            'endpoint' => '/users/_search',
            'index' => 'users',           // auto-extracted from endpoint
            'body' => '{"query":{...}}',
            'line' => '/src/Repo.php:42',
            'status' => 'success',         // success | error | initialized
            'startTime' => 1711900000.123,
            'endTime' => 1711900000.135,
            'duration' => 0.012,
            'statusCode' => 200,
            'responseBody' => '...',
            'responseSize' => 256,
            'hitsCount' => 42,             // extracted from response (null for non-search)
            'exception' => null,
        ],
    ],
    'duplicates' => [
        'groups' => [...],                 // repeated method+endpoint combinations
        'totalDuplicatedCount' => 0,
    ],
]
```

### Summary

```php
[
    'elasticsearch' => [
        'total' => 3,
        'errors' => 0,
        'totalTime' => 0.045,
        'duplicateGroups' => 0,
        'totalDuplicatedCount' => 0,
    ],
]
```

### Features

* **Index extraction** — parses the index name from the endpoint path (e.g., `/users/_search` → `users`)
* **Hits count** — extracts `hits.total.value` from search responses
* **Duplicate detection** — identifies repeated `method + endpoint` combinations (N+1 pattern detection)
* **Timeline integration** — reports to AppDevPanel\Kernel\Collector\TimelineCollector for unified performance timeline

## Inspector

The Elasticsearch inspector provides live cluster inspection via AppDevPanel\Api\Inspector\Elasticsearch\ElasticsearchProviderInterface.

### API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/inspect/api/elasticsearch` | Cluster health + indices list |
| GET | `/inspect/api/elasticsearch/{name}` | Index detail (mappings, settings, stats) |
| POST | `/inspect/api/elasticsearch/search` | Execute search query |
| POST | `/inspect/api/elasticsearch/query` | Execute raw query |

### Provider Interface

```php
interface ElasticsearchProviderInterface
{
    public function getHealth(): array;
    public function getIndices(): array;
    public function getIndex(string $name): array;
    public function search(string $index, array $query, int $limit, int $offset): array;
    public function executeQuery(string $method, string $endpoint, array $body): array;
}
```

Default: AppDevPanel\Api\Inspector\Elasticsearch\NullElasticsearchProvider returns empty data. Adapters provide concrete implementations backed by an actual ES client.

## Frontend

### Debug Panel

The `ElasticsearchPanel` displays captured requests with:

* Method and status code badges (color-coded)
* Endpoint with extracted index name
* Duration and hits count per request
* Expandable request/response body (JSON-rendered)
* Filter by endpoint, index, method, or body content
* Duplicate detection warnings

### Inspector Page

The `ElasticsearchPage` shows live cluster state:

* Cluster health banner (green/yellow/red status chips)
* Node and shard counts
* Indices table with docs count, store size, health, shards

## Framework Integration

Register AppDevPanel\Kernel\Collector\ElasticsearchCollector in your adapter's DI with AppDevPanel\Kernel\Collector\TimelineCollector as constructor dependency. Enable via config flag `'elasticsearch' => true`.

See [Adapters](/guide/adapters/symfony) for framework-specific registration patterns.

---

---
url: >-
  https://app-dev-panel.github.io/app-dev-panel/guide/collectors/elasticsearch.md
---

# Elasticsearch Collector

Captures Elasticsearch requests — method, endpoint, index, request/response body, timing, hits count, and duplicate detection.

![Elasticsearch Collector panel](/images/collectors/elasticsearch.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `method` | HTTP method (GET, POST, PUT, DELETE) |
| `endpoint` | Elasticsearch endpoint path |
| `index` | Target index name |
| `body` | Request body (JSON) |
| `status` | Request status (`success` or `error`) |
| `statusCode` | HTTP response status code |
| `responseBody` | Response body |
| `responseSize` | Response size in bytes |
| `hitsCount` | Number of search hits (for search queries) |
| `duration` | Request duration in seconds |

## Data Schema

```json
{
    "requests": [
        {
            "method": "GET",
            "endpoint": "/users/_search",
            "index": "users",
            "body": "{\"query\": {\"match\": {\"name\": \"John\"}}}",
            "line": "/app/src/SearchService.php:42",
            "status": "success",
            "startTime": 1711878000.100,
            "endTime": 1711878000.150,
            "duration": 0.05,
            "statusCode": 200,
            "responseBody": "{\"hits\": {\"total\": 5, ...}}",
            "responseSize": 1024,
            "hitsCount": 5,
            "exception": null
        }
    ],
    "duplicates": {
        "groups": [],
        "totalDuplicatedCount": 0
    }
}
```

**Summary** (shown in debug entry list):

```json
{
    "elasticsearch": {
        "total": 3,
        "errors": 0,
        "totalTime": 0.15,
        "duplicateGroups": 0,
        "totalDuplicatedCount": 0
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\ElasticsearchCollector;
use AppDevPanel\Kernel\Collector\ElasticsearchRequestRecord;

// Option A: start/end pattern
$collector->collectRequestStart(
    id: 'es-1',
    method: 'GET',
    endpoint: '/users/_search',
    body: '{"query": {"match": {"name": "John"}}}',
    line: '/app/src/SearchService.php:42',
);
$collector->collectRequestEnd(
    id: 'es-1',
    statusCode: 200,
    responseBody: '{"hits": {"total": 5}}',
    responseSize: 1024,
);

// Option B: single record
$collector->logRequest(new ElasticsearchRequestRecord(
    method: 'GET',
    endpoint: '/users/_search',
    index: 'users',
    body: '{"query": {"match": {"name": "John"}}}',
    duration: 0.05,
    statusCode: 200,
    hitsCount: 5,
    line: '/app/src/SearchService.php:42',
));
```

::: info
\AppDevPanel\Kernel\Collector\ElasticsearchCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface, depends on \AppDevPanel\Kernel\Collector\TimelineCollector, and uses \AppDevPanel\Kernel\Collector\DuplicateDetectionTrait.
:::

See the dedicated [Elasticsearch](/guide/elasticsearch) page for configuration and integration details.

## Debug Panel

* **Request list** — all ES requests with method, endpoint, status, and timing
* **Hits count** — number of search results for search queries
* **Duplicate detection** — highlights repeated identical requests
* **Error tracking** — failed requests highlighted with error details

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/inspector/elasticsearch.md'
---

# Elasticsearch Inspector

Inspect Elasticsearch cluster health, browse indices, and execute search queries.

## Features

| Feature | Description |
|---------|-------------|
| Cluster health | Green/yellow/red status |
| Indices list | All indices with document counts and sizes |
| Index details | Mappings, settings, and statistics |
| Search | Execute search queries against an index |
| Raw query | Run arbitrary Elasticsearch API requests |

## Search

Execute Elasticsearch queries against any index. Specify the index, query body, limit, and offset. Results are displayed with document source data.

## Raw Query

For advanced use, execute any Elasticsearch API request by specifying the HTTP method, endpoint, and optional body.

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/inspect/api/elasticsearch` | Cluster health + indices list |
| GET | `/inspect/api/elasticsearch/{name}` | Index mappings, settings, stats |
| POST | `/inspect/api/elasticsearch/search` | Search query against an index |
| POST | `/inspect/api/elasticsearch/query` | Raw Elasticsearch API request |

**Search request body:**

```json
{
    "index": "products",
    "query": {"match": {"name": "widget"}},
    "limit": 10,
    "offset": 0
}
```

**Raw query request body:**

```json
{
    "method": "GET",
    "endpoint": "/_cluster/stats",
    "body": null
}
```

## Requirements

Requires an AppDevPanel\Api\Inspector\Elasticsearch\ElasticsearchProviderInterface implementation in the DI container. Each adapter provides its own implementation based on the Elasticsearch client library in use.

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/environment.md'
---

# Environment Collector

Collects runtime environment information — PHP version, extensions, OS details, Git branch, server parameters, and environment variables.

![Environment Collector panel](/images/collectors/environment.png)

## What It Captures

| Section | Fields |
|---------|--------|
| **PHP** | version, SAPI, binary path, extensions, xdebug/opcache/pcov status, INI settings |
| **OS** | family, name, uname, hostname |
| **Git** | branch, commit hash (short and full) |
| **Server** | `$_SERVER` parameters |
| **Env** | Environment variables |

## Data Schema

```json
{
    "php": {
        "version": "8.4.1",
        "sapi": "cli-server",
        "binary": "/usr/bin/php",
        "os": "Linux",
        "extensions": ["pdo", "mbstring", "json", "..."],
        "xdebug": false,
        "opcache": "8.4.1",
        "pcov": false,
        "ini": {
            "memory_limit": "256M",
            "max_execution_time": "30",
            "display_errors": "1",
            "error_reporting": 32767
        },
        "zend_extensions": ["Zend OPcache"]
    },
    "os": {
        "family": "Linux",
        "name": "Ubuntu 24.04",
        "uname": "Linux hostname 6.5.0 ...",
        "hostname": "app-server"
    },
    "git": {
        "branch": "main",
        "commit": "a1b2c3d",
        "commitFull": "a1b2c3d4e5f6..."
    },
    "server": {...},
    "env": {...}
}
```

**Summary** (shown in debug entry list):

```json
{
    "environment": {
        "php": {"version": "8.4.1", "sapi": "cli-server"},
        "os": "Linux",
        "git": {"branch": "main", "commit": "a1b2c3d"}
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\EnvironmentCollector;

// Collect from PSR-7 request
$collector->collectFromRequest(request: $serverRequest);

// Or collect from PHP globals
$collector->collectFromGlobals();
```

::: info
\AppDevPanel\Kernel\Collector\EnvironmentCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface. It has no dependencies on other collectors.
:::

## How It Works

The collector reads PHP runtime information via `phpversion()`, `php_sapi_name()`, `get_loaded_extensions()`, INI values, and `php_uname()`. Git information is obtained via shell commands (`git rev-parse`, `git branch`). Server parameters come from the PSR-7 request or `$_SERVER`.

## Debug Panel

* **PHP info** — version, SAPI, extensions, INI settings in a structured view
* **OS info** — operating system family and version
* **Git info** — current branch and commit hash
* **Server/Env tabs** — filterable key-value tables for server params and env vars

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/event.md'
---

# Event Collector

Captures PSR-14 dispatched events with timing, listener metadata, and source location.

![Event Collector panel](/images/collectors/event.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `name` | Event class name |
| `event` | Serialized event object |
| `file` | Source file of the dispatch call |
| `line` | Source line of the dispatch call |
| `time` | Timestamp when the event was dispatched |

## Data Schema

```json
[
    {
        "name": "App\\Event\\UserRegistered",
        "event": "object@App\\Event\\UserRegistered#12",
        "file": "/app/src/UserService.php",
        "line": "42",
        "time": 1711878000.456
    }
]
```

**Summary** (shown in debug entry list):

```json
{
    "event": {
        "total": 8
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\EventCollector;

$collector->collect(
    event: $event,     // The dispatched event object
    line: '/app/src/UserService.php:42',
);
```

::: info
\AppDevPanel\Kernel\Collector\EventCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface and depends on \AppDevPanel\Kernel\Collector\TimelineCollector for cross-collector timeline integration.
:::

## How It Works

The collector is fed by \AppDevPanel\Kernel\Collector\EventDispatcherInterfaceProxy — a PSR-14 Psr\EventDispatcher\EventDispatcherInterface decorator. Every `$dispatcher->dispatch($event)` call is intercepted, timed, and forwarded to the collector.

Framework adapters register the proxy automatically.

## Debug Panel

* **Event type badges** — color-coded by event category (request, response, controller, etc.)
* **Chronological list** — events shown in dispatch order with timestamps
* **Expandable details** — click to view the full event object and listener chain
* **Event count** — total events shown in sidebar badge

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/inspector/events.md'
---

# Event Listeners Inspector

View all registered event listeners across your application — organized by event class.

![Event Listeners Inspector](/images/inspector/events.png)

## What It Shows

| Field | Description |
|-------|-------------|
| Event class | Fully qualified event class name |
| Listeners | List of listener classes/methods subscribed to this event |
| Groups | Common, Web, and Console event dispatchers (tab-separated) |

## Tabs

* **Common** — Event listeners shared across all contexts
* **Web** — Listeners specific to HTTP request handling
* **Console** — Listeners specific to CLI command execution

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/inspect/api/events` | All event listeners by group |

## How It Works

The inspector reads the application's event dispatcher configuration and enumerates all registered listeners. For Symfony, this includes kernel events (`kernel.request`, `kernel.response`, etc.), Doctrine events, and custom application events.

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/exception.md'
---

# Exception Collector

Captures uncaught exceptions with full stack traces and exception chains (previous exceptions).

![Exception Collector panel](/images/collectors/exception.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `class` | Exception class name |
| `message` | Exception message |
| `file` | File where the exception was thrown |
| `line` | Line number |
| `code` | Exception code |
| `trace` | Stack trace array |
| `traceAsString` | Stack trace as formatted string |

## Data Schema

Exceptions are serialized as an array (chain from outermost to innermost):

```json
[
    {
        "class": "RuntimeException",
        "message": "Something went wrong",
        "file": "/app/src/Service.php",
        "line": 42,
        "code": 0,
        "trace": [...],
        "traceAsString": "#0 /app/src/Controller.php(15): ..."
    },
    {
        "class": "InvalidArgumentException",
        "message": "Original cause",
        "file": "/app/src/Validator.php",
        "line": 88,
        "code": 0,
        "trace": [...],
        "traceAsString": "..."
    }
]
```

**Summary** (shown in debug entry list):

```json
{
    "exception": {
        "class": "RuntimeException",
        "message": "Something went wrong",
        "file": "/app/src/Service.php",
        "line": 42,
        "code": 0
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\ExceptionCollector;

$collector->collect(throwable: $exception);
```

::: info
\AppDevPanel\Kernel\Collector\ExceptionCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface and depends on \AppDevPanel\Kernel\Collector\TimelineCollector.
:::

## How It Works

Framework adapters hook into the error handling pipeline to capture uncaught exceptions. The collector traverses the exception chain via `getPrevious()` and serializes each exception in the chain.

## Debug Panel

* **Exception header** — class name, message, and throw location
* **Chained exceptions** — previous exceptions shown in a collapsible chain
* **Syntax-highlighted source code** — shows the file around the throw line
* **Full stack trace** — expandable with file links for IDE integration

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/feature-matrix.md'
---

# Feature Matrix

ADP supports multiple PHP frameworks through adapters. Each adapter wires framework-specific hooks into the shared Kernel collectors. This page documents what is available in each adapter.

## Collector Support by Adapter

All collectors live in the Kernel and are framework-independent. Adapters register and wire them via framework-specific event hooks, proxies, or decorators.

### Universal Collectors

These collectors are registered in **all four adapters**:

| Collector | Frontend Panel | Description |
|-----------|---------------|-------------|
| AppDevPanel\Kernel\Collector\TimelineCollector | Timeline | Performance timeline events |
| AppDevPanel\Kernel\Collector\LogCollector | Logs | PSR-3 log messages |
| AppDevPanel\Kernel\Collector\EventCollector | Events | PSR-14 dispatched events |
| AppDevPanel\Kernel\Collector\ExceptionCollector | Exceptions | Uncaught exceptions with stack traces |
| AppDevPanel\Kernel\Collector\DeprecationCollector | *(in Logs)* | PHP deprecation warnings |
| AppDevPanel\Kernel\Collector\ServiceCollector | Services | DI container service resolutions |
| AppDevPanel\Kernel\Collector\HttpClientCollector | HTTP Client | PSR-18 outgoing HTTP requests |
| AppDevPanel\Kernel\Collector\VarDumperCollector | Var Dumper | `dump()` / `dd()` calls |
| AppDevPanel\Kernel\Collector\EnvironmentCollector | Environment | PHP and OS environment info |
| AppDevPanel\Kernel\Collector\Stream\FilesystemStreamCollector | Filesystem | File system stream operations |
| AppDevPanel\Kernel\Collector\Stream\HttpStreamCollector | *(hidden)* | Raw HTTP stream data (sub-view of HTTP Client) |
| AppDevPanel\Kernel\Collector\Web\RequestCollector | Request | Incoming HTTP request/response (web entries) |
| AppDevPanel\Kernel\Collector\Console\CommandCollector | Request | Console command details (console entries) |
| AppDevPanel\Kernel\Collector\Web\WebAppInfoCollector | *(meta)* | Web app summary for entry list |
| AppDevPanel\Kernel\Collector\Console\ConsoleAppInfoCollector | *(meta)* | Console app summary for entry list |
| AppDevPanel\Kernel\Collector\RouterCollector | Router | HTTP route matching data |
| AppDevPanel\Kernel\Collector\ValidatorCollector | Validator | Validation operations and results |
| AppDevPanel\Kernel\Collector\TranslatorCollector | Translator | Translation lookups, missing translations |
| AppDevPanel\Kernel\Collector\AuthorizationCollector | Security | Authentication and authorization data |
| AppDevPanel\Kernel\Collector\OpenTelemetryCollector | OpenTelemetry | OpenTelemetry spans and traces |

### Collector Availability Matrix

| Collector | Yii 3 | Symfony | Laravel | Yii2 | Frontend Panel |
|-----------|:-------:|:-------:|:-------:|:----:|---------------|
| Database | ✅ | ✅ | ✅ | ✅ | Database |
| Cache | ✅ | ✅ | ✅ | ✅ | Cache |
| Mailer | ✅ | ✅ | ✅ | ✅ | Mailer |
| Queue | ✅ | ✅ | ✅ | ✅ | Queue |
| Redis | ✅ | ✅ | ✅ | ✅ | Redis |
| Elasticsearch | ✅ | ✅ | ✅ | ✅ | Elasticsearch |
| View | ✅ | — | — | ✅ | WebView |
| Templates | — | ✅ | — | ✅ | Templates |
| Code Coverage | — | ✅ | ✅ | ✅ | Coverage |
| Asset Bundles | — | — | — | ✅ | Asset Bundles |
| Middleware | ✅ | — | — | — | Middleware |
| Messenger | — | ✅ | — | — | Messenger |

### Collector Totals by Adapter

| Adapter | Universal | Additional | Total |
|---------|:---------:|:----------:|:-----:|
| Yii 3 | 20 | 8 | **28** |
| Symfony | 20 | 9 | **29** |
| Yii2 | 20 | 10 | **30** |
| Laravel | 20 | 7 | **27** |

## Proxy / Interception Mechanisms

Each adapter uses different strategies to intercept framework internals and feed data into collectors:

| Interface | Yii 3 | Symfony | Laravel | Yii2 |
|-----------|---------|---------|---------|------|
| PSR-3 Logger | AppDevPanel\Kernel\Collector\LoggerInterfaceProxy | AppDevPanel\Kernel\Collector\LoggerInterfaceProxy | AppDevPanel\Kernel\Collector\LoggerInterfaceProxy | AppDevPanel\Adapter\Yii2\Collector\DebugLogTarget |
| PSR-14 Events | AppDevPanel\Kernel\Collector\EventDispatcherInterfaceProxy | AppDevPanel\Adapter\Symfony\Proxy\SymfonyEventDispatcherProxy | AppDevPanel\Adapter\Laravel\Proxy\LaravelEventDispatcherProxy | Wildcard `Event::on('*')` |
| PSR-18 HTTP Client | AppDevPanel\Kernel\Collector\HttpClientInterfaceProxy | AppDevPanel\Kernel\Collector\HttpClientInterfaceProxy | AppDevPanel\Kernel\Collector\HttpClientInterfaceProxy | AppDevPanel\Kernel\Collector\HttpClientInterfaceProxy |
| PSR-11 Container | AppDevPanel\Adapter\Yii3\Proxy\ContainerInterfaceProxy | Compiler pass | — | — |
| VarDumper | AppDevPanel\Adapter\Yii3\Proxy\VarDumperHandlerInterfaceProxy | Handler hook | Handler hook | Handler hook |
| Database | AppDevPanel\Adapter\Yii3\Collector\Db\ConnectionInterfaceProxy | DBAL middleware | Event listener | AppDevPanel\Adapter\Yii2\Collector\DbProfilingTarget |
| Mailer | AppDevPanel\Adapter\Yii3\Collector\Mailer\MailerInterfaceProxy | Event listener | Event listener | Event hook |
| Router | AppDevPanel\Adapter\Yii3\Collector\Router\UrlMatcherInterfaceProxy | — | AppDevPanel\Adapter\Laravel\Collector\RouterDataExtractor | AppDevPanel\Adapter\Yii2\Proxy\UrlRuleProxy |
| Validator | AppDevPanel\Adapter\Yii3\Collector\Validator\ValidatorInterfaceProxy | — | — | — |
| Queue | AppDevPanel\Adapter\Yii3\Collector\Queue\QueueProviderInterfaceProxy | — | Event listener | — |
| View/Templates | — | Twig profiler extension | — | `View::EVENT_AFTER_RENDER` |
| Cache | — | Decorated `CacheAdapter` | Event listener | — |
| Messenger | — | Messenger middleware | — | — |
| Translator | AppDevPanel\Adapter\Yii3\Collector\Translator\TranslatorInterfaceProxy | AppDevPanel\Adapter\Symfony\Proxy\SymfonyTranslatorProxy | AppDevPanel\Adapter\Laravel\Proxy\LaravelTranslatorProxy | AppDevPanel\Adapter\Yii2\Proxy\I18NProxy |

## Inspector Features

Inspector provides live application introspection (not tied to debug entries). All API-based features are adapter-independent:

| Feature | Yii 3 | Symfony | Laravel | Yii2 | Cycle |
|---------|:-------:|:-------:|:-------:|:----:|:-----:|
| Configuration | ✅ | ✅ | ✅ | ✅ | — |
| Database Schema | ✅ | ✅ | ✅ | ✅ | ✅ |
| Routes | ✅ | ✅ | ✅ | ✅ | — |
| File Explorer | ✅ | ✅ | ✅ | ✅ | — |
| Git | ✅ | ✅ | ✅ | ✅ | — |
| Composer | ✅ | ✅ | ✅ | ✅ | — |
| Opcache | ✅ | ✅ | ✅ | ✅ | — |
| PHP Info | ✅ | ✅ | ✅ | ✅ | — |
| Commands | ✅ | ✅ | ✅ | ✅ | — |
| Container / DI | ✅ | ✅ | ✅ | ✅ | — |
| Cache | ✅ | ✅ | ✅ | ✅ | — |
| Translations | ✅ | ✅ | ✅ | ✅ | — |

## Feature Parity Gaps

Current differences between adapters:

| Feature | Yii 3 | Symfony | Laravel | Yii2 |
|---------|:-------:|:-------:|:-------:|:----:|
| View/template debugging | ✅ | ✅ | ❌ | ✅ |
| Code coverage | ❌ | ✅ | ✅ | ✅ |
| Middleware debugging | ✅ | ❌ | ❌ | ❌ |
| Message bus debugging | ❌ | ✅ | ❌ | ❌ |
| Asset bundle debugging | ❌ | ❌ | ❌ | ✅ |
| Container proxy | ✅ | ❌ | ❌ | ❌ |

::: tip
Feature parity is actively improving. If you need a specific collector for your framework, [contributions are welcome](/guide/contributing).
:::

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/inspector/files.md'
---

# File Explorer

Browse your project's file system, view source code, and navigate to class definitions.

![File Explorer](/images/inspector/files.png)

## What It Shows

| Feature | Description |
|---------|-------------|
| Directory listing | Navigate directories with file metadata |
| File viewer | Read source files with syntax highlighting |
| Class resolution | Jump to any PHP class by FQCN |
| Method navigation | Jump to specific method start/end lines |

## File Metadata

Each file entry shows:

* **Name** and **extension**
* **Size** (bytes)
* **Permissions** (octal)
* **Owner/group** (username or UID)
* **Last modified** time

## Class & Method Resolution

Provide a fully qualified class name (e.g., `App\Controller\UserController`) and optionally a method name to jump directly to the source file at the correct line.

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/inspect/api/files?path=/src` | List directory contents or read file |
| GET | `/inspect/api/files?class=App\Controller\UserController` | Resolve class to file |
| GET | `/inspect/api/files?class=App\Controller\UserController&method=index` | Resolve class method with line range |

## IDE Integration

File paths are mapped via AppDevPanel\Api\PathMapperInterface for IDE integration. Click a file path to open it in your local IDE (VS Code, PhpStorm, etc.) if configured.

::: info
File access is restricted to the project root directory. Attempting to navigate outside the root returns a 403 error.
:::

---

---
url: >-
  https://app-dev-panel.github.io/app-dev-panel/guide/collectors/filesystem-stream.md
---

# Filesystem Stream Collector

Captures filesystem (`file://`) stream operations via a PHP stream wrapper proxy — reads, writes, stats, and directory operations.

![Filesystem Stream Collector panel](/images/collectors/filesystem-stream.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `operation` | Operation type (`open`, `read`, `write`, `stat`, `unlink`, `mkdir`, etc.) |
| `path` | File path |
| `args` | Operation arguments |

## Data Schema

Operations are grouped by type:

```json
{
    "open": [
        {"path": "/app/config/app.php", "args": {"mode": "r"}},
        {"path": "/app/var/cache/data.json", "args": {"mode": "w"}}
    ],
    "stat": [
        {"path": "/app/public/index.php", "args": {}}
    ]
}
```

**Summary** (shown in debug entry list):

```json
{
    "fs_stream": {
        "open": 15,
        "read": 42,
        "stat": 8,
        "write": 3
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\Stream\FilesystemStreamCollector;

$collector->collect(
    operation: 'open',
    path: '/app/config/app.php',
    args: ['mode' => 'r'],
);
```

::: info
\AppDevPanel\Kernel\Collector\Stream\FilesystemStreamCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface. Supports configurable ignore patterns to exclude paths (e.g., vendor directory).
:::

## How It Works

The collector uses a PHP stream wrapper proxy (\AppDevPanel\Kernel\Collector\Stream\FilesystemStreamProxy) that registers itself for the `file://` protocol. All filesystem operations (`fopen`, `file_get_contents`, `is_file`, `mkdir`, etc.) are intercepted via PHP's stream wrapper mechanism. Paths matching `excludePaths` patterns are ignored.

## Debug Panel

* **Operation groups** — filesystem operations grouped by type
* **File path list** — all accessed paths with operation details
* **Operation counts** — summary of operations per type in sidebar badge (I/O)

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/frontend-packages.md'
---

# Frontend Packages

ADP provides three npm packages under the `@app-dev-panel` scope, published to [GitHub Packages](https://github.com/orgs/app-dev-panel/packages).

| Package | Description |
|---------|-------------|
| `@app-dev-panel/sdk` | Shared library: React components, API clients (RTK Query), theme system, helpers |
| `@app-dev-panel/panel` | Main SPA — the debug panel application |
| `@app-dev-panel/toolbar` | Embeddable toolbar widget for injecting into your application |

## Installation

### 1. Configure GitHub Packages registry

ADP frontend packages are hosted on GitHub Packages. Add the registry scope to your project:

```bash
echo "@app-dev-panel:registry=https://npm.pkg.github.com" >> .npmrc
```

::: tip Authentication
GitHub Packages requires authentication even for public packages. Create a [personal access token](https://github.com/settings/tokens) with `read:packages` scope and add it to your `~/.npmrc`:

```bash
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
```

:::

### 2. Install packages

```bash
# SDK only (components, API clients, helpers)
npm install @app-dev-panel/sdk

# Full panel application
npm install @app-dev-panel/panel

# Toolbar widget
npm install @app-dev-panel/toolbar
```

## Packages

### SDK (`@app-dev-panel/sdk`)

The foundation library used by both panel and toolbar. Contains:

* **API clients** — RTK Query endpoints for debug data, inspector, git, and LLM APIs
* **React components** — `JsonRenderer`, `CodeHighlight`, `DataGrid`, `SearchFilter`, `EmptyState`, `CommandPalette`
* **Layout components** — `TopBar`, `UnifiedSidebar`, `EntrySelector`, `ContentPanel`
* **Theme system** — MUI 5 theme with light/dark mode, design tokens, brand colors
* **Helpers** — fuzzy matching, keyboard layout transliteration (QWERTY/ЙЦУКЕН), date formatting
* **SSE** — `useServerSentEvents` hook for real-time debug entry updates
* **State management** — Redux Toolkit slices for application state, debug entries, notifications

```typescript
import { createAppTheme } from '@app-dev-panel/sdk/Component/Theme/DefaultTheme';
import { JsonRenderer } from '@app-dev-panel/sdk/Component/JsonRenderer';
import { useServerSentEvents } from '@app-dev-panel/sdk/Component/useServerSentEvents';
```

### Panel (`@app-dev-panel/panel`)

The main debug panel SPA. Modules:

* **Debug** — collector panels (logs, database, events, exceptions, timeline, etc.)
* **Inspector** — live application state (routes, config, database, git, cache, files, translations, etc.)
* **LLM** — AI-powered chat and analysis integration
* **MCP** — MCP server configuration page
* **OpenAPI** — Swagger UI integration

### Toolbar (`@app-dev-panel/toolbar`)

Embeddable widget that shows a compact debug bar at the bottom of your application. Displays key metrics (request time, memory, query count) and links to the full panel.

## Pre-built Assets

Each [GitHub Release](https://github.com/app-dev-panel/app-dev-panel/releases) includes pre-built static assets:

| Asset | Contents |
|-------|----------|
| `panel-dist.tar.gz` | Production build of the panel SPA |
| `toolbar-dist.tar.gz` | Production build of the toolbar widget |

These can be served directly by a web server or embedded into PHP adapter packages.

## Development

### Prerequisites

* Node.js 21+
* npm 10+

### Setup

```bash
git clone https://github.com/app-dev-panel/app-dev-panel.git
cd app-dev-panel/libs/frontend
npm install
```

### Commands

```bash
npm start              # Start all Vite dev servers (panel + toolbar + sdk)
npm run build          # Production build all packages
npm run check          # Run Prettier + ESLint checks
npm test               # Run Vitest unit tests
npm run test:e2e       # Run browser E2E tests (requires Chrome)
```

### Project Structure

```
libs/frontend/
├── packages/
│   ├── sdk/           # Shared library (components, API, theme, helpers)
│   ├── panel/         # Main SPA
│   └── toolbar/       # Toolbar widget
├── lerna.json         # Independent versioning
└── package.json       # npm workspaces root
```

### Tech Stack

* React 19, TypeScript 5.5+
* Vite 5 (build tool)
* MUI 5 (Material UI components)
* Redux Toolkit + RTK Query (state management + API)
* React Router 6 (navigation)
* Vitest (testing)
* Prettier 3.8+ and ESLint 9 (code quality)

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/getting-started.md'
---

# Getting Started

ADP (Application Development Panel) is a framework-agnostic debugging panel for PHP applications. It collects runtime data and provides a web UI to inspect and debug your application.

## Prerequisites

* PHP 8.4 or higher
* Composer

## Installation

### 1. Install the adapter for your framework

:::tabs key:framework
\== Symfony

```bash
composer require app-dev-panel/adapter-symfony
```

\== Yii 2

```bash
composer require app-dev-panel/adapter-yii2
```

\== Yii 3

```bash
composer require app-dev-panel/adapter-yii3
```

\== Laravel

```bash
composer require app-dev-panel/adapter-laravel
```

:::

Each adapter pulls in app-dev-panel/kernel and app-dev-panel/api as dependencies automatically.

### 2. Configure your application

:::tabs key:framework
\== Symfony

```php
// config/bundles.php
return [
    // ...
    AppDevPanel\Adapter\Symfony\AppDevPanelBundle::class => ['dev' => true, 'test' => true],
];
```

\== Yii 2

```php
// config/web.php
return [
    'bootstrap' => ['debug-panel'],
    'modules' => [
        'debug-panel' => [
            'class' => \AppDevPanel\Adapter\Yii2\Module::class,
        ],
    ],
];
```

\== Yii 3

```php
// No configuration needed — auto-registered via yiisoft/config plugin
```

\== Laravel

```php
// Auto-registered via package discovery
// Optionally publish config:
// php artisan vendor:publish --tag=app-dev-panel-config
```

:::

### 3. Start debugging

Run your application and open `http://your-app/debug` in your browser. The ADP [debug panel](/guide/debug-panel) shows debug data collected from your application in real-time.

::: tip PHP Built-in Server
When using PHP's built-in server, always set `PHP_CLI_SERVER_WORKERS=3` or higher. ADP makes concurrent requests (SSE + data fetching); single-worker mode causes timeouts.

```bash
PHP_CLI_SERVER_WORKERS=3 php -S 127.0.0.1:8080 -t public
```

:::

## Try the Demo

You can try the panel UI right away with the [Live Demo](https://app-dev-panel.github.io/app-dev-panel/demo/) — no installation required. Enter your application's backend URL to connect.

ADP also ships with [playground applications](/guide/playgrounds) for each supported framework:

```bash
git clone https://github.com/app-dev-panel/app-dev-panel.git
cd app-dev-panel
make install              # Install all dependencies
```

Start a playground server:

:::tabs key:framework
\== Symfony

```bash
cd playground/symfony-app && PHP_CLI_SERVER_WORKERS=3 php -S 127.0.0.1:8102 -t public
```

\== Yii 2

```bash
cd playground/yii2-basic-app && PHP_CLI_SERVER_WORKERS=3 php -S 127.0.0.1:8103 -t public
```

\== Yii 3

```bash
cd playground/yii3-app && ./yii serve --port=8101
```

\== Laravel

```bash
cd playground/laravel-app && PHP_CLI_SERVER_WORKERS=3 php -S 127.0.0.1:8104 -t public
```

:::

## Architecture Overview

ADP follows a layered architecture:

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Frontend   │────▶│     API      │────▶│    Kernel     │
│  (React SPA) │ HTTP│  (REST+SSE)  │     │ (Collectors)  │
└──────────────┘     └──────────────┘     └───────┬───────┘
                                                  │
                                          ┌───────┴───────┐
                                          │    Adapter     │
                                          └───────┬───────┘
                                                  │
                                          ┌───────┴───────┐
                                          │  Target App   │
                                          └───────────────┘
```

1. **Kernel** — Core engine managing debugger lifecycle, collectors, and storage
2. **API** — HTTP layer exposing debug data via REST + SSE
3. **Adapter** — Framework bridge wiring collectors into your application
4. **Frontend** — React SPA consuming the API

## What's Next?

* [What is ADP?](/guide/what-is-adp) — Learn about the project philosophy
* [Debug Panel](/guide/debug-panel) — Configure the embedded debug panel UI
* [Architecture](/guide/architecture) — Deep dive into the system design
* [Collectors](/guide/collectors) — Understand how data is collected
* [Data Flow](/guide/data-flow) — Follow data from your app to the panel
* [Feature Matrix](/guide/feature-matrix) — See what's supported per framework
* [Playgrounds](/guide/playgrounds) — Try the demo applications

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/inspector/git.md'
---

# Git Inspector

View repository status, browse commit history, and perform basic Git operations.

![Git Inspector — Summary](/images/inspector/git.png)

## Summary View

| Field | Description |
|-------|-------------|
| Branch | Current branch name with checkout button |
| Last commit | SHA, message, and author of the latest commit |
| Remote | Remote name and URL |
| Status | Current `git status` output |

## Actions

| Action | Description |
|--------|-------------|
| **Checkout** | Switch to any branch (validated: alphanumeric, `/`, `.`, `-`, `_`) |
| **Pull** | Run `git pull --rebase=false` |
| **Fetch** | Run `git fetch --tags` |

## Commit Log

![Git Inspector — Log](/images/inspector/git-log.png)

Browse the last 20 commits with SHA, message, and author info.

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/inspect/api/git/summary` | Branch, SHA, remotes, status |
| GET | `/inspect/api/git/log` | Last 20 commits |
| POST | `/inspect/api/git/checkout` | Switch branch |
| POST | `/inspect/api/git/command` | Run pull or fetch |

**Checkout request body:**

```json
{
    "branch": "feature/my-branch"
}
```

**Command request:**

```
POST /inspect/api/git/command?command=pull
```

::: tip
Git operations use the [Gitonomy](https://github.com/gitonomy/gitlib) library for safe repository interaction.
:::

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/http-client.md'
---

# HTTP Client Collector

Captures outgoing PSR-18 HTTP requests and responses with timing and status codes.

![HTTP Client Collector panel](/images/collectors/http-client.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `method` | HTTP method (GET, POST, etc.) |
| `uri` | Request URI |
| `headers` | Request headers |
| `line` | Source file and line of the HTTP call |
| `responseStatus` | Response HTTP status code |
| `responseRaw` | Raw response body |
| `totalTime` | Total request/response time in seconds |

## Data Schema

```json
[
    {
        "startTime": 1711878000.100,
        "endTime": 1711878000.350,
        "totalTime": 0.25,
        "method": "GET",
        "uri": "https://api.example.com/users/42",
        "headers": {"Authorization": "Bearer ***"},
        "line": "/app/src/ApiClient.php:55",
        "responseRaw": "{\"id\": 42, \"name\": \"John\"}",
        "responseStatus": 200
    }
]
```

**Summary** (shown in debug entry list):

```json
{
    "http": {
        "count": 3,
        "totalTime": 0.75
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\HttpClientCollector;

// Start collection
$collector->collect(
    request: $psrRequest,
    startTime: microtime(true),
    line: '/app/src/ApiClient.php:55',
    uniqueId: 'req-1',
);

// Complete with response
$collector->collectTotalTime(
    response: $psrResponse,
    endTime: microtime(true),
    uniqueId: 'req-1',
);
```

::: info
\AppDevPanel\Kernel\Collector\HttpClientCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface and depends on \AppDevPanel\Kernel\Collector\TimelineCollector.
:::

## How It Works

The collector is fed by \AppDevPanel\Kernel\Collector\HttpClientInterfaceProxy — a PSR-18 Psr\Http\Client\ClientInterface decorator. Every `$client->sendRequest($request)` call is automatically intercepted, timed, and recorded.

## Debug Panel

* **Request list** — all outgoing HTTP calls with method, URL, status, and timing
* **Request/response details** — expandable view with headers and body
* **Status badges** — color-coded by response status (2xx green, 4xx orange, 5xx red)
* **Timing breakdown** — per-request duration

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/http-stream.md'
---

# HTTP Stream Collector

Captures HTTP/HTTPS stream wrapper operations — requests made via `file_get_contents('http://...')`, `fopen('https://...')`, and similar PHP stream functions.

![HTTP Stream Collector panel](/images/collectors/http-stream.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `operation` | Stream operation type (`open`, `read`, `stat`, etc.) |
| `uri` | HTTP/HTTPS URL accessed |
| `args` | Operation arguments |

## Data Schema

Operations are grouped by type:

```json
{
    "open": [
        {"uri": "https://api.example.com/data", "args": {"mode": "r"}}
    ]
}
```

**Summary** (shown in debug entry list):

```json
{
    "http_stream": {
        "open": 2,
        "read": 2
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\Stream\HttpStreamCollector;

$collector->collect(
    operation: 'open',
    path: 'https://api.example.com/data',
    args: ['mode' => 'r'],
);
```

::: info
\AppDevPanel\Kernel\Collector\Stream\HttpStreamCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface. Supports configurable ignore patterns.
:::

## How It Works

The collector uses a PHP stream wrapper proxy (\AppDevPanel\Kernel\Collector\Stream\HttpStreamProxy) that registers itself for the `http://` and `https://` protocols. Stream operations via native PHP functions are intercepted. Paths matching `excludePaths` patterns are ignored.

::: warning
This collector only captures HTTP requests made via PHP stream functions (`file_get_contents`, `fopen`). For PSR-18 HTTP client calls, use the [HTTP Client Collector](/guide/collectors/http-client).
:::

## Debug Panel

* **Operation list** — HTTP stream operations with URLs
* **Combined with Filesystem** — displayed together with \AppDevPanel\Kernel\Collector\Stream\FilesystemStreamCollector under the "I/O" sidebar item

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/api/inspector.md'
---
# Inspector Endpoints

Inspector endpoints query live application state. All routes are under `/inspect/api`.

## Core Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/routes` | All registered routes |
| GET | `/route/check` | Test route matching |
| GET | `/params` | Application parameters |
| GET | `/config` | DI configuration |
| GET | `/events` | Event listeners |
| GET | `/classes` | Declared classes |
| GET | `/object` | Instantiate and dump object |
| GET | `/files` | File explorer |
| GET | `/phpinfo` | PHP info output |

## Database

| Method | Path | Description |
|--------|------|-------------|
| GET | `/table` | Database tables list |
| GET | `/table/{name}` | Table schema + paginated records |

## Translations

| Method | Path | Description |
|--------|------|-------------|
| GET | `/translations` | Translation catalogs |
| PUT | `/translations` | Update a translation |

## Request

| Method | Path | Description |
|--------|------|-------------|
| PUT | `/request` | Re-execute a captured request |
| POST | `/curl/build` | Build cURL command from request |

## Git

| Method | Path | Description |
|--------|------|-------------|
| GET | `/git/summary` | Branch, SHA, remotes, branches |
| GET | `/git/log` | Last 20 commits |
| POST | `/git/checkout` | Switch branch |
| POST | `/git/command` | Run git pull/fetch |

## Commands

| Method | Path | Description |
|--------|------|-------------|
| GET | `/command/` | List available commands |
| POST | `/command/` | Execute a command |

## Composer

| Method | Path | Description |
|--------|------|-------------|
| GET | `/composer/` | composer.json + composer.lock |
| GET | `/composer/inspect` | Package details |
| POST | `/composer/require` | Install a package |

## Cache

| Method | Path | Description |
|--------|------|-------------|
| GET | `/cache/` | View cache entry |
| DELETE | `/cache/` | Delete cache key |
| POST | `/cache/clear` | Clear all cache |

## OPcache

| Method | Path | Description |
|--------|------|-------------|
| GET | `/opcache/` | OPcache status and configuration |

## Authorization

| Method | Path | Description |
|--------|------|-------------|
| GET | `/authorization` | Guards, role hierarchy, voters, security config |

See [Security & Authorization](/guide/security) for details.

## Elasticsearch

| Method | Path | Description |
|--------|------|-------------|
| GET | `/elasticsearch` | Cluster health + indices list |
| GET | `/elasticsearch/{name}` | Index detail (mappings, settings, stats) |
| POST | `/elasticsearch/search` | Execute search query against an index |
| POST | `/elasticsearch/query` | Execute raw Elasticsearch query |

## Redis

| Method | Path | Description |
|--------|------|-------------|
| GET | `/redis/ping` | Test Redis connection |
| GET | `/redis/info` | Server info (`INFO` command, optional `?section=`) |
| GET | `/redis/db-size` | Number of keys in current DB |
| GET | `/redis/keys` | Browse keys via SCAN (`?pattern=*&limit=100&cursor=0`) |
| GET | `/redis/get` | Get key value (type-aware) with TTL |
| DELETE | `/redis/delete` | Delete a key |
| POST | `/redis/flush-db` | Flush current database |

Requires `\Redis` (phpredis extension) in the DI container.

## Code Coverage

| Method | Path | Description |
|--------|------|-------------|
| GET | `/coverage/` | Collect and return PHP code coverage data (requires pcov or xdebug) |
| GET | `/coverage/file` | Read a source file (query param: `path`) |

## MCP (AI Integration)

| Method | Path | Description |
|--------|------|-------------|
| POST | `/mcp/` | JSON-RPC 2.0 handler |
| GET | `/mcp/settings` | Get MCP enabled status |
| PUT | `/mcp/settings` | Set MCP enabled status |

## Multi-Service Proxying

Inspector requests with `?service=<name>` are proxied to the registered external service's URL via AppDevPanel\Api\Inspector\Middleware\InspectorProxyMiddleware. Requests without `?service` or with `?service=local` are handled locally.

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/adapters/laravel.md'
---
# Laravel Adapter

The Laravel adapter bridges ADP Kernel and API into Laravel 11.x / 12.x via a service provider with auto-discovery.

## Installation

```bash
composer require app-dev-panel/adapter-laravel
```

::: info Package
app-dev-panel/adapter-laravel
:::

The package is auto-discovered via `extra.laravel.providers` in composer.json — no manual registration needed.

## Configuration

Publish the configuration file:

```bash
php artisan vendor:publish --provider="AppDevPanel\Adapter\Laravel\AppDevPanelServiceProvider"
```

This creates `config/app-dev-panel.php`:

```php
return [
    'enabled' => env('APP_DEV_PANEL_ENABLED', env('APP_DEBUG', true)),
    'storage' => [
        'path' => storage_path('debug'),
        'history_size' => 50,
    ],
    'collectors' => [
        'request' => true,
        'exception' => true,
        'log' => true,
        'event' => true,
        'database' => true,
        'cache' => true,
        'mailer' => true,
        'queue' => true,
        'code_coverage' => false,  // opt-in; requires pcov or xdebug
        // ... all collectors enabled by default
    ],
    'ignored_requests' => ['/debug/api/**', '/inspect/api/**'],
    'ignored_commands' => ['completion', 'help', 'list', 'debug:*', 'cache:*'],
    'api' => [
        'enabled' => true,
        'allowed_ips' => ['127.0.0.1', '::1'],
        'auth_token' => env('APP_DEV_PANEL_TOKEN', ''),
    ],
];
```

## Collectors

Supports all Kernel collectors plus Laravel-specific data capture via event listeners: Eloquent queries, cache operations, mail, queue jobs, HTTP client requests, translator lookups, and [Redis commands](/guide/collectors/redis) (via `Redis::listen()`).

## Translator Integration

The adapter automatically decorates Laravel's `Translator` service with AppDevPanel\Adapter\Laravel\Proxy\LaravelTranslatorProxy via `$app->extend('translator')`. All `__('key')`, `trans()`, and `Lang::get()` calls are intercepted. Laravel's dot-notation keys (`group.key`) are parsed into category and message. See [Translator](/guide/translator) for details.

## Database Inspector

AppDevPanel\Adapter\Laravel\Inspector\LaravelSchemaProvider provides database schema inspection via `Illuminate\Database\Connection`. Falls back to AppDevPanel\Adapter\Laravel\Inspector\NullSchemaProvider when no database is configured.

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/llms-txt.md'
---

# llms.txt

ADP provides machine-readable documentation following the [llms.txt](https://llmstxt.org/) standard. This allows AI assistants (Claude, ChatGPT, Cursor, Copilot, and others) to quickly understand the project and provide accurate answers about it.

## What is llms.txt?

llms.txt is an open standard proposed by Jeremy Howard (fast.ai). It provides a well-known URL (`/llms.txt`) where websites expose their documentation in a clean markdown format optimized for LLM consumption — no HTML, no JavaScript, no navigation clutter.

## Available Files

| File | URL | Content |
|------|-----|---------|
| `llms.txt` | [/llms.txt](/llms.txt) | Concise table of contents with links to per-page `.md` files |
| `llms-full.txt` | [/llms-full.txt](/llms-full.txt) | All documentation pages concatenated into a single file |
| `*.md` (per-page) | e.g. [/guide/collectors.md](/guide/collectors.md) | Clean markdown for any individual page |

**`llms.txt`** is a lightweight index — titles and links. Use it when your AI tool has limited context or you need a quick overview.

**`llms-full.txt`** contains the complete documentation in one file (~13K tokens). Use it when your AI tool has a large context window and you want comprehensive answers.

**Per-page `.md` files** are available for every documentation page. Use them when you need information about a specific topic without loading the entire documentation.

## How to Use

### In Claude (claude.ai)

Paste the URL in the chat:

```
Read https://app-dev-panel.github.io/app-dev-panel/llms-full.txt and answer my questions about ADP.
```

### In Claude Code

Use the `WebFetch` tool or paste the URL:

```
Fetch https://app-dev-panel.github.io/app-dev-panel/llms-full.txt
```

### In Cursor / Copilot / other IDE assistants

Add the URL as a documentation source in your IDE settings, or paste it into the chat context.

### In custom agents

Fetch the file programmatically and include it in the system prompt:

```python
import httpx

response = httpx.get("https://app-dev-panel.github.io/app-dev-panel/llms-full.txt")
docs = response.text

messages = [
    {"role": "system", "content": f"ADP documentation:\n\n{docs}"},
    {"role": "user", "content": "How do I add a custom collector?"},
]
```

## What's Inside

Both files are auto-generated at build time from the same markdown sources that produce this documentation site. They include:

* **Getting Started** — installation for each framework
* **Architecture** — layers, data flow, proxy system
* **Collectors** — all 28 collectors with descriptions
* **API Reference** — REST endpoints, SSE, Inspector API
* **Adapters** — Symfony, Yii 2, Yii 3, Laravel
* **MCP Server** — AI integration setup
* **CLI** — commands and options

Content stays in sync automatically — when a documentation page is updated, the next build regenerates both files.

## How It Works

Powered by [`vitepress-plugin-llms`](https://github.com/okineadev/vitepress-plugin-llms) — the same plugin used by Vite, Vue.js, and Vitest.

The plugin operates as a Vite plugin during the build:

1. **Collects** all markdown files during Vite's transform phase
2. **Cleans** content via remark AST — strips frontmatter, HTML, Vue components
3. **Generates** `llms.txt` (TOC), `llms-full.txt` (concatenated), and per-page `.md` files
4. **Injects** hidden hints on HTML pages pointing LLMs to the `.md` versions

Only English pages are included. Russian translations are excluded via `ignoreFiles: ['ru/**']`.

Source: [plugin config in `config.ts`](https://github.com/app-dev-panel/app-dev-panel/blob/master/website/.vitepress/config.ts)

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/log.md'
---

# Log Collector

Captures PSR-3 log messages recorded during a request or console command — level, message, context, and source location.

![Log Collector panel](/images/collectors/log.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `time` | Timestamp when the log entry was recorded |
| `level` | PSR-3 log level (`debug`, `info`, `warning`, `error`, etc.) |
| `message` | Log message (string or stringable) |
| `context` | Contextual data array passed with the log call |
| `line` | Source file and line where the log call originated |

## Data Schema

```json
[
    {
        "time": 1711878000.123,
        "level": "info",
        "message": "User logged in",
        "context": {"userId": 42},
        "line": "/app/src/AuthService.php:87"
    }
]
```

**Summary** (shown in debug entry list):

```json
{
    "logger": {
        "total": 5
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\LogCollector;

$collector->collect(
    level: 'info',
    message: 'User logged in',
    context: ['userId' => 42],
    line: '/app/src/AuthService.php:87',
);
```

::: info
\AppDevPanel\Kernel\Collector\LogCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface and depends on \AppDevPanel\Kernel\Collector\TimelineCollector for cross-collector timeline integration.
:::

## How It Works

The collector is fed by \AppDevPanel\Kernel\Collector\LoggerInterfaceProxy — a PSR-3 Psr\Log\LoggerInterface decorator. When the proxy is registered as the application's logger, every `$logger->info(...)`, `$logger->error(...)`, etc. call is automatically intercepted and forwarded to the collector.

No manual wiring is needed if you use an adapter (Symfony, Laravel, Yii) — the proxy is registered automatically.

## Debug Panel

* **Filterable log list** — search by message text or log level
* **Color-coded levels** — each PSR-3 level has a distinct color badge
* **Expandable entries** — click to view full context data and source location
* **Entry count** — total log entries shown in sidebar badge

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/mailer.md'
---

# Mailer Collector

Captures email messages sent during a request — recipients, subject, body, and metadata.

![Mailer Collector panel](/images/collectors/mailer.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `from` | Sender addresses |
| `to` | Recipient addresses |
| `cc` | CC addresses |
| `bcc` | BCC addresses |
| `replyTo` | Reply-To addresses |
| `subject` | Email subject line |
| `textBody` | Plain text body |
| `htmlBody` | HTML body |
| `charset` | Character set |
| `date` | Send date |

## Data Schema

```json
{
    "messages": [
        {
            "from": [{"address": "noreply@app.com", "name": "App"}],
            "to": [{"address": "user@example.com", "name": "Test User"}],
            "cc": [],
            "bcc": [],
            "replyTo": [],
            "subject": "Welcome to App",
            "textBody": "Hello, welcome!",
            "htmlBody": "<h1>Welcome</h1>",
            "raw": "...",
            "charset": "utf-8",
            "date": "Tue, 31 Mar 2026 12:00:00 +0000"
        }
    ]
}
```

**Summary** (shown in debug entry list):

```json
{
    "mailer": {
        "total": 1
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\MailerCollector;

$collector->collectMessage([
    'from' => [['address' => 'noreply@app.com', 'name' => 'App']],
    'to' => [['address' => 'user@example.com', 'name' => 'Test User']],
    'subject' => 'Welcome to App',
    'textBody' => 'Hello, welcome!',
    'htmlBody' => '<h1>Welcome</h1>',
    // ...
]);
```

::: info
\AppDevPanel\Kernel\Collector\MailerCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface and depends on \AppDevPanel\Kernel\Collector\TimelineCollector.
:::

## How It Works

Framework adapters intercept email sending through framework-specific hooks:

* **Symfony**: `MessageEvent` listener on the Mailer component
* **Laravel**: `MessageSending` event listener
* **Yii 3**: Mailer proxy decorator

## Debug Panel

* **Message list** — all emails with subject, recipients, and send date
* **Expandable details** — full email headers, text body, and HTML body preview
* **Message count** — total shown in sidebar badge

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/mcp-server.md'
---

# MCP Server

ADP includes an MCP (Model Context Protocol) server that exposes debug data to AI assistants like Claude, Cursor, and other MCP-compatible clients.

## Transports

ADP supports two transport modes for MCP communication:

| Transport | Use Case | Entry Point |
|-----------|----------|-------------|
| **stdio** | AI clients that launch a local process (Claude Code, Cursor) | `php vendor/bin/adp-mcp` |
| **HTTP** | AI clients that connect to a running server | `POST /inspect/api/mcp` |

### stdio Transport

Configure your AI client to launch the ADP MCP binary:

```json
{
  "mcpServers": {
    "adp": {
      "command": "php",
      "args": ["vendor/bin/adp-mcp", "--storage=/path/to/debug-data"]
    }
  }
}
```

The `ADP_STORAGE_PATH` environment variable is also accepted.

### HTTP Transport

Available automatically when the ADP server is running. For clients that support HTTP URLs:

```json
{
  "mcpServers": {
    "AppDevPanel": {
      "url": "http://localhost:8080/inspect/api/mcp"
    }
  }
}
```

For stdio-only clients (e.g., Claude Desktop), use the `mcp-remote` proxy:

```json
{
  "mcpServers": {
    "AppDevPanel": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8080/inspect/api/mcp"]
    }
  }
}
```

## Available Tools

The MCP server exposes six debug tools:

| Tool | Description |
|------|-------------|
| `list_debug_entries` | List recent debug entries with summary info |
| `view_debug_entry` | View full collector data for a specific entry |
| `search_logs` | Search log messages across all entries by query and level |
| `analyze_exception` | Exception details with stack trace and context |
| `view_database_queries` | SQL queries with timing and N+1 detection |
| `view_timeline` | Performance timeline from all collectors |

## Enabling and Disabling

The MCP server can be toggled via the Settings UI in the frontend or via the API:

```bash
# Check status
curl http://localhost:8080/inspect/api/mcp/settings

# Enable
curl -X PUT http://localhost:8080/inspect/api/mcp/settings \
  -H "Content-Type: application/json" -d '{"enabled": true}'
```

When disabled, the MCP endpoint returns a JSON-RPC error code `-32000`.

## Protocol

ADP implements MCP spec version `2024-11-05` using JSON-RPC 2.0. Supported methods: `initialize`, `initialized`, `ping`, `tools/list`, `tools/call`.

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/middleware.md'
---

# Middleware Collector

Captures HTTP middleware stack execution — the before and after processing phases with timing and memory usage.

## What It Captures

| Field | Description |
|-------|-------------|
| `beforeStack` | Middleware invoked before the action handler |
| `actionHandler` | The main action/controller handler |
| `afterStack` | Middleware invoked after the action handler |

Each middleware entry contains:

| Field | Description |
|-------|-------------|
| `name` | Middleware class name |
| `time` | Execution timestamp |
| `memory` | Memory usage at this point |
| `request` | Request state (before stack) |
| `response` | Response state (after stack) |

## Data Schema

```json
{
    "beforeStack": [
        {"name": "App\\Middleware\\AuthMiddleware", "time": 1711878000.100, "memory": 2097152, "request": "..."}
    ],
    "actionHandler": {
        "name": "App\\Controller\\UserController::index",
        "startTime": 1711878000.105,
        "request": "...",
        "response": "...",
        "endTime": 1711878000.120,
        "memory": 4194304
    },
    "afterStack": [
        {"name": "App\\Middleware\\CorsMiddleware", "time": 1711878000.121, "memory": 4194304, "response": "..."}
    ]
}
```

**Summary** (shown in debug entry list):

```json
{
    "middleware": {
        "total": 5
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\MiddlewareCollector;

$collector->collectBefore(
    name: 'App\\Middleware\\AuthMiddleware',
    time: microtime(true),
    memory: memory_get_usage(),
    request: $request,
);

$collector->collectAfter(
    name: 'App\\Middleware\\CorsMiddleware',
    time: microtime(true),
    memory: memory_get_usage(),
    response: $response,
);
```

::: info
\AppDevPanel\Kernel\Collector\MiddlewareCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface and depends on \AppDevPanel\Kernel\Collector\TimelineCollector.
:::

## How It Works

Framework adapters instrument the middleware pipeline:

* **Yii 3**: \AppDevPanel\Adapter\Yii3\Collector\Middleware\MiddlewareEventListener listens to Yii middleware events
* **Symfony**: Kernel events (`kernel.request`, `kernel.response`, `kernel.controller`)
* **Laravel**: Middleware pipeline hooks

## Debug Panel

* **Middleware stack** — visual before/after pipeline with action handler in the middle
* **Timing** — execution time for each middleware
* **Memory tracking** — memory usage delta across the pipeline

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/inspector/opcache.md'
---

# OPcache Inspector

View PHP OPcache status and configuration.

![OPcache Inspector](/images/inspector/opcache.png)

## What It Shows

| Section | Description |
|---------|-------------|
| Status | OPcache enabled/disabled, memory usage, hit rate |
| Configuration | OPcache INI directives and their values |
| Statistics | Cache hits, misses, restarts, cached scripts count |

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/inspect/api/opcache` | OPcache status and configuration |

::: info
Returns HTTP 422 if OPcache is not enabled on the server.
:::

---

---
url: >-
  https://app-dev-panel.github.io/app-dev-panel/guide/collectors/opentelemetry.md
---

# OpenTelemetry Collector

Captures OpenTelemetry spans and traces — distributed tracing data with error counting and span metadata.

![OpenTelemetry Collector panel](/images/collectors/opentelemetry.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `spans` | Array of collected spans |
| `traceCount` | Number of distinct traces |
| `spanCount` | Total number of spans |
| `errorCount` | Number of spans with errors |

## Data Schema

```json
{
    "spans": [
        {
            "traceId": "abc123...",
            "spanId": "def456...",
            "parentSpanId": null,
            "name": "HTTP GET /users",
            "kind": "SERVER",
            "startTime": 1711878000100,
            "endTime": 1711878000350,
            "status": "OK",
            "attributes": {"http.method": "GET", "http.url": "/users"},
            "events": []
        }
    ],
    "traceCount": 1,
    "spanCount": 5,
    "errorCount": 0
}
```

**Summary** (shown in debug entry list):

```json
{
    "opentelemetry": {
        "spans": 5,
        "traces": 1,
        "errors": 0
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\OpenTelemetryCollector;
use AppDevPanel\Kernel\Collector\SpanRecord;

$collector->collect(new SpanRecord(
    traceId: 'abc123...',
    spanId: 'def456...',
    name: 'HTTP GET /users',
    kind: 'SERVER',
    startTime: 1711878000100,
    endTime: 1711878000350,
    status: 'OK',
    attributes: ['http.method' => 'GET'],
));

// Or batch collection
$collector->collectBatch([$span1, $span2, $span3]);
```

::: info
\AppDevPanel\Kernel\Collector\OpenTelemetryCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface and depends on \AppDevPanel\Kernel\Collector\TimelineCollector.
:::

## How It Works

The collector receives spans from an OpenTelemetry `SpanExporter` adapter. When your application uses OpenTelemetry SDK for tracing, spans are exported to this collector instead of (or in addition to) external backends like Jaeger or Zipkin.

## Debug Panel

* **Trace view** — spans grouped by trace ID
* **Span timeline** — visual timeline of span durations
* **Error highlighting** — spans with errors marked in red
* **Attribute inspection** — expandable span attributes and events

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/inspector/phpinfo.md'
---

# PHP Info

View the full output of `phpinfo()` rendered in the panel.

![PHP Info](/images/inspector/phpinfo.png)

## What It Shows

The complete PHP configuration output including:

* PHP version and build info
* Loaded extensions and their settings
* Server API (SAPI)
* Configuration directives (`php.ini` values)
* Environment variables
* HTTP request/response headers

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/inspect/api/phpinfo` | PHP info output |

::: info
The output is the same as calling `phpinfo()` directly, rendered as HTML within the panel iframe.
:::

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/playgrounds.md'
---

# Playgrounds

Playgrounds are minimal, working applications demonstrating ADP integration with specific PHP frameworks. Each playground installs the corresponding ADP adapter, configures collectors, and exposes demo endpoints that generate debug data.

## Available Playgrounds

| Playground | Framework | Port | Adapter |
|------------|-----------|------|---------|
| `yii3-app` | Yii 3 | 8101 | app-dev-panel/adapter-yii3 |
| `symfony-app` | Symfony 7 | 8102 | app-dev-panel/adapter-symfony |
| `yii2-basic-app` | Yii 2 | 8103 | app-dev-panel/adapter-yii2 |
| `laravel-app` | Laravel 12 | 8104 | app-dev-panel/adapter-laravel |

## Running Playgrounds

### Install Dependencies

```bash
make install-playgrounds
```

### Start Servers

Each playground runs on its own port. Start in separate terminals:

:::tabs key:framework
\== Symfony

```bash
cd playground/symfony-app && PHP_CLI_SERVER_WORKERS=3 php -S 127.0.0.1:8102 -t public
```

\== Yii 2

```bash
cd playground/yii2-basic-app && PHP_CLI_SERVER_WORKERS=3 php -S 127.0.0.1:8103 -t public
```

\== Yii 3

```bash
cd playground/yii3-app && ./yii serve --port=8101
```

\== Laravel

```bash
cd playground/laravel-app && PHP_CLI_SERVER_WORKERS=3 php -S 127.0.0.1:8104 -t public
```

:::

::: tip
`PHP_CLI_SERVER_WORKERS=3` is required for SSE — one worker handles the SSE stream, others handle API requests.
:::

## Common URLs

All playgrounds expose the same URL structure:

| Path | Purpose |
|------|---------|
| `/` | Home / demo page |
| `/debug/api/` | Debug entry list (JSON) |
| `/debug/api/view/{id}` | Full debug entry data |
| `/debug/api/summary/{id}` | Entry summary |
| `/inspect/api/*` | Inspector endpoints |
| `/test/fixtures/*` | Test fixture endpoints |

## Integration Methods

Each framework uses a different adapter registration approach:

| Framework | Integration | Registration |
|-----------|------------|--------------|
| Yii 3 | Config plugin | Automatic via `yiisoft/config` |
| Symfony | Bundle | Manual in `config/bundles.php` (dev/test only) |
| Laravel | Package discovery | Automatic via `extra.laravel.providers` |
| Yii 2 | Module + Bootstrap | Auto-bootstrap via `extra.bootstrap` in composer |

### Storage Paths

| Framework | Path | Resolution |
|-----------|------|------------|
| Yii 3 | `runtime/debug/` | `@runtime` alias |
| Symfony | `var/debug/` | `%kernel.project_dir%` |
| Laravel | `storage/debug/` | `storage_path('debug')` |
| Yii2 | `runtime/debug/` | `@runtime` alias |

## Running Test Fixtures

Fixtures are automated test endpoints that exercise each collector:

```bash
make fixtures              # All playgrounds in parallel
make fixtures-yii3         # Yii 3 only
make fixtures-symfony      # Symfony only
make fixtures-yii2         # Yii2 only
make fixtures-laravel      # Laravel only
```

For PHPUnit E2E tests (requires running servers):

```bash
make test-fixtures         # All playgrounds
make test-fixtures-yii3    # Yii 3 only
```

## Adding a New Playground

To add a playground for a new framework:

1. Create `playground/<framework>-app/` with a minimal application using the framework's official skeleton
2. Install ADP packages using path repositories:

```json
{
    "repositories": [
        {"type": "path", "url": "../../libs/Kernel"},
        {"type": "path", "url": "../../libs/API"},
        {"type": "path", "url": "../../libs/Adapter/<Framework>"}
    ],
    "require": {
        "app-dev-panel/adapter-<framework>": "*"
    }
}
```

3. Configure collectors, storage, and API routes per the adapter's documentation
4. Implement `/test/fixtures/*` endpoints matching `FixtureRegistry` (see [Contributing](/guide/contributing))
5. Add Makefile targets for serve, fixtures, and Mago checks
6. Assign the next available port (8105+)

### Port Allocation

| Port | Assignment |
|------|-----------|
| 8100 | Frontend dev server |
| 8101 | Yii 3 |
| 8102 | Symfony |
| 8103 | Yii2 |
| 8104 | Laravel |
| 8105+ | Available |

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/proxies.md'
---

# Proxy System

ADP uses the proxy pattern to intercept PSR interface calls transparently. Proxies wrap standard PSR implementations and feed intercepted data to collectors without modifying application code.

## How It Works

A proxy implements the same PSR interface as the original service. It delegates all calls to the real implementation while recording data for its paired collector.

```
Application Code
       │
       ▼
┌─────────────────┐
│  PSR Interface   │  ← Your code calls this normally
│  (e.g. Logger)   │
└────────┬────────┘
         │
┌────────▼────────┐
│     Proxy        │  ← Intercepts + records
│ (LoggerProxy)    │
└────────┬────────┘
         │
┌────────▼────────┐
│  Real Service    │  ← Original implementation
│ (Monolog, etc.)  │
└────────┬────────┘
         │
┌────────▼────────┐
│   Collector      │  ← Receives recorded data
│ (LogCollector)   │
└─────────────────┘
```

## Built-in Proxies

Kernel provides framework-independent PSR proxies:

| Proxy | PSR Interface | Paired Collector |
|-------|---------------|-----------------|
| AppDevPanel\Kernel\Collector\LoggerInterfaceProxy | PSR-3 Psr\Log\LoggerInterface | AppDevPanel\Kernel\Collector\LogCollector |
| AppDevPanel\Kernel\Collector\EventDispatcherInterfaceProxy | PSR-14 Psr\EventDispatcher\EventDispatcherInterface | AppDevPanel\Kernel\Collector\EventCollector |
| AppDevPanel\Kernel\Collector\HttpClientInterfaceProxy | PSR-18 Psr\Http\Client\ClientInterface | AppDevPanel\Kernel\Collector\HttpClientCollector |

### Framework-Specific Proxies

Framework adapters provide additional proxies for interfaces that are not PSR-standardized:

| Proxy | Framework | Interface | Paired Collector |
|-------|-----------|-----------|-----------------|
| AppDevPanel\Adapter\Symfony\Proxy\SymfonyTranslatorProxy | Symfony | Symfony\Contracts\Translation\TranslatorInterface | AppDevPanel\Kernel\Collector\TranslatorCollector |
| AppDevPanel\Adapter\Symfony\Proxy\SymfonyEventDispatcherProxy | Symfony | Symfony\Contracts\EventDispatcher\EventDispatcherInterface | AppDevPanel\Kernel\Collector\EventCollector |
| AppDevPanel\Adapter\Laravel\Proxy\LaravelTranslatorProxy | Laravel | Illuminate\Contracts\Translation\Translator | AppDevPanel\Kernel\Collector\TranslatorCollector |
| AppDevPanel\Adapter\Laravel\Proxy\LaravelEventDispatcherProxy | Laravel | `Dispatcher` | AppDevPanel\Kernel\Collector\EventCollector |
| AppDevPanel\Adapter\Yii3\Collector\Translator\TranslatorInterfaceProxy | Yii 3 | `TranslatorInterface` | AppDevPanel\Kernel\Collector\TranslatorCollector |
| AppDevPanel\Adapter\Yii3\Collector\Validator\ValidatorInterfaceProxy | Yii 3 | `ValidatorInterface` | AppDevPanel\Kernel\Collector\ValidatorCollector |
| AppDevPanel\Adapter\Yii3\Proxy\ContainerInterfaceProxy | Yii 3 | PSR-11 Psr\Container\ContainerInterface | AppDevPanel\Kernel\Collector\ServiceCollector |
| AppDevPanel\Adapter\Yii2\Proxy\I18NProxy | Yii 2 | `yii\i18n\I18N` | AppDevPanel\Kernel\Collector\TranslatorCollector |

### Translator Proxies

Each framework has its own translator interface. ADP provides a dedicated proxy for each, all feeding the same AppDevPanel\Kernel\Collector\TranslatorCollector. See the [Translator](/guide/translator) page for full details.

**Symfony** -- decorates Symfony\Contracts\Translation\TranslatorInterface via `setDecoratedService()` in the compiler pass. Intercepts `trans()` calls.

**Laravel** -- decorates Illuminate\Contracts\Translation\Translator via `$app->extend('translator')`. Intercepts `get()` and `choice()` calls. Parses Laravel's dot-notation keys (`group.key`) into category and message.

**Yii 3** -- registered in `trackedServices` alongside AppDevPanel\Adapter\Yii3\Collector\Validator\ValidatorInterfaceProxy. Intercepts `translate()` calls. Supports `withDefaultCategory()` and `withLocale()` immutable methods.

**Yii 2** -- extends `yii\i18n\I18N` and overrides `translate()`. Replaces the `i18n` application component during module bootstrap.

::: tip Missing translation detection
All proxies detect missing translations by comparing the translator's return value with the original message ID. If they are identical, the translation is marked as `missing`.
:::

## ProxyDecoratedCalls Trait

The `ProxyDecoratedCalls` trait provides `__call`, `__get`, and `__set` magic methods that delegate to the wrapped service. Proxies use this trait to forward any non-intercepted method calls transparently.

## Proxy Registration

Proxies are registered by framework adapters through DI container configuration. The adapter replaces the original PSR service binding with the proxy, which wraps the original service:

```php
// Simplified adapter DI configuration
LoggerInterface::class => function (ContainerInterface $c) {
    return new LoggerInterfaceProxy(
        $c->get(LogCollector::class),
        $c->get('original.logger'),
    );
},
```

## Key Principles

* **Transparent** -- Application code is unaware of interception
* **Zero overhead when disabled** -- Proxies are only registered when ADP is active
* **PSR-compliant** -- Proxies implement the exact same interface as the original service
* **Colocated** -- Each proxy lives alongside its paired collector in `src/Collector/`

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/queue.md'
---

# Queue Collector

Captures message queue operations — dispatched messages, processing status, failures, and duplicate detection.

![Queue Collector panel](/images/collectors/queue.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `pushes` | Messages pushed to queues, grouped by queue name |
| `statuses` | Message status updates (ID and status) |
| `processingMessages` | Messages currently being processed |
| `messages` | Dispatched/handled messages with metadata |
| `messageCount` | Total message count |
| `failedCount` | Number of failed messages |

## Data Schema

```json
{
    "pushes": {
        "default": [...]
    },
    "statuses": [
        {"id": "msg-1", "status": "handled"}
    ],
    "processingMessages": {},
    "messages": [...],
    "messageCount": 3,
    "failedCount": 0,
    "duplicates": {
        "groups": [],
        "totalDuplicatedCount": 0
    }
}
```

**Summary** (shown in debug entry list):

```json
{
    "queue": {
        "countPushes": 2,
        "countStatuses": 1,
        "countProcessingMessages": 0,
        "messageCount": 3,
        "failedCount": 0,
        "duplicateGroups": 0,
        "totalDuplicatedCount": 0
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\QueueCollector;
use AppDevPanel\Kernel\Collector\MessageRecord;

// Log a dispatched/handled message
$collector->logMessage(new MessageRecord(
    class: 'App\\Message\\SendNotification',
    status: 'dispatched',
    queue: 'default',
    handlerClass: 'App\\Handler\\NotificationHandler',
));

// Or use individual methods
$collector->collectPush(queueName: 'default', message: $message);
$collector->collectStatus(id: 'msg-1', status: 'handled');
```

::: info
\AppDevPanel\Kernel\Collector\QueueCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface, depends on \AppDevPanel\Kernel\Collector\TimelineCollector, and uses \AppDevPanel\Kernel\Collector\DuplicateDetectionTrait.
:::

## How It Works

Framework adapters intercept message bus/queue operations:

* **Symfony**: Messenger middleware and event listeners
* **Laravel**: Queue event listeners (`JobProcessing`, `JobProcessed`, `JobFailed`)
* **Yii 3**: Queue proxy decorator

## Debug Panel

* **Message list** — all dispatched and handled messages with status
* **Queue grouping** — messages grouped by queue name
* **Status badges** — dispatched (blue), handled (green), failed (red)
* **Duplicate detection** — highlights repeated identical messages

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/redis.md'
---

# Redis Collector

The \AppDevPanel\Kernel\Collector\RedisCollector captures all Redis commands executed during a request — SET, GET, DEL, INCR, and any other command — with timing, error tracking, and multi-connection support.

## What It Captures

| Field | Description |
|-------|-------------|
| `connection` | Redis connection name (e.g., `default`, `cache`) |
| `command` | Command name (e.g., `SET`, `GET`, `DEL`) |
| `arguments` | Command arguments array |
| `result` | Return value |
| `duration` | Execution time in seconds |
| `error` | Error message (or `null` on success) |
| `line` | Source file and line (optional) |

## Data Schema

```json
{
    "commands": [
        {
            "connection": "default",
            "command": "SET",
            "arguments": ["user:42", "{\"name\":\"John\"}"],
            "result": true,
            "duration": 0.0012,
            "error": null,
            "line": "/app/src/UserService.php:42"
        }
    ],
    "totalTime": 0.0035,
    "errorCount": 0,
    "totalCommands": 3,
    "connections": ["default", "cache"]
}
```

**Summary** (shown in debug entry list):

```json
{
    "redis": {
        "commandCount": 3,
        "errorCount": 0,
        "totalTime": 0.0035
    }
}
```

## How It Works

The collector is framework-agnostic. It accepts normalized data via `logCommand()`:

```php
use AppDevPanel\Kernel\Collector\RedisCollector;
use AppDevPanel\Kernel\Collector\RedisCommandRecord;

$collector->logCommand(new RedisCommandRecord(
    connection: 'default',
    command: 'SET',
    arguments: ['user:42', '{"name":"John"}'],
    result: true,
    duration: 0.0012,
    error: null,
    line: '/app/src/UserService.php:42',
));
```

::: info
\AppDevPanel\Kernel\Collector\RedisCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface and uses \AppDevPanel\Kernel\Collector\CollectorTrait for the standard lifecycle methods. It depends on \AppDevPanel\Kernel\Collector\TimelineCollector for cross-collector timeline integration.
:::

Framework adapters are responsible for intercepting Redis calls and feeding data to the collector. There is no PSR standard for Redis, so each framework uses its own interception mechanism.

## Framework Integration

### Laravel

Laravel provides `Redis::listen()` out of the box — no decorator needed:

```php
use Illuminate\Redis\Events\CommandExecuted;
use Illuminate\Support\Facades\Redis;

// In your service provider
Redis::enableEvents();
Redis::listen(function (CommandExecuted $event) {
    app(RedisCollector::class)->logCommand(new RedisCommandRecord(
        connection: $event->connectionName,
        command: strtoupper($event->command),
        arguments: $event->parameters,
        result: null,
        duration: $event->time / 1000, // ms → seconds
    ));
});
```

::: tip
Laravel's `CommandExecuted` event does not expose the command result. If you need result tracking, use a phpredis decorator instead.
:::

### Symfony

Two options depending on your Redis client:

::: code-group

```php [Predis Plugin]
use Predis\Command\CommandInterface;
use Predis\Plugin\PluginInterface;

final class RedisCollectorPlugin implements PluginInterface
{
    public function __construct(private RedisCollector $collector) {}

    public function onCommand(CommandInterface $command, callable $next): mixed
    {
        $start = microtime(true);
        $error = null;
        try {
            $result = $next($command);
        } catch (\Throwable $e) {
            $error = $e->getMessage();
            throw $e;
        } finally {
            $this->collector->logCommand(new RedisCommandRecord(
                connection: 'default',
                command: strtoupper($command->getId()),
                arguments: $command->getArguments(),
                result: $result ?? null,
                duration: microtime(true) - $start,
                error: $error,
            ));
        }
        return $result;
    }
}
```

```php [phpredis Decorator]
final class TrackedRedis
{
    public function __construct(
        private \Redis $redis,
        private RedisCollector $collector,
        private string $connection = 'default',
    ) {}

    public function __call(string $method, array $args): mixed
    {
        $start = microtime(true);
        $error = null;
        try {
            $result = $this->redis->$method(...$args);
        } catch (\Throwable $e) {
            $error = $e->getMessage();
            throw $e;
        } finally {
            $this->collector->logCommand(new RedisCommandRecord(
                connection: $this->connection,
                command: strtoupper($method),
                arguments: $args,
                result: $result ?? null,
                duration: microtime(true) - $start,
                error: $error,
            ));
        }
        return $result;
    }
}
```

:::

Register the phpredis decorator in `services.yaml`:

```yaml
App\Redis\TrackedRedis:
    decorates: Redis
    arguments:
        $redis: '@.inner'
        $collector: '@AppDevPanel\Kernel\Collector\RedisCollector'
```

### Yii 3

Register the collector in DI and use the phpredis decorator pattern:

```php
// config/di.php
use AppDevPanel\Kernel\Collector\RedisCollector;
use AppDevPanel\Kernel\Collector\TimelineCollector;
use Yiisoft\Definitions\DynamicReference;

return [
    RedisCollector::class => [
        'class' => RedisCollector::class,
        '__construct()' => [
            DynamicReference::to(TimelineCollector::class),
        ],
    ],
];
```

Add to collectors list in `config/params.php`:

```php
'app-dev-panel' => [
    'collectors' => [
        RedisCollector::class,
    ],
],
```

### Yii 2

If using `yiisoft/yii2-redis`:

```php
use yii\redis\Connection;

Event::on(Connection::class, Connection::EVENT_AFTER_EXECUTE, function ($event) {
    $module = \Yii::$app->getModule('debug-panel');
    $collector = $module->getCollector(RedisCollector::class);
    $collector?->logCommand(new RedisCommandRecord(
        connection: 'default',
        command: strtoupper($event->command),
        arguments: $event->params,
        result: $event->result,
        duration: $event->duration,
    ));
});
```

## Redis Inspector

ADP provides a live Redis inspector at `/inspector/redis`. See the full endpoint reference in [Inspector API](/api/inspector#redis).

**Keys tab** — browse, search, view, and delete Redis keys:

* Pattern-based search (e.g., `user:*`) using Redis SCAN
* Type-aware value display (string, list, set, zset, hash, stream)
* TTL information for each key
* Delete individual keys or flush the entire database

**Server Info tab** — full Redis server information from the `INFO` command.

::: warning
The inspector requires `\Redis` (phpredis extension) registered in the DI container. It does not support Predis for live inspection.
:::

## Debug Panel

The debug panel shows Redis data collected during a request:

* **Summary cards** — total commands, total time, error count, connections
* **Connection breakdown** — per-connection statistics when multiple connections are used
* **Filterable command list** — search by command name, connection, or arguments
* **Expandable details** — arguments, result, error message, source location
* **Color coding** — reads (blue), writes (green), deletes (yellow), errors (red)

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/inspector/redis.md'
---

# Redis Inspector

Browse Redis keys, view values by type, manage keys, and monitor server status.

## Features

| Feature | Description |
|---------|-------------|
| Ping | Test Redis server connection |
| Server info | Full `INFO` output (memory, clients, stats, etc.) |
| DB size | Number of keys in the current database |
| Key browser | Browse keys with pattern matching via `SCAN` |
| Value viewer | Type-aware display (string, list, set, zset, hash, stream) |
| Delete | Remove individual keys |
| Flush DB | Clear all keys in the current database |

## Key Browser

Browse keys using glob patterns (default: `*`). Uses `SCAN` for safe iteration (no blocking). Supports pagination with cursor and limit.

## Type-Aware Value Display

The inspector automatically detects the Redis data type and displays values appropriately:

* **String** — raw value
* **List** — ordered elements
* **Set** — unique members
* **Sorted Set** — members with scores
* **Hash** — field-value pairs
* **Stream** — stream entries

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/inspect/api/redis/ping` | Test connection |
| GET | `/inspect/api/redis/info?section=memory` | Server info (optional section filter) |
| GET | `/inspect/api/redis/db-size` | Key count |
| GET | `/inspect/api/redis/keys?pattern=user:*&limit=100&cursor=0` | Browse keys |
| GET | `/inspect/api/redis/get?key=user:1` | Get value (type-aware) with TTL |
| DELETE | `/inspect/api/redis/delete?key=user:1` | Delete a key |
| POST | `/inspect/api/redis/flush-db` | Flush current database |

## Requirements

Requires the **phpredis** extension (`\Redis` class) registered in the DI container.

::: warning
**Flush DB** is destructive — it removes all keys in the current database. Use with extreme care.
:::

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/request.md'
---

# Request Collector

Captures incoming HTTP request and response details — method, path, headers, query parameters, status code, and raw bodies.

![Request Collector panel](/images/collectors/request.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `requestUrl` | Full request URL |
| `requestPath` | URL path |
| `requestQuery` | Query string |
| `requestMethod` | HTTP method (GET, POST, etc.) |
| `requestIsAjax` | Whether it's an AJAX/XHR request |
| `userIp` | Client IP address |
| `responseStatusCode` | Response HTTP status code |
| `request` | Full PSR-7 ServerRequest object |
| `requestRaw` | Raw HTTP request |
| `response` | Full PSR-7 Response object |
| `responseRaw` | Raw HTTP response |

## Data Schema

```json
{
    "requestUrl": "http://app.local/users?page=2",
    "requestPath": "/users",
    "requestQuery": "page=2",
    "requestMethod": "GET",
    "requestIsAjax": false,
    "userIp": "127.0.0.1",
    "responseStatusCode": 200,
    "requestRaw": "GET /users?page=2 HTTP/1.1\r\nHost: app.local\r\n\r\n",
    "responseRaw": "HTTP/1.1 200 OK\r\nContent-Type: text/html\r\n\r\n..."
}
```

**Summary** (shown in debug entry list):

```json
{
    "request": {
        "url": "http://app.local/users?page=2",
        "path": "/users",
        "query": "page=2",
        "method": "GET",
        "isAjax": false,
        "userIp": "127.0.0.1"
    },
    "response": {
        "statusCode": 200
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\Web\RequestCollector;

$collector->collectRequest(request: $serverRequest);
$collector->collectResponse(response: $response);
```

::: info
\AppDevPanel\Kernel\Collector\Web\RequestCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface and depends on \AppDevPanel\Kernel\Collector\TimelineCollector. Located in the `Web` sub-namespace.
:::

## How It Works

Framework adapters collect the PSR-7 request at the beginning of the middleware pipeline and the response at the end. The collector stores both the parsed objects and raw HTTP representations.

## Debug Panel

* **Request/Response tabs** — switch between request and response views
* **Headers table** — filterable header key-value pairs
* **Raw view** — full HTTP request/response as raw text
* **Parsed view** — structured view of query params, body, cookies
* **Status badge** — color-coded response status (2xx green, 4xx orange, 5xx red)
* **Repeat request** — button to re-send the same request
* **Copy cURL** — copy the request as a cURL command

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/api/rest.md'
---
# REST Endpoints

## Debug API

| Method | Path | Description |
|--------|------|-------------|
| GET | `/debug/api/` | List all debug entries (summaries) |
| GET | `/debug/api/summary/{id}` | Single entry summary |
| GET | `/debug/api/view/{id}` | Full entry data (optionally filtered by collector) |
| GET | `/debug/api/dump/{id}` | Dump objects for entry |
| GET | `/debug/api/object/{id}/{objectId}` | Specific object from dump |

### Example: List entries

```
GET /debug/api/
```

```json
{
    "id": null,
    "data": [
        {
            "id": "abc123",
            "collectors": ["request", "log", "event"],
            "url": "/api/users",
            "method": "GET",
            "status": 200,
            "time": 1234567890
        }
    ],
    "error": null,
    "success": true,
    "status": 200
}
```

### Example: View entry

```
GET /debug/api/view/abc123?collector=log
```

Returns full collected data for the specified entry, optionally filtered to a single collector.

## Ingestion API

| Method | Path | Description |
|--------|------|-------------|
| POST | `/debug/api/ingest/` | Ingest single debug entry |
| POST | `/debug/api/ingest/batch` | Ingest multiple entries |
| POST | `/debug/api/ingest/log` | Shorthand: ingest a single log entry |
| GET | `/debug/api/ingest/openapi.json` | OpenAPI 3.1 specification |

## Service Registry API

| Method | Path | Description |
|--------|------|-------------|
| POST | `/debug/api/services/register` | Register an external service |
| POST | `/debug/api/services/heartbeat` | Keep service online |
| GET | `/debug/api/services/` | List registered services |
| DELETE | `/debug/api/services/{service}` | Deregister a service |

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/roadmap.md'
---

# Roadmap

ADP development follows a phased approach. This page tracks progress and planned work.

## Phase 1: Stabilization & Testing ✅

All critical bugs resolved. Test coverage expanding across modules.

* Decoupled AppDevPanel\Kernel\Debugger from framework-specific events via AppDevPanel\Kernel\StartupContext
* Fixed shutdown registration, socket lifecycle, JSON error handling
* 755+ PHP tests, 328 frontend tests passing

## Phase 2: Security Hardening ✅ (core)

Eliminated critical security vulnerabilities in the API.

* Path traversal protection on file endpoints
* Input validation for class names, git branches, locales, database queries
* Pagination limits on all list endpoints

**Remaining:** Authentication/authorization for inspector, CSRF protection, URL allowlist for request replay.

## Phase 3: Performance Optimization ✅ (core)

* Optimized SSE poll interval (1s → 500ms)
* Reduced backtrace overhead (`IGNORE_ARGS` + depth limit)

**Remaining:** Frontend code splitting, list virtualization for large datasets.

## Phase 4: Architecture Improvements 🔄

Backend improvements (mostly complete):

* Split monolithic AppDevPanel\Api\Inspector\Controller\InspectController into domain-specific controllers
* Replaced global AppDevPanel\Api\Inspector\ApplicationState with proper DI
* Added file locking to AppDevPanel\Kernel\Storage\FileStorage (atomic writes + non-blocking GC)
* Completed namespace migration to `AppDevPanel`

**Remaining backend:** Connection refactoring, CLI configurability, circular dependency guards.

**Remaining frontend:** TypeScript type generation from API, `ErrorBoundary` coverage, shared types package.

## Phase 5: Ecosystem Growth 🔄

Multi-framework support:

| Adapter | Status |
|---------|--------|
| Symfony | ✅ Complete |
| Yii 2 | ✅ Complete |
| Yii 3 | ✅ Complete |
| Laravel | ✅ Complete |

See [Feature Matrix](/guide/feature-matrix) for detailed adapter capabilities.

## Phase 6: Observability & Documentation

* Structured logging for Kernel operations
* OpenAPI spec for the API
* Integration tests with real framework DI containers

## Summary

| Phase | Status | Theme |
|-------|--------|-------|
| 1. Stabilization | ✅ Complete | Make it reliable |
| 2. Security | ✅ Core done | Make it safe |
| 3. Performance | ✅ Core done | Make it fast |
| 4. Architecture | 🔄 In progress | Make it maintainable |
| 5. Ecosystem | 🔄 In progress | Make it universal |
| 6. Observability | Planned | Make it understandable |

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/router.md'
---

# Router Collector

Captures HTTP route matching data — matched route, pattern, arguments, match timing, and the full route tree.

![Router Collector panel](/images/collectors/router.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `currentRoute.name` | Route name (if named) |
| `currentRoute.pattern` | Route URL pattern |
| `currentRoute.arguments` | Matched route parameters |
| `currentRoute.host` | Host constraint (if any) |
| `currentRoute.uri` | Actual matched URI |
| `currentRoute.action` | Controller/action handler |
| `currentRoute.middlewares` | Route-level middleware stack |
| `currentRoute.matchTime` | Time to match the route (seconds) |
| `routes` | Full route table |
| `routesTree` | Route tree structure |

## Data Schema

```json
{
    "currentRoute": {
        "matchTime": 0.00012,
        "name": "user.show",
        "pattern": "/users/{id}",
        "arguments": {"id": "42"},
        "host": null,
        "uri": "/users/42",
        "action": "App\\Controller\\UserController::show",
        "middlewares": ["auth", "throttle"]
    },
    "routes": [...],
    "routesTree": [...],
    "routeTime": 0.00012
}
```

**Summary** (shown in debug entry list):

```json
{
    "router": {
        "matchTime": 0.00012,
        "name": "user.show",
        "pattern": "/users/{id}"
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\RouterCollector;

$collector->collectMatchedRoute([
    'name' => 'user.show',
    'pattern' => '/users/{id}',
    'arguments' => ['id' => '42'],
    'host' => null,
    'uri' => '/users/42',
    'action' => 'App\\Controller\\UserController::show',
    'middlewares' => ['auth', 'throttle'],
]);
$collector->collectMatchTime(matchTime: 0.00012);
$collector->collectRoutes(routes: $allRoutes, routesTree: $routeTree);
```

::: info
\AppDevPanel\Kernel\Collector\RouterCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface. It has no dependencies on other collectors.
:::

## How It Works

Each framework adapter has a `RouterDataExtractor` that normalizes framework-specific route data into the common format:

* **Symfony**: Extracts from `RouterInterface` and request attributes
* **Laravel**: Extracts from Illuminate\Routing\Router facade and matched `Route` object
* **Yii 3**: Extracts from Symfony\Component\Routing\Matcher\UrlMatcherInterface result

## Debug Panel

* **Matched route** — current route pattern, name, and matched parameters
* **Route arguments** — key-value pairs of resolved parameters
* **Action handler** — controller class and method
* **Match timing** — how long route matching took

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/inspector/routes.md'
---

# Routes Inspector

Browse and test all registered HTTP routes in your application.

![Routes Inspector](/images/inspector/routes.png)

## What It Shows

| Field | Description |
|-------|-------------|
| Name | Route name (e.g., `app_users_index`) |
| Pattern | URL pattern with placeholders (e.g., `/api/users/{id}`) |
| Methods | Allowed HTTP methods (GET, POST, etc.) |
| Middlewares | Controller/action or middleware stack handling the route |

## Route Testing

Test whether a URL matches any registered route directly in the panel. Enter a path like `GET /api/users/42` and see:

* Whether it matches a route
* Which controller/action handles it

Supports inline HTTP method specification: `POST /api/users` (defaults to GET if omitted).

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/inspect/api/routes` | List all registered routes |
| GET | `/inspect/api/route/check?route=GET /path` | Test if a path matches a route |

## Adapter Support

| Adapter | Supported |
|---------|-----------|
| Symfony | Yes (via AppDevPanel\Adapter\Symfony\Inspector\SymfonyRouteCollectionAdapter) |
| Laravel | Yes |
| Yii 3 | Yes |
| Yii 2 | Yes |

::: tip
Routes include middleware definitions where available, so you can see the full request pipeline for each endpoint.
:::

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/screenshots.md'
---

# Screenshots

ADP supports taking screenshots of the frontend panel using [Playwright](https://playwright.dev/). This is useful for visual verification during development, debugging UI issues, and generating documentation assets.

## Prerequisites

| Tool | Purpose | Install |
|------|---------|---------|
| **Playwright** | Browser automation | `npm install -g playwright` |
| **Chromium** | Headless browser | Bundled with Playwright (`npx playwright install chromium`) |

::: tip Why Playwright, not Selenium?
Selenium requires ChromeDriver to match the installed Chromium version exactly. Playwright bundles its own browser — no version conflicts. Use Selenium only for [E2E test suites](/guide/ci-and-tooling#frontend-checks).
:::

## Quick Screenshot (CLI)

One command, no script needed:

```bash
npx playwright screenshot \
  --browser chromium \
  --wait-for-timeout 5000 \
  --full-page \
  --viewport-size "1920,1080" \
  http://localhost:5173/ /tmp/screenshot.png
```

## Full Screenshot (Node.js)

For React SPAs, use a script to wait for rendering:

```js
const { chromium } = require('playwright');

(async () => {
    const browser = await chromium.launch({ headless: true });
    const page = await browser.newPage({
        viewport: { width: 1920, height: 1080 },
    });

    await page.goto('http://localhost:5173/', { waitUntil: 'networkidle' });
    await page.waitForTimeout(3000);

    await page.screenshot({ path: '/tmp/screenshot.png', fullPage: true });
    await browser.close();
})();
```

::: info NODE\_PATH
If Playwright is installed globally (e.g. at `/opt/node22/lib/node_modules`), prefix the command:

```bash
NODE_PATH=/opt/node22/lib/node_modules node screenshot.js
```

:::

## Starting the Dev Server

Before taking screenshots, start the frontend:

```bash
cd libs/frontend/packages/panel
npx vite --host 0.0.0.0 --port 5173 &

# Wait for server
sleep 5
curl -s -o /dev/null -w "%{http_code}" http://localhost:5173/
# Should return 200
```

## Advanced Scenarios

### Wait for a Specific Element

```js
await page.goto('http://localhost:5173/debug');
await page.waitForSelector('.MuiDataGrid-root', { timeout: 10000 });
await page.screenshot({ path: '/tmp/debug-grid.png' });
```

### Screenshot a Single Element

```js
const card = await page.locator('.MuiCard-root').first();
await card.screenshot({ path: '/tmp/card.png' });
```

### Multiple Pages

```js
const pages = ['/', '/debug', '/inspector/config', '/inspector/routes'];
for (const path of pages) {
    await page.goto(`http://localhost:5173${path}`, { waitUntil: 'networkidle' });
    await page.waitForTimeout(2000);
    const name = path === '/' ? 'home' : path.replace(/\//g, '-').slice(1);
    await page.screenshot({ path: `/tmp/screenshot-${name}.png`, fullPage: true });
}
```

### Dark Mode

```js
await page.emulateMedia({ colorScheme: 'dark' });
await page.goto('http://localhost:5173/', { waitUntil: 'networkidle' });
await page.waitForTimeout(3000);
await page.screenshot({ path: '/tmp/dark-mode.png', fullPage: true });
```

### Mobile Viewport

```js
const page = await browser.newPage({
    viewport: { width: 390, height: 844 },
    deviceScaleFactor: 3,
});
```

## Claude Code Integration

Claude Code can take and analyze screenshots using the `/screenshot` skill:

```
/screenshot http://localhost:5173/
```

This launches Playwright, captures the page, and displays the image directly in the conversation. Claude Code can then analyze the UI, identify issues, or compare it against design specs.

### Workflow

1. Start the frontend dev server
2. Use `/screenshot [URL or path]` to capture
3. Claude Code reads and analyzes the image via the `Read` tool
4. Iterate: fix UI issues, re-screenshot, verify

## Troubleshooting

| Problem | Cause | Solution |
|---------|-------|----------|
| White/blank screenshot | React hasn't rendered | Add `waitForTimeout(3000)` or `waitForSelector()` |
| `MODULE_NOT_FOUND: playwright` | Playwright not in NODE\_PATH | Set `NODE_PATH=/path/to/node_modules` |
| `ERR_CONNECTION_REFUSED` in console | Backend API not running | Expected — frontend UI still renders without backend |
| `Session not created` (Selenium) | ChromeDriver/Chromium version mismatch | Use Playwright instead |

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/security.md'
---

# Security & Authorization

ADP captures authentication and authorization data from your application: user identity, roles, tokens, login/logout events, access decisions, and impersonation. The inspector also provides a live view of your security configuration.

## AuthorizationCollector

AppDevPanel\Kernel\Collector\AuthorizationCollector captures runtime security data. It implements AppDevPanel\Kernel\Collector\SummaryCollectorInterface for summary display in the debug entry list.

### Collected Data

| Field | Type | Description |
|-------|------|-------------|
| `username` | `?string` | Authenticated user identifier |
| `roles` | `string[]` | Assigned roles |
| `effectiveRoles` | `string[]` | Resolved roles (from hierarchy) |
| `firewallName` | `?string` | Active firewall/guard name |
| `authenticated` | `bool` | Whether the user is authenticated |
| `token` | `?{type, attributes, expiresAt}` | Auth token info (JWT, session, API key) |
| `impersonation` | `?{originalUser, impersonatedUser}` | User switching data |
| `guards` | `array` | Guard/firewall configurations |
| `roleHierarchy` | `array<string, string[]>` | Role inheritance map |
| `authenticationEvents` | `array` | Login, logout, failure events with timing |
| `accessDecisions` | `array` | Authorization checks with voters and results |

### Collection Methods

```php
$collector->collectUser('admin@example.com', ['ROLE_ADMIN'], true);
$collector->collectFirewall('main');
$collector->collectToken('jwt', ['sub' => '123'], '2026-12-31T23:59:59Z');
$collector->collectImpersonation('admin', 'user@example.com');
$collector->collectGuard('web', 'users', ['driver' => 'session']);
$collector->collectRoleHierarchy(['ROLE_ADMIN' => ['ROLE_USER', 'ROLE_EDITOR']]);
$collector->collectEffectiveRoles(['ROLE_ADMIN', 'ROLE_USER', 'ROLE_EDITOR']);
$collector->collectAuthenticationEvent('login', 'form_login', 'success', ['ip' => '127.0.0.1']);
$collector->logAccessDecision('EDIT', 'App\\Entity\\Post', 'ACCESS_DENIED', $voters, 0.002, ['route' => '/admin']);
```

## Adapter Wiring

Each adapter automatically feeds AppDevPanel\Kernel\Collector\AuthorizationCollector from the framework's native auth system.

### Symfony

AppDevPanel\Adapter\Symfony\EventSubscriber\AuthorizationSubscriber listens to Symfony Security events. Requires symfony/security-http.

| Event | Data Captured |
|-------|---------------|
| Symfony\Component\Security\Http\Event\LoginSuccessEvent | User identity, roles, firewall, token type, impersonation |
| Symfony\Component\Security\Http\Event\LoginFailureEvent | Failed auth event with exception details |
| Symfony\Component\Security\Http\Event\LogoutEvent | Logout event |
| Symfony\Component\Security\Http\Event\SwitchUserEvent | Impersonation data |
| Symfony\Component\Security\Core\Event\VoteEvent | Access decisions with voter results |

::: tip
Enable in `config/packages/app_dev_panel.yaml`:

```yaml
app_dev_panel:
    collectors:
        security: true
```

:::

### Laravel

AppDevPanel\Adapter\Laravel\EventListener\AuthorizationListener listens to Laravel Auth events.

| Event | Data Captured |
|-------|---------------|
| Illuminate\Auth\Events\Authenticated | User identity, guard name |
| Illuminate\Auth\Events\Login | Login event, remember flag |
| Illuminate\Auth\Events\Logout | Logout event |
| Illuminate\Auth\Events\Failed | Failed auth with credential keys |
| Illuminate\Auth\Events\OtherDeviceLogout | Other device logout |

### Yii 2

AppDevPanel\Adapter\Yii2\EventListener\AuthorizationListener hooks into yii\web\User events.

| Event | Data Captured |
|-------|---------------|
| `User::EVENT_AFTER_LOGIN` | User ID, duration, cookie-based flag |
| `User::EVENT_AFTER_LOGOUT` | Logout event with user ID |
| `Application::EVENT_BEFORE_REQUEST` | Current session user on each request |

### Yii 3

AppDevPanel\Kernel\Collector\AuthorizationCollector is registered in DI but requires manual calls — Yii 3 has no standardized auth event system.

## Authorization Inspector

The inspector provides a live view of security configuration via `GET /inspect/api/authorization`.

### Response

```json
{
  "guards": [
    {"name": "web", "provider": "users", "config": {"driver": "session"}}
  ],
  "roleHierarchy": {
    "ROLE_ADMIN": ["ROLE_USER", "ROLE_EDITOR"]
  },
  "voters": [
    {"name": "RoleVoter", "type": "voter", "priority": 255}
  ],
  "config": {
    "access_decision_manager": {"strategy": "affirmative"}
  }
}
```

Adapters implement `AuthorizationConfigProviderInterface` to supply this data. Default: AppDevPanel\Api\Inspector\Authorization\NullAuthorizationConfigProvider (empty arrays).

## Frontend

### AuthorizationPanel (Debug)

Displays per-request security data in the debug view:

* User identity card (username, status, firewall, roles, effective roles, token)
* Impersonation banner (when active)
* Authentication events timeline (login, logout, failure)
* Access decisions table (expandable, shows voters and context)

### AuthorizationPage (Inspector)

Located at `/inspector/authorization`. Displays live security configuration:

* Guards table (name, provider, config)
* Role hierarchy tree (role → inherited roles)
* Voters/policies table (name, type, priority)
* Security configuration JSON

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/service.md'
---

# Service Collector

Captures DI container service method calls — invoked service, method, arguments, result, and timing.

![Service Collector panel](/images/collectors/service.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `service` | Service identifier |
| `class` | Service class name |
| `method` | Method called |
| `arguments` | Method arguments |
| `result` | Return value |
| `status` | Call status (`success` or `error`) |
| `error` | Error message if failed |
| `timeStart` | Call start time |
| `timeEnd` | Call end time |

## Data Schema

```json
[
    {
        "service": "App\\Service\\UserService",
        "class": "App\\Service\\UserService",
        "method": "findById",
        "arguments": [42],
        "result": {"id": 42, "name": "John"},
        "status": "success",
        "error": null,
        "timeStart": 1711878000.100,
        "timeEnd": 1711878000.105
    }
]
```

**Summary** (shown in debug entry list):

```json
{
    "service": {
        "total": 5
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\ServiceCollector;
use AppDevPanel\Kernel\Event\MethodCallRecord;

$collector->collect(new MethodCallRecord(
    service: 'App\\Service\\UserService',
    class: 'App\\Service\\UserService',
    method: 'findById',
    arguments: [42],
    result: $result,
    status: 'success',
    timeStart: $start,
    timeEnd: $end,
));
```

::: info
\AppDevPanel\Kernel\Collector\ServiceCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface and depends on \AppDevPanel\Kernel\Collector\TimelineCollector.
:::

## How It Works

The collector is fed by \AppDevPanel\Adapter\Yii3\Proxy\ContainerInterfaceProxy which wraps the PSR-11 Psr\Container\ContainerInterface. When services are resolved and their methods are called through the proxy, the calls are intercepted and recorded.

## Debug Panel

* **Service call list** — all tracked method calls with class, method, and timing
* **Expandable details** — arguments and return values
* **Status indicators** — success (green) and error (red) badges

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/sponsor.md'
---

# Sponsor ADP

ADP is an open-source project maintained in spare time. Your sponsorship helps cover infrastructure costs, fund new features, and keep the project actively developed.

## Why Sponsor?

* **Sustainability** — Regular contributions ensure long-term maintenance and timely updates
* **Feature development** — Sponsors directly fund new collectors, adapters, and UI improvements
* **Priority support** — Sponsors get faster responses to issues and feature requests
* **Community growth** — Your support helps build a stronger ecosystem around ADP

## How to Support

### Recurring

### Crypto

## Company Sponsorship

Want your company logo on the ADP homepage and documentation? Company sponsorships start at **$500/month** and include:

* Logo placement on the homepage and documentation footer
* Link to your website from all pages
* Mention in release announcements
* Priority feature requests

Contact **xepozzd@gmail.com** for details.

## Current Sponsors

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/api/sse.md'
---
# SSE (Server-Sent Events)

The SSE endpoint provides real-time push notifications when new debug entries are written to storage.

## Endpoint

```
GET /debug/api/event-stream
```

## How It Works

The server polls storage every second, computing an MD5 hash of the summary data. When a new debug entry is written, the hash changes and an event is emitted to all connected clients.

## Event Format

```
data: {"type": "debug-updated", "payload": []}
```

| Field | Description |
|-------|-------------|
| `type` | Always `debug-updated` |
| `payload` | Reserved for future use (currently empty array) |

## Client Usage

```javascript
const source = new EventSource('/debug/api/event-stream');

source.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.type === 'debug-updated') {
        // Refresh debug entry list
    }
};
```

## Notes

* The SSE stream bypasses AppDevPanel\Api\Debug\Middleware\ResponseDataWrapper -- it uses the native SSE text/event-stream format, not the JSON envelope.
* The connection remains open until the client disconnects.
* IP filtering applies -- only allowed IPs can connect (default: `127.0.0.1`, `::1`).

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/storage.md'
---

# Storage

ADP persists debug data through a AppDevPanel\Kernel\Storage\StorageInterface abstraction. The default implementation, AppDevPanel\Kernel\Storage\FileStorage, writes JSON files to disk.

## StorageInterface

```php
interface StorageInterface
{
    public function addCollector(CollectorInterface $collector): void;
    public function getData(): array;
    public function read(string $type, ?string $id = null): array;
    public function write(string $id, array $summary, array $data, array $objects): void;
    public function flush(): void;
    public function clear(): void;
}
```

### Data Types

Each debug entry is stored as three separate pieces:

| Type | Constant | Contents |
|------|----------|----------|
| Summary | `TYPE_SUMMARY` | Timestamp, URL, HTTP status, collector names |
| Data | `TYPE_DATA` | Full collector payloads |
| Objects | `TYPE_OBJECTS` | Serialized PHP objects for deep inspection |

This separation allows the frontend to load summaries quickly without fetching full data.

## FileStorage

AppDevPanel\Kernel\Storage\FileStorage is the default production implementation. It writes JSON files to a configurable directory.

**Key behaviors:**

* Each debug entry produces three JSON files (summary, data, objects)
* Uses `LOCK_EX` for atomic writes to prevent corruption
* Uses `flock` for garbage collection mutual exclusion
* Supports configurable entry limit with automatic GC of old entries

### Directory Structure

```
debug-data/
├── 000001.summary.json
├── 000001.data.json
├── 000001.objects.json
├── 000002.summary.json
├── 000002.data.json
├── 000002.objects.json
└── ...
```

## MemoryStorage

AppDevPanel\Kernel\Storage\MemoryStorage is an in-memory implementation used exclusively for testing. It stores all data in PHP arrays with no disk I/O.

## Write Sources

Storage receives data from two sources:

1. **Debugger flush** -- After a request or console command completes, the AppDevPanel\Kernel\Debugger calls `flush()` on the storage, which serializes all collector data.
2. **Ingestion API** -- The AppDevPanel\Api\Ingestion\Controller\IngestionController calls `write()` directly, allowing external (non-PHP) applications to send debug data via HTTP.

## Extending Storage

To create a custom storage backend (e.g., Redis, database), implement AppDevPanel\Kernel\Storage\StorageInterface and register it in your DI container. All six methods must be implemented. The `read()` method must support filtering by `$type` and optionally by `$id`.

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/adapters/symfony.md'
---
# Symfony Adapter

The Symfony adapter bridges ADP Kernel and API into Symfony 6.4+ / 7.x / 8.x via a Symfony Bundle.

## Installation

```bash
composer require app-dev-panel/adapter-symfony
```

::: info Package
app-dev-panel/adapter-symfony
:::

## Bundle Registration

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

```php
return [
    // ...
    AppDevPanel\Adapter\Symfony\AppDevPanelBundle::class => ['dev' => true, 'test' => true],
];
```

## Configuration

Create `config/packages/app_dev_panel.yaml`:

```yaml
app_dev_panel:
    enabled: true
    storage:
        path: '%kernel.project_dir%/var/debug'
        history_size: 50
    collectors:
        request: true
        exception: true
        log: true
        event: true
        doctrine: true        # requires doctrine/dbal
        twig: true             # requires twig/twig
        security: true         # requires symfony/security-bundle
        cache: true
        mailer: true           # requires symfony/mailer
        messenger: true        # requires symfony/messenger
        code_coverage: false   # opt-in; requires pcov or xdebug
    ignored_requests:
        - '/_wdt/*'
        - '/_profiler/*'
        - '/debug/api/**'
    api:
        enabled: true
        allowed_ips: ['127.0.0.1', '::1']
```

## Collectors

Supports all Kernel collectors plus Symfony-specific ones: Twig templates, Security (user/roles/firewall), Cache, Messenger, Translator, Doctrine database queries, and [Redis commands](/guide/collectors/redis) (via Predis plugin or phpredis decorator).

## Translator Integration

The adapter automatically decorates Symfony's Symfony\Contracts\Translation\TranslatorInterface with AppDevPanel\Adapter\Symfony\Proxy\SymfonyTranslatorProxy via the compiler pass. All `trans()` calls are intercepted and logged to AppDevPanel\Kernel\Collector\TranslatorCollector — no code changes needed. See [Translator](/guide/translator) for details.

## Database Inspector

When `doctrine/dbal` is available, AppDevPanel\Adapter\Symfony\Inspector\DoctrineSchemaProvider provides database schema inspection. Falls back to AppDevPanel\Adapter\Symfony\Inspector\NullSchemaProvider otherwise.

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/template.md'
---

# Template Collector

Captures template/view rendering with optional timing, output capture, parameters, and duplicate detection. Works with any template engine (Twig, Blade, PHP templates, etc.).

## What It Captures

| Field | Description |
|-------|-------------|
| `template` | Template file path or name |
| `renderTime` | Rendering duration in seconds (optional, 0 if not measured) |
| `output` | Rendered output HTML (optional, empty if not captured) |
| `parameters` | Parameters passed to the template (optional) |

## Data Schema

```json
{
    "renders": [
        {
            "template": "home/index.html.twig",
            "renderTime": 0.0045,
            "output": "",
            "parameters": []
        },
        {
            "template": "/app/views/user/profile.php",
            "renderTime": 0,
            "output": "<div class=\"profile\">...</div>",
            "parameters": {"user": "object@App\\Entity\\User#42"}
        }
    ],
    "totalTime": 0.0045,
    "renderCount": 2,
    "duplicates": {
        "groups": [],
        "totalDuplicatedCount": 0
    }
}
```

**Summary** (shown in debug entry list):

```json
{
    "template": {
        "renderCount": 2,
        "totalTime": 0.0045,
        "duplicateGroups": 0,
        "totalDuplicatedCount": 0
    }
}
```

## Contract

Two entry points depending on available data:

```php
use AppDevPanel\Kernel\Collector\TemplateCollector;

// Template engines with timing (Twig, Blade)
$collector->logRender(
    template: 'home/index.html.twig',
    renderTime: 0.0045,
);

// View systems with output capture (Yii views, PHP templates)
$collector->collectRender(
    template: '/app/views/user/profile.php',
    output: '<div class="profile">...</div>',
    parameters: ['user' => $userObject],
    renderTime: 0.003, // optional
);
```

::: info
\AppDevPanel\Kernel\Collector\TemplateCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface, depends on \AppDevPanel\Kernel\Collector\TimelineCollector, and uses \AppDevPanel\Kernel\Collector\DuplicateDetectionTrait.
:::

## How It Works

Framework adapters hook into the template/view rendering system:

* **Symfony**: Twig profiler extension measures render time, calls `logRender()`
* **Yii 3**: \AppDevPanel\Adapter\Yii3\Collector\View\ViewEventListener listens to view render events, calls `collectRender()`
* **Yii 2**: `View::EVENT_BEFORE_RENDER` + `EVENT_AFTER_RENDER` with per-file timer stack — captures timing, output, and parameters in one call

## Debug Panel

* **Summary cards** — total templates rendered, aggregate render time (when timing available)
* **Template list** — all rendered templates with file paths and render time
* **Output preview** — rendered HTML output (expandable, when captured)
* **Parameters** — expandable view parameters (when captured)
* **Duplicate detection** — highlights repeated renders of the same template (N+1 issues)
* **Flat / Grouped views** — toggle between all renders and grouped duplicates

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/timeline.md'
---

# Timeline Collector

Captures cross-collector performance timeline — a unified view of all events from all collectors in chronological order.

![Timeline Collector panel](/images/collectors/timeline.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `time` | Event timestamp |
| `reference` | Reference ID linking back to the source collector's data entry |
| `collector` | Source collector class name |
| `data` | Additional event data (varies by collector) |

## Data Schema

Timeline events are stored as arrays:

```json
[
    [1711878000.100, 0, "AppDevPanel\\Kernel\\Collector\\Web\\RequestCollector", []],
    [1711878000.105, 0, "AppDevPanel\\Kernel\\Collector\\LogCollector", ["level", "info"]],
    [1711878000.150, 0, "AppDevPanel\\Kernel\\Collector\\EventCollector", []],
    [1711878000.200, 1, "AppDevPanel\\Kernel\\Collector\\LogCollector", ["level", "warning"]]
]
```

**Summary** (shown in debug entry list):

```json
{
    "timeline": {
        "total": 15
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\TimelineCollector;

// Called by other collectors to register timeline events
$timeline->collect(
    collector: $logCollector,
    reference: 0,           // Index in the source collector's data
    'level', 'info',        // Additional context data
);
```

::: info
\AppDevPanel\Kernel\Collector\TimelineCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface. Most other collectors depend on \AppDevPanel\Kernel\Collector\TimelineCollector to register their events on the timeline.
:::

## How It Works

The \AppDevPanel\Kernel\Collector\TimelineCollector is a central aggregation point. Other collectors (Log, Event, Database, etc.) call `$timeline->collect()` when they record an event, passing themselves as the source. This creates a unified chronological view across all collectors.

## Debug Panel

* **Visual timeline** — horizontal bar chart showing events across time
* **Collector filtering** — toggle visibility of specific collectors via chips
* **Color coding** — each collector type has a distinct color
* **Time scale** — auto-scaling time axis with microsecond precision
* **Event count** — total timeline events in sidebar badge

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/inspector/translations.md'
---

# Translations Inspector

Browse and edit translation catalogs across all locales.

## Features

| Feature | Description |
|---------|-------------|
| Catalog browser | View all translation catalogs and their messages |
| Locale comparison | Compare translations across locales |
| Live editing | Update translation messages directly from the panel |

## How It Works

The inspector reads all registered translation category sources and displays messages organized by catalog and locale. You can browse messages, search for specific keys, and edit translations in place.

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/inspect/api/translations` | All catalogs and messages for all locales |
| PUT | `/inspect/api/translations` | Update a translation message |

**Update request body:**

```json
{
    "catalog": "messages",
    "locale": "en",
    "key": "welcome.title",
    "value": "Welcome to our app"
}
```

## Adapter Support

Requires framework-specific translation integration (e.g., Symfony Translator, Laravel Lang). Returns 501 if translations are not available.

::: tip
Changes made via the Translations Inspector update the application's translation source directly. This is useful for quick fixes during development.
:::

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/translator.md'
---

# Translator

ADP automatically intercepts translation calls in your application and records every lookup — including missing translations. No code changes required.

## TranslatorCollector

AppDevPanel\Kernel\Collector\TranslatorCollector implements AppDevPanel\Kernel\Collector\SummaryCollectorInterface and captures every translation lookup during request execution.

### TranslationRecord

Each translation call produces a AppDevPanel\Kernel\Collector\TranslationRecord DTO:

| Field | Type | Description |
|-------|------|-------------|
| `category` | `string` | Translation domain/group (e.g., `messages`, `app`, `validation`) |
| `locale` | `string` | Target locale (e.g., `en`, `de`, `fr`) |
| `message` | `string` | Original message ID / translation key |
| `translation` | `?string` | Translated string, or `null` if missing |
| `missing` | `bool` | `true` when no translation was found |
| `fallbackLocale` | `?string` | Fallback locale used (if applicable) |

### Collected Data

`getCollected()` returns:

```php
[
    'translations' => [
        ['category' => 'messages', 'locale' => 'de', 'message' => 'welcome', 'translation' => 'Willkommen!', 'missing' => false, 'fallbackLocale' => null],
        ['category' => 'messages', 'locale' => 'de', 'message' => 'goodbye', 'translation' => null, 'missing' => true, 'fallbackLocale' => null],
    ],
    'missingCount' => 1,
    'totalCount' => 2,
    'locales' => ['de'],
    'categories' => ['messages'],
]
```

### Summary

`getSummary()` returns:

```php
[
    'translator' => [
        'total' => 2,
        'missing' => 1,
    ],
]
```

## Missing Translation Detection

Each framework proxy detects missing translations differently, but the logic is consistent: if the translator returns the original message ID unchanged, the translation is considered missing.

| Framework | Detection Method |
|-----------|-----------------|
| Symfony | `trans()` returns `$id` unchanged |
| Laravel | `get()` returns `$key` unchanged |
| Yii 3 | `translate()` returns `$id` unchanged |
| Yii 2 | `MessageSource::translate()` returns `false` |

## Framework Proxies

Each adapter provides a translator proxy that wraps the framework's native translator and feeds data to AppDevPanel\Kernel\Collector\TranslatorCollector. Proxies are registered automatically — no manual setup needed.

### Symfony — AppDevPanel\Adapter\Symfony\Proxy\SymfonyTranslatorProxy

Decorates `Symfony\Contracts\Translation\TranslatorInterface`. Intercepts `trans()` calls.

**Wiring:** Registered via AppDevPanel\Adapter\Symfony\DependencyInjection\CollectorProxyCompilerPass using Symfony's `setDecoratedService()` pattern.

```php
// All trans() calls are intercepted automatically
$translator->trans('welcome', [], 'messages', 'de');
```

* Default domain: `messages` (when `$domain` is `null`)
* Uses `ProxyDecoratedCalls` trait for method forwarding

### Laravel — AppDevPanel\Adapter\Laravel\Proxy\LaravelTranslatorProxy

Decorates `Illuminate\Contracts\Translation\Translator`. Intercepts `get()` and `choice()` calls.

**Wiring:** Registered via `$app->extend('translator', ...)` in the service provider.

```php
// All translation helpers are intercepted
__('messages.welcome');
trans('messages.welcome');
Lang::get('messages.welcome');
```

* Parses Laravel's dot-notation keys: `group.key` → category `group`, message `key`
* JSON translations (no dot): category defaults to `messages`
* Uses `ProxyDecoratedCalls` trait for method forwarding

### Yii 3 — AppDevPanel\Adapter\Yii3\Collector\Translator\TranslatorInterfaceProxy

Decorates `Yiisoft\Translator\TranslatorInterface`. Intercepts `translate()` calls.

**Wiring:** Registered as a `trackedService` in `params.php` — the adapter's service proxy system handles decoration automatically.

```php
// All translate() calls are intercepted
$translator->translate('welcome', [], 'app', 'de');
```

* Default category: `app` (when `$category` is `null` and no `withDefaultCategory()` was called)
* Supports immutable `withDefaultCategory()` and `withLocale()` via `clone`

### Yii 2 — AppDevPanel\Adapter\Yii2\Proxy\I18NProxy

Extends `yii\i18n\I18N` and overrides `translate()`. Replaces the `i18n` application component.

**Wiring:** The module replaces `Yii::$app->i18n` with the proxy instance, copying existing translations config.

```php
// All Yii::t() calls are intercepted
Yii::t('app', 'welcome', [], 'de');
```

* Calls `$messageSource->translate()` directly — returns `false` when missing (more reliable than string comparison)
* Safe to use without collector (null-safe `$this->collector?->logTranslation()`)

## Configuration

Translation interception is enabled by default when the AppDevPanel\Kernel\Collector\TranslatorCollector is active. No additional configuration is needed.

:::tabs key:framework
\== Symfony

```yaml
# config/packages/app_dev_panel.yaml
app_dev_panel:
    collectors:
        translator: true    # enabled by default
```

\== Yii 2

```php
// application config
'modules' => [
    'debug-panel' => [
        'collectors' => [
            'translator' => true,   // enabled by default
        ],
    ],
],
```

\== Yii 3

```php
// config/params.php
'app-dev-panel/yii3' => [
    'collectors' => [
        TranslatorCollector::class => true,  // enabled by default
    ],
    'trackedServices' => [
        TranslatorInterface::class => [TranslatorInterfaceProxy::class, TranslatorCollector::class],
    ],
],
```

\== Laravel

```php
// config/app-dev-panel.php
'collectors' => [
    'translator' => true,   // enabled by default
],
```

:::

## Frontend Panel

The TranslatorPanel in the debug UI displays:

* **Summary badge** — total translation count and missing count
* **Translation table** — all recorded translations with category, locale, message, translated value, and missing status
* **Filters** — filter by locale, category, or missing status
* **Missing highlights** — missing translations are visually highlighted for quick identification

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/translator.md'
---

# Translator Collector

Captures translation lookups during request execution — resolved translations, missing keys, locale usage, and categories.

![Translator Collector panel](/images/collectors/translator.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `category` | Translation category/domain |
| `locale` | Target locale |
| `message` | Translation key |
| `translation` | Resolved translation (or `null` if missing) |
| `missing` | Whether the translation was not found |
| `fallbackLocale` | Fallback locale used (if any) |

## Data Schema

```json
{
    "translations": [
        {
            "category": "messages",
            "locale": "en",
            "message": "welcome.title",
            "translation": "Welcome to App",
            "missing": false,
            "fallbackLocale": null
        },
        {
            "category": "messages",
            "locale": "fr",
            "message": "missing.key",
            "translation": null,
            "missing": true,
            "fallbackLocale": "en"
        }
    ],
    "missingCount": 1,
    "totalCount": 2,
    "locales": ["en", "fr"],
    "categories": ["messages"]
}
```

**Summary** (shown in debug entry list):

```json
{
    "translator": {
        "total": 2,
        "missing": 1
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\TranslatorCollector;
use AppDevPanel\Kernel\Collector\TranslationRecord;

$collector->logTranslation(new TranslationRecord(
    category: 'messages',
    locale: 'en',
    message: 'welcome.title',
    translation: 'Welcome to App',
    missing: false,
));
```

::: info
\AppDevPanel\Kernel\Collector\TranslatorCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface. It has no dependencies on other collectors.
:::

## How It Works

The collector is fed by the `TranslatorProxy` which intercepts calls to the translator service. Each `trans()` / `translate()` call is recorded with its result.

See the dedicated [Translator](/guide/translator) page for detailed integration examples per framework.

## Debug Panel

* **Translation list** — all lookups with key, resolved value, and locale
* **Missing detection** — missing translations highlighted in red
* **Locale breakdown** — translations grouped by locale
* **Category filtering** — filter by translation domain/category

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/validator.md'
---

# Validator Collector

Captures validation operations with rules, results, and error lists.

![Validator Collector panel](/images/collectors/validator.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `value` | The validated value |
| `rules` | Validation rules applied |
| `result` | Whether validation passed (`true`/`false`) |
| `errors` | Validation error messages |

## Data Schema

```json
[
    {
        "value": {"email": "invalid"},
        "rules": "email|required",
        "result": false,
        "errors": ["The email field must be a valid email address."]
    },
    {
        "value": {"name": "John"},
        "rules": "string|min:2",
        "result": true,
        "errors": []
    }
]
```

**Summary** (shown in debug entry list):

```json
{
    "validator": {
        "total": 2,
        "valid": 1,
        "invalid": 1
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\ValidatorCollector;

$collector->collect(
    value: ['email' => 'invalid'],
    isValid: false,
    errors: ['The email field must be a valid email address.'],
    rules: 'email|required',
);
```

::: info
\AppDevPanel\Kernel\Collector\ValidatorCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface. It has no dependencies on other collectors.
:::

## How It Works

Framework adapters intercept validation calls:

* **Symfony**: Validator event listener
* **Laravel**: Validator hook after validation
* **Yii 3**: Validator proxy decorator

## Debug Panel

* **Validation list** — all validations with pass/fail status
* **Status badges** — valid (green), invalid (red)
* **Error details** — expandable error messages per validation
* **Rule display** — validation rules shown for each operation

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/var-dumper.md'
---

# VarDumper Collector

Captures manual variable dumps (`dump()` / `dd()` calls) with source file and line information.

![VarDumper Collector panel](/images/collectors/var-dumper.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `variable` | The dumped variable value |
| `line` | Source file and line of the dump call |

## Data Schema

```json
[
    {
        "variable": {"key": "value", "nested": [1, 2, 3]},
        "line": "/app/src/Controller.php:42"
    }
]
```

**Summary** (shown in debug entry list):

```json
{
    "var-dumper": {
        "total": 2
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\VarDumperCollector;

$collector->collect(
    variable: ['key' => 'value'],
    line: '/app/src/Controller.php:42',
);
```

::: info
\AppDevPanel\Kernel\Collector\VarDumperCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface and depends on \AppDevPanel\Kernel\Collector\TimelineCollector.
:::

## How It Works

Framework adapters hook into the `dump()` / `dd()` function to intercept variable dumps. Instead of outputting to the browser, the dumped values are captured and sent to the collector with source location.

## Debug Panel

* **Variable list** — all dumped variables with source location
* **Deep inspection** — expandable variable viewer with nested object/array support
* **File links** — clickable source file paths for IDE integration

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/collectors/web-app-info.md'
---

# WebAppInfo Collector

Collects web application performance metrics — request processing time, preload time, emit time, memory usage, and adapter name.

![WebAppInfo Collector panel](/images/collectors/web-app-info.png)

## What It Captures

| Field | Description |
|-------|-------------|
| `applicationProcessingTime` | Total application processing time |
| `requestProcessingTime` | Request handling time |
| `applicationEmit` | Response emit time |
| `preloadTime` | Bootstrap/preload time |
| `memoryPeakUsage` | Peak memory usage in bytes |
| `memoryUsage` | Current memory usage in bytes |
| `adapter` | Framework adapter name |

## Data Schema

```json
{
    "applicationProcessingTime": 0.045,
    "requestProcessingTime": 0.032,
    "applicationEmit": 0.001,
    "preloadTime": 0.012,
    "memoryPeakUsage": 8388608,
    "memoryUsage": 6291456,
    "adapter": "symfony"
}
```

**Summary** (shown in debug entry list):

```json
{
    "web": {
        "adapter": "symfony",
        "request": {
            "startTime": 1711878000.100,
            "processingTime": 0.032
        },
        "memory": {
            "peakUsage": 8388608
        }
    }
}
```

## Contract

```php
use AppDevPanel\Kernel\Collector\Web\WebAppInfoCollector;

$collector->markApplicationStarted();
$collector->markRequestStarted();
// ... request processing ...
$collector->markRequestFinished();
$collector->markApplicationFinished();
```

::: info
\AppDevPanel\Kernel\Collector\Web\WebAppInfoCollector implements \AppDevPanel\Kernel\Collector\SummaryCollectorInterface and depends on \AppDevPanel\Kernel\Collector\TimelineCollector. Located in the `Web` sub-namespace.
:::

## How It Works

Framework adapters call the `mark*()` methods at key points in the request lifecycle — application boot, request start, request end, and response emit. Memory metrics are captured via `memory_get_peak_usage()` and `memory_get_usage()`.

## Debug Panel

The WebAppInfo data is displayed in the **top bar** of every debug entry as processing time and memory usage, rather than having a dedicated panel.

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/what-is-adp.md'
---
# What is ADP?

**ADP (Application Development Panel)** is a framework-agnostic debugging and development panel for PHP applications. Think of it as a universal "developer toolbar" that works with any PHP framework.

## The Problem

Every PHP framework has its own debugging tools:

* Symfony has the **Web Profiler**
* Laravel has **Telescope**
* Yii has the **Debug Extension**

But what if you work with multiple frameworks? Or want consistent tooling across projects? That's where ADP comes in.

## The Solution

ADP provides a **single, unified debugging experience** that works across frameworks by leveraging PSR standards:

* **PSR-3** (Logger) — Captures log messages
* **PSR-7** (HTTP Messages) — Inspects requests and responses
* **PSR-14** (Event Dispatcher) — Tracks events
* **PSR-15** (HTTP Handlers) — Monitors middleware pipeline
* **PSR-11** (Container) — Inspects dependency injection

## Key Features

### Collectors

ADP ships with collectors for common debugging scenarios:

| Collector | What it captures |
|-----------|-----------------|
| AppDevPanel\Kernel\Collector\LogCollector | PSR-3 log messages |
| AppDevPanel\Kernel\Collector\EventCollector | PSR-14 events |
| AppDevPanel\Kernel\Collector\HttpClientCollector | Outgoing HTTP requests |
| AppDevPanel\Kernel\Collector\DatabaseCollector | SQL queries and timings |
| AppDevPanel\Kernel\Collector\ExceptionCollector | Caught and uncaught exceptions |
| AppDevPanel\Kernel\Collector\MiddlewareCollector | PSR-15 middleware execution |
| AppDevPanel\Kernel\Collector\ServiceCollector | DI container resolutions |
| AppDevPanel\Kernel\Collector\AssetBundleCollector | Frontend assets |
| AppDevPanel\Kernel\Collector\RouterCollector | Route matching and parameters |

### Real-time Updates

The panel uses Server-Sent Events (SSE) to push new debug entries to the browser in real-time. No need to refresh.

### AI Integration

ADP includes an MCP (Model Context Protocol) server that exposes debug data to AI assistants like Claude. Ask your AI to analyze errors, suggest fixes, or explain complex request flows.

### Framework Support

| Framework | Adapter Status |
|-----------|---------------|
| Symfony 7 | Stable |
| Yii 2 | Stable |
| Yii 3 | Stable |
| Laravel 12 | Stable |

## Philosophy

* **Framework-agnostic** — Works with any PSR-compliant framework
* **Zero configuration** — Install the adapter and it just works
* **Non-intrusive** — Uses proxies, not patches. Your code stays clean
* **Extensible** — Write custom collectors implementing AppDevPanel\Kernel\Collector\CollectorInterface for your domain
* **Modern stack** — React 19, TypeScript, Material-UI on the frontend

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/adapters/yii2.md'
---
# Yii 2 Adapter

The Yii 2 adapter bridges ADP Kernel and API into Yii 2.0.50+ via the bootstrap mechanism.

## Installation

```bash
composer require app-dev-panel/adapter-yii2
```

The package auto-registers via `extra.bootstrap` in composer.json. The AppDevPanel\Adapter\Yii2\Bootstrap class registers the `debug-panel` module automatically when `YII_DEBUG` is enabled.

## Configuration

Configure the module in your application config:

```php
'modules' => [
    'debug-panel' => [
        'class' => \AppDevPanel\Adapter\Yii2\Module::class,
        'storagePath' => '@runtime/debug',
        'historySize' => 50,
        'collectors' => [
            'request' => true,
            'exception' => true,
            'log' => true,
            'event' => true,
            'db' => true,
            'mailer' => true,
            'assets' => true,
            'redis' => true,
            'elasticsearch' => true,
            'template' => true,
            'code_coverage' => false, // opt-in, requires pcov or xdebug
            // ... all collectors enabled by default
        ],
        'ignoredRequests' => ['/debug/api/**', '/inspect/api/**'],
        'ignoredCommands' => ['help', 'list', 'cache/*', 'asset/*'],
        'allowedIps' => ['127.0.0.1', '::1'],
    ],
],
```

## Collectors

Supports all Kernel collectors plus Yii 2-specific data capture:

| Collector | Mechanism | Data |
|-----------|-----------|------|
| Database | `DbProfilingTarget` (Yii logger) | SQL queries, timing, row count |
| Log | AppDevPanel\Adapter\Yii2\Collector\DebugLogTarget (real-time Yii log target) | Log messages with PSR-3 level mapping |
| Mailer | `BaseMailer::EVENT_AFTER_SEND` | From, to, cc, bcc, subject, body |
| Asset Bundles | `View::EVENT_END_PAGE` | Bundles: class, paths, CSS/JS, dependencies |
| Translator | AppDevPanel\Adapter\Yii2\Proxy\I18NProxy replaces `Yii::$app->i18n` | Translation lookups, missing translations |
| Template | `View::EVENT_BEFORE_RENDER` + `EVENT_AFTER_RENDER` | Render timing, output, parameters (supports nesting) |
| Redis | Direct collector calls | Redis commands, timing, errors |
| Elasticsearch | Direct collector calls | ES requests, timing, hits |
| Code Coverage | `pcov` / `xdebug` extension | Per-file line coverage (opt-in) |
| Authorization | `User::EVENT_AFTER_LOGIN/LOGOUT` | Auth events, user identity |
| Router | AppDevPanel\Adapter\Yii2\Proxy\UrlRuleProxy wraps all URL rules | Route matching data, timing |

### Template Collector

The **TemplateCollector** hooks into `View::EVENT_BEFORE_RENDER` and `EVENT_AFTER_RENDER` to capture every view rendering with its file path, output, parameters, and timing. Handles nested view rendering correctly (e.g., layout → partial → widget) using a per-file timer stack. Detects duplicate renders automatically.

### Code Coverage

Code coverage is **opt-in** (`'code_coverage' => false` by default). Requires the `pcov` or `xdebug` PHP extension. Without either, the collector returns `driver: null`. See [Collectors — Code Coverage](/guide/collectors#code-coverage-collector) for details.

## Translator Integration

The adapter replaces Yii 2's `i18n` application component with AppDevPanel\Adapter\Yii2\Proxy\I18NProxy — an extended `yii\i18n\I18N` that overrides `translate()`. All `Yii::t()` calls are intercepted and logged to AppDevPanel\Kernel\Collector\TranslatorCollector automatically. See [Translator](/guide/translator) for details.

## Database Inspector

`Yii2DbSchemaProvider` provides database schema inspection via `yii\db\Schema`. Falls back to AppDevPanel\Adapter\Yii2\Inspector\NullSchemaProvider when no database component is configured.

---

---
url: 'https://app-dev-panel.github.io/app-dev-panel/guide/adapters/yii3.md'
---
# Yii 3 Adapter

The Yii 3 adapter is the reference ADP adapter. It bridges ADP Kernel and API into Yii 3 via config plugins.

## Installation

```bash
composer require app-dev-panel/adapter-yii3
```

::: info Package
app-dev-panel/adapter-yiisoft
:::

The package auto-registers via Yii 3's config plugin system — no manual wiring needed.

## Configuration

All settings are managed in `config/params.php`:

```php
'app-dev-panel/yii3' => [
    'enabled' => true,
    'collectors' => [...],
    'trackedServices' => [...],
    'ignoredRequests' => [],
    'ignoredCommands' => [],
    'dumper' => [
        'excludedClasses' => [],
    ],
    'logLevel' => [
        'AppDevPanel\\' => 0,
    ],
    'storage' => [
        'path' => '@runtime/debug',
        'historySize' => 50,
        'exclude' => [],
    ],
],
```

## Middleware

Add the following middleware to your web application stack (order matters):

```
DebugHeaders → ErrorCatcher → YiiApiMiddleware → ... → Router
```

* AppDevPanel\Api\Debug\Middleware\DebugHeaders — must be outermost to attach `X-Debug-Id` even on error responses
* AppDevPanel\Adapter\Yii3\Api\YiiApiMiddleware — intercepts `/debug/api/*` requests before the router

## Collectors

Includes Yii-specific collectors for database queries, mailer, queue, router, validator, translator, and views — in addition to all Kernel collectors (logs, events, exceptions, HTTP client, etc.).

## Translator Integration

When `yiisoft/translator` is installed, the adapter registers AppDevPanel\Adapter\Yii3\Collector\Translator\TranslatorInterfaceProxy in `trackedServices`. All `translate()` calls on `Yiisoft\Translator\TranslatorInterface` are intercepted automatically. See [Translator](/guide/translator) for details.

## Database Inspector

Database schema inspection is provided via `Yiisoft\Db` through AppDevPanel\Adapter\Yii3\Inspector\DbSchemaProvider.