PHPackages monkeyscloud/monkeyslegion-devtools - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Debugging & Profiling](/categories/debugging) 4. / 5. monkeyscloud/monkeyslegion-devtools ActiveLibrary[Debugging & Profiling](/categories/debugging) monkeyscloud/monkeyslegion-devtools =================================== Enterprise-grade debugging, profiling, inspection, and diagnostics package for MonkeysLegion — zero-magic PHP 8.4+ observability. 2.0.4(1mo ago)0150↓77.9%2MITPHPPHP ^8.4 Since Apr 27Pushed 1mo agoCompare [ Source](https://github.com/MonkeysCloud/MonkeysLegion-DevTools)[ Packagist](https://packagist.org/packages/monkeyscloud/monkeyslegion-devtools)[ Docs](https://monkeyslegion.com)[ RSS](/packages/monkeyscloud-monkeyslegion-devtools/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (8)Versions (6)Used By (2) [![PHP 8.4+](https://camo.githubusercontent.com/52b0210149e0532eb9c7786553a9b09306900967c60ce8c8650ef1bee1997d5f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e342532422d3741383642383f7374796c653d666f722d7468652d6261646765266c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/52b0210149e0532eb9c7786553a9b09306900967c60ce8c8650ef1bee1997d5f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e342532422d3741383642383f7374796c653d666f722d7468652d6261646765266c6f676f3d706870266c6f676f436f6c6f723d7768697465) [![MIT License](https://camo.githubusercontent.com/136220bfabe56c0cd331521f3cc02a25e467a53ecb16e52cde7b0db6ea667aa9/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d3965636536613f7374796c653d666f722d7468652d6261646765)](https://camo.githubusercontent.com/136220bfabe56c0cd331521f3cc02a25e467a53ecb16e52cde7b0db6ea667aa9/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d3965636536613f7374796c653d666f722d7468652d6261646765) [![Tests](https://camo.githubusercontent.com/b13a928a685ec76d2c5267c0a10edb5518445da94d315bdb28757ec9e4810f10/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f54657374732d3138342532307061737365642d3965636536613f7374796c653d666f722d7468652d6261646765)](https://camo.githubusercontent.com/b13a928a685ec76d2c5267c0a10edb5518445da94d315bdb28757ec9e4810f10/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f54657374732d3138342532307061737365642d3965636536613f7374796c653d666f722d7468652d6261646765) [![Coverage](https://camo.githubusercontent.com/f60212a32c942a8d03b5867b34b72a7073339612ec2498bb98aaec0a1efc3670/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f436f7665726167652d39302532352532422d3761613266373f7374796c653d666f722d7468652d6261646765)](https://camo.githubusercontent.com/f60212a32c942a8d03b5867b34b72a7073339612ec2498bb98aaec0a1efc3670/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f436f7665726167652d39302532352532422d3761613266373f7374796c653d666f722d7468652d6261646765) [![PHP 8.4 Hooks](https://camo.githubusercontent.com/34ebf8563f84d83330b6bc7b90e937e2899a8dc30450a85b61a91262958cfd6d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f50726f7065727479253230486f6f6b732d32362d6530616636383f7374796c653d666f722d7468652d6261646765)](https://camo.githubusercontent.com/34ebf8563f84d83330b6bc7b90e937e2899a8dc30450a85b61a91262958cfd6d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f50726f7065727479253230486f6f6b732d32362d6530616636383f7374796c653d666f722d7468652d6261646765) 🐒 MonkeysLegion DevTools ======================== [](#-monkeyslegion-devtools) **Enterprise-grade debugging, profiling, and diagnostics for MonkeysLegion v2.** Inspect every request, route, query, cache operation, event, and exception — with a self-contained debug toolbar, intelligent anomaly detection, and zero runtime overhead when disabled. ``` Laravel has Telescope. Symfony has the Web Profiler. MonkeysLegion has DevTools — and it's smarter than both. ``` --- ✨ Key Features -------------- [](#-key-features) FeatureDescription🚀 **Zero Overhead**Early-return when disabled — no reflection, no magic, no cost🪝 **PHP 8.4 Property Hooks**26 computed properties replace traditional getters across the codebase🔍 **N+1 Detection**Automatic duplicate query grouping with configurable thresholds⚡ **Cache Intelligence**Hit/miss ratios, hot key ranking, per-store breakdown📡 **Event Storm Detection**Timeline visualization with storm alerts and slow listener tracking🎯 **Deterministic Sampling**Hash-based consistency for distributed trace coherence🔒 **Redaction Pipeline**Recursive key-based masking — secrets never leak, even in dev🛡️ **Request Fingerprinting**xxh3-based grouping for automatic request clustering🖥️ **Debug Toolbar**Self-contained Tokyo Night UI — no external assets required🧪 **184 Tests**572 assertions across 22 test files — 90%+ coverage--- 📦 Installation -------------- [](#-installation) ``` composer require monkeyscloud/monkeyslegion-devtools --dev ``` For production diagnostics (sampling + redacted output): ``` composer require monkeyscloud/monkeyslegion-devtools ``` ### Requirements [](#requirements) - PHP 8.4+ (property hooks, asymmetric visibility) - PSR-7 HTTP Message (`psr/http-message ^2.0`) - PSR-15 Middleware (`psr/http-server-middleware ^1.0`) --- 🚀 Quick Start ------------- [](#-quick-start) ### 1. Boot & Register Middleware [](#1-boot--register-middleware) ``` use MonkeysLegion\DevTools\DevToolsServiceProvider; $devtools = new DevToolsServiceProvider(); $profiler = $devtools->boot([ 'enabled' => true, 'environment' => 'local', 'sample_rate' => 1.0, 'storage' => ['driver' => 'file', 'path' => 'var/devtools/profiles'], 'collectors' => [ 'request' => true, 'route' => true, 'middleware' => true, 'query' => true, 'cache' => true, 'event' => true, 'exception' => true, ], 'toolbar' => ['enabled' => true], ]); // Add to your PSR-15 pipeline $middleware = $devtools->createMiddleware(); ``` ### 2. Record Intelligence Data [](#2-record-intelligence-data) ``` // Query profiling — N+1 is detected automatically $queryCollector = $profiler->getCollector('query'); $queryCollector->recordQuery('SELECT * FROM users WHERE id = ?', durationMs: 2.3, connection: 'mysql'); // Cache tracking — hot keys are ranked automatically $cacheCollector = $profiler->getCollector('cache'); $cacheCollector->recordOperation('redis', 'user:42', 'get', hit: true, durationMs: 0.4); // Event timeline — storms are flagged automatically $eventCollector = $profiler->getCollector('event'); $eventCollector->recordDispatch('App\Event\OrderPlaced', [ ['name' => 'SendConfirmation', 'duration_ms' => 45.2], ['name' => 'UpdateInventory', 'duration_ms' => 12.1], ]); ``` ### 3. Inspect via CLI [](#3-inspect-via-cli) ``` # System status php ml devtools:status # List recent profiled requests (color-coded by status) php ml devtools:requests --limit=20 # Inspect the latest request in detail php ml devtools:request latest # Inspect by partial ID php ml devtools:request c461 # Export a sanitized profile for sharing php ml devtools:export latest --output=profile.json # Clear all stored profiles php ml devtools:clear ``` ### 4. Debug Toolbar [](#4-debug-toolbar) When `toolbar.enabled` is `true`, the toolbar auto-injects into HTML responses: - **Toggle**: Click the 🐒 bar or press `Ctrl+Shift+D` - **5 Panels**: Overview, Queries, Cache, Events, Exceptions - **Severity Badges**: Green / Yellow / Red per-panel status at a glance - **Self-Contained**: Zero external CSS/JS — embedded Tokyo Night theme The toolbar only injects into `text/html` responses and respects a configurable size limit. --- ⚙️ Configuration ---------------- [](#️-configuration) Create `config/devtools.mlc`: ``` devtools { enabled = ${DEVTOOLS_ENABLED:true} environment = ${APP_ENV:local} sample_rate = ${DEVTOOLS_SAMPLE_RATE:1.0} storage { driver = "file" path = "var/devtools/profiles" retention_days = 7 max_profiles = 1000 } collectors { request = true route = true middleware = true query = true cache = true event = true exception = true } redaction { enabled = true keys = ["password", "token", "secret", "api_key", "authorization", "cookie"] } thresholds { slow_request_ms = 200 slow_query_ms = 100 n_plus_one_count = 5 } toolbar { enabled = true max_payload_kb = 256 } production { sample_rate = 0.01 } } ``` --- 🔬 Collectors ------------ [](#-collectors) ### Built-in Collectors (7) [](#built-in-collectors-7) \#CollectorIconPriorityKey Features1**Request**🌐1000Method, URI, headers, IP hashing, fingerprint, timing, memory2**Middleware**🔗950Per-middleware timing, memory delta, bottleneck detection3**Route**🔀900Pattern, controller, params, middleware stack, OpenAPI hints4**Query**🗄️800SQL timing, N+1 detection, duplicate grouping, source tracing5**Cache**⚡700Hit/miss ratio, hot key ranking, per-store breakdown6**Event**📡600Timeline, storm detection, slow listeners, failed tracking7**Exception**💥100Class, message, trace, chain traversal, xxh3 fingerprint### Intelligence Features [](#intelligence-features) #### N+1 Query Detection [](#n1-query-detection) ``` 🔴 N+1 DETECTED: SELECT * FROM comments WHERE post_id = ? (×47 executions) Source: App\Repository\CommentRepository::findByPost() at line 42 ``` The QueryCollector automatically fingerprints SQL by normalizing literals and compares execution counts against the configurable threshold. #### Cache Hot Key Analysis [](#cache-hot-key-analysis) ``` 🔥 Hot Keys: user:session:abc123 (×84 accesses) config:app (×31 accesses) route:cache (×22 accesses) ``` #### Event Storm Detection [](#event-storm-detection) ``` 🌪️ STORM: App\Event\CacheInvalidated dispatched 142 times in this request ``` ### Custom Collectors [](#custom-collectors) Implement `CollectorInterface` to add your own: ``` use MonkeysLegion\DevTools\Contract\CollectorInterface; use MonkeysLegion\DevTools\Profiler\ProfileContext; final class MyCollector implements CollectorInterface { public function name(): string { return 'custom'; } public function label(): string { return 'Custom'; } public function icon(): string { return '🔧'; } public function priority(): int { return 500; } public function isEnabled(): bool { return true; } public function start(ProfileContext $context): void { /* setup */ } public function stop(ProfileContext $context): void { /* teardown */ } public function collect(ProfileContext $context): array { return [...]; } } $profiler->addCollector(new MyCollector()); ``` --- 🏷️ Attributes ------------- [](#️-attributes) ``` use MonkeysLegion\DevTools\Attribute\{Profile, IgnoreProfile, Redact}; // Force profiling on a specific route with a label #[Profile(name: 'checkout.process', includePayload: true)] public function processCheckout(): Response { } // Exclude high-frequency endpoints from profiling #[IgnoreProfile(reason: 'health check')] public function healthCheck(): Response { } // Mark sensitive constructor parameters public function __construct( #[Redact] private readonly string $apiSecret, #[Redact(replacement: '***')] private readonly string $dbPassword, ) {} ``` --- 🪝 PHP 8.4 Property Hooks ------------------------ [](#-php-84-property-hooks) DevTools leverages **26 PHP 8.4 property hooks** — replacing traditional getters with declarative computed properties. This is a first for PHP frameworks. ``` // Profile model — zero getters, all computed $profile->durationMs // float: endedAt - startedAt $profile->durationFormatted // "42.7ms" | "1.23s" | "850μs" $profile->isError // statusCode >= 400 $profile->isSlow // durationMs > threshold $profile->statusBadge // 🟢 🔵 🟠 🔴 ⚪ $profile->memoryPeakFormatted // "12.4 MB" $profile->memoryDelta // bytes used during request $profile->createdAtFormatted // "2026-04-27 03:42:53.087" // Profiler engine — live state hooks $profiler->isActive // currently profiling? $profiler->collectorCount // number of registered collectors $profiler->collectorNames // ['request', 'query', 'cache', ...] // QueryCollector — computed analytics $collector->queryCount // total queries recorded $collector->totalDurationMs // sum of all query times $collector->duplicateCount // grouped duplicate queries $collector->hasNPlusOne // automatic N+1 flag $collector->slowestQueryMs // max single query time // CacheCollector — computed metrics $collector->hitRatio // hits / total (float) $collector->hitRatioFormatted // "85.7%" $collector->operationCount // total operations tracked // EventCollector — computed state $collector->hasStorm // event storm detected? $collector->failedListenerCount // listeners that threw $collector->totalListenerMs // aggregate listener time // ServiceProvider — boot state $provider->booted // has boot() been called? $provider->profiler // resolved Profiler instance $provider->toolbar // resolved ToolbarRenderer ``` ### Asymmetric Visibility [](#asymmetric-visibility) All mutable state uses `private(set)` — the profiler's internal state is read-only for external consumers: ``` public private(set) string $id; public private(set) bool $booted = false; public private(set) ?Profiler $profiler = null; ``` --- 🗄️ Storage Drivers ------------------ [](#️-storage-drivers) DriverUse CasePersistence`FileProfileStorage`Local development — JSON files with index✅ Disk`MemoryProfileStorage`Testing & benchmarks❌ Request-scoped`NullProfileStorage`Disabled / CI environments❌ No-opFile storage features: - **JSON format** — human-readable, diffable, grep-friendly - **Index file** — fast listing without deserializing all profiles - **Retention pruning** — automatic cleanup on write (no cron needed) - **Query filtering** — method, URI, status, duration, environment, time range --- 🖥️ Debug Toolbar Panels ----------------------- [](#️-debug-toolbar-panels) ### Overview Panel [](#overview-panel) Request summary, performance alerts (slow/error), and collector badge aggregation. ### Query Panel [](#query-panel) SQL listing with per-query timing, duplicate warnings (🟡), and N+1 alerts (🔴). Source file tracing for each query. ### Cache Panel [](#cache-panel) Hit/miss ratio gauges, per-store breakdown table, and 🔥 hot key ranking. ### Event Panel [](#event-panel) Chronological timeline with relative timestamps, storm warnings (🌪️), and failed listener tracking. ### Exception Panel [](#exception-panel) Error display with class highlighting, sanitized stack traces, and previous exception chain traversal. ### Custom Panels [](#custom-panels) Extend `AbstractPanel` to add your own: ``` use MonkeysLegion\DevTools\Toolbar\AbstractPanel; use MonkeysLegion\DevTools\Profiler\Profile; final class MyPanel extends AbstractPanel { public function id(): string { return 'custom'; } public function label(): string { return 'Custom'; } public function icon(): string { return '🔧'; } public function priority(): int { return 400; } public function badge(Profile $profile): string { return '3 items'; } public function badgeSeverity(Profile $profile): string { return 'ok'; } public function render(Profile $profile): string { return $this->section('Data', $this->renderTable([ 'Key' => 'Value', ])); } } ``` --- 🏗️ Architecture --------------- [](#️-architecture) ``` src/ ├── Attribute/ # #[Profile], #[IgnoreProfile], #[Redact] ├── Collector/ # 7 intelligence collectors │ ├── CacheCollector.php # Hit/miss, hot keys, per-store │ ├── EventCollector.php # Timeline, storms, slow listeners │ ├── ExceptionCollector.php # Traces, chains, fingerprinting │ ├── MiddlewareCollector.php # Per-middleware timing, bottlenecks │ ├── QueryCollector.php # N+1, duplicates, SQL fingerprinting │ ├── RequestCollector.php # Headers, IP hash, fingerprint │ └── RouteCollector.php # Pattern, controller, OpenAPI ├── Command/ # 5 CLI commands (devtools:*) ├── Contract/ # Stable interfaces ├── Exception/ # Package exceptions ├── Middleware/ # PSR-15 DevToolsMiddleware ├── Profiler/ # Core engine │ ├── Profile.php # 10 property hooks │ ├── ProfileContext.php # Request lifecycle context │ └── Profiler.php # Orchestrator with 3 hooks ├── Redaction/ # Key-based recursive masking ├── Sampler/ # Rate-based + deterministic sampling ├── Storage/ # File, Memory, Null drivers ├── Toolbar/ # Self-contained debug toolbar │ ├── Panel/ # 5 built-in panels │ ├── AbstractPanel.php # Rendering helpers │ ├── PanelInterface.php # Panel contract │ ├── ToolbarInjector.php # HTML response injection │ └── ToolbarRenderer.php # Self-contained HTML/CSS/JS └── DevToolsServiceProvider.php # Config-driven bootstrap ``` **40 source files** · **5,099 lines** · **22 test files** · **184 tests** · **572 assertions** --- 🆚 Competitive Comparison ------------------------ [](#-competitive-comparison) FeatureSymfony ProfilerLaravel Telescope**ML DevTools**PHP Version8.2+8.3+**8.4+**Property Hooks00**26**N+1 Detection❌❌**✅ Automatic**Event Storm Detection❌❌**✅**Cache Hot Key Analysis❌❌**✅**Deterministic Sampling❌❌**✅ Hash-based**Request Fingerprinting❌❌**✅ xxh3**Priority Collectors❌❌**✅ With wrap**Partial Value Redaction❌❌**✅**Self-Contained Toolbar❌ Requires Webpack❌ Requires Tailwind**✅ Embedded**Zero-Overhead Disabled⚠️ Partial❌**✅ Full**Asymmetric Visibility❌❌**✅ private(set)**MLC Config Format❌❌**✅ Native**--- 🧪 Testing --------- [](#-testing) ``` # Run all tests composer test # With testdox output ./vendor/bin/phpunit --testdox # Static analysis composer analyse ``` ### Test Suite Coverage [](#test-suite-coverage) AreaTest FilesTestsAssertionsCollectors (7)762178Profiler Core328102Storage (3)32872Toolbar & Panels338108Service Provider11234Middleware1412Attributes1918Exceptions136Redaction11024Sampler1618**Total****22****184****572**--- 🗺️ Roadmap ---------- [](#️-roadmap) PhaseFocusStatus0Contracts & Skeleton✅ Complete1MVP Profiler & CLI✅ Complete2Debug Toolbar & Local DX✅ Complete3Query, Cache & Event Intelligence✅ Complete4Container, Entity & Config Inspectors🔜 Next5OpenAPI, Security & Validation Reports🔜 Planned6Production Diagnostics & APM🔜 Planned7MonkeysCloud SaaS Integration🔜 Planned--- 🤝 Contributing -------------- [](#-contributing) 1. Fork & clone the repository 2. Install dependencies: `composer install` 3. Run the test suite: `composer test` 4. Run static analysis: `composer analyse` 5. Submit a PR against `main` Please ensure all new collectors include corresponding unit tests and property hooks where applicable. --- 📄 License --------- [](#-license) MIT — © 2026 MonkeysCloud Team Built with 🐒 by [MonkeysCloud](https://monkeyslegion.com) ### Health Score 45 — FairBetter than 91% of packages Maintenance91 Actively maintained with recent releases Popularity15 Limited adoption so far Community10 Small or concentrated contributor base Maturity55 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~1 days Total 5 Last Release 41d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/2913369?v=4)[Jorge Peraza](/maintainers/yorchperaza)[@yorchperaza](https://github.com/yorchperaza) --- Top Contributors [![yorchperaza](https://avatars.githubusercontent.com/u/2913369?v=4)](https://github.com/yorchperaza "yorchperaza (6 commits)") --- Tags profilerinspectiontoolbarDevtoolsdebuggerobservabilitydiagnosticsphp84monkeyslegion ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/monkeyscloud-monkeyslegion-devtools/health.svg) ``` [![Health](https://phpackages.com/badges/monkeyscloud-monkeyslegion-devtools/health.svg)](https://phpackages.com/packages/monkeyscloud-monkeyslegion-devtools) ``` ### Alternatives [cakephp/cakephp The CakePHP framework 8.8k19.1M1.7k](/packages/cakephp-cakephp)[typo3/cms TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL. 1.2k1.9M122](/packages/typo3-cms)[tempest/framework The PHP framework that gets out of your way. 2.2k31.1k11](/packages/tempest-framework)[typo3/cms-core TYPO3 CMS Core 3312.9M4.7k](/packages/typo3-cms-core)[windwalker/framework The next generation PHP framework. 25640.0k1](/packages/windwalker-framework)[jaxon-php/jaxon-core Jaxon is an open source PHP library for easily creating Ajax web applications 73147.2k29](/packages/jaxon-php-jaxon-core) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)