PHPackages martino/kirby-debug-toggle - 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. martino/kirby-debug-toggle ActiveKirby-plugin[Debugging & Profiling](/categories/debugging) martino/kirby-debug-toggle ========================== A Kirby 5 CMS panel plugin for safe, time-limited debug mode toggling with automatic expiry 1.0.0(1mo ago)10MITPHP Since Apr 7Pushed 3w ago1 watchersCompare [ Source](https://github.com/JoaoMartino/kirby-debug-toggle)[ Packagist](https://packagist.org/packages/martino/kirby-debug-toggle)[ Docs](https://github.com/JoaoMartino/kirby-debug-toggle)[ RSS](/packages/martino-kirby-debug-toggle/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (1)Versions (2)Used By (0) Debug Toggle for Kirby 5 ======================== [](#debug-toggle-for-kirby-5) A Kirby 5 CMS panel plugin that provides a safe, time-limited debug mode toggle with automatic expiry and git-safe flag file management. [![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)[![Kirby](https://camo.githubusercontent.com/129cbd06df744e4c587392840a3d2b09aedc102b63c7cd47f1de8271b291e6c3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4b697262792d352e782d6f72616e67652e737667)](https://camo.githubusercontent.com/129cbd06df744e4c587392840a3d2b09aedc102b63c7cd47f1de8271b291e6c3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4b697262792d352e782d6f72616e67652e737667) Features -------- [](#features) - **Flag-based debug control** - Uses a `.debug_enabled` flag file instead of modifying `config.php` - **Panel auto-debug** - Automatically enables debug for panel when authorized users are logged in (prevents panel lockout) - **Auto-expiry** - Debug mode automatically disables after configured hours - **Permission system** - Restrict access by admin status, role name, or custom callback - **Git-safe** - Automatically adds flag file to `.gitignore` - **Panel UI** - Clean card-based interface with status indicator - **Dark/Light mode** - Fully responsive to Kirby panel theme (Kirby 5) and fallback for Kirby 4 - **Real-time status** - Shows who enabled debug and when it expires Demo ---- [](#demo) [![Debug Toggle Demo](.github/assets/kirby-debug-toggle.gif)](.github/assets/kirby-debug-toggle.gif) Why this exists --------------- [](#why-this-exists) The built-in Kirby workarounds for toggling debug mode didn't fully fit my needs. So I built this for myself. It does exactly what I need and nothing more. If it fits yours too, feel free to use it. Installation ------------ [](#installation) ### Manual Installation [](#manual-installation) 1. Download and extract the plugin to `site/plugins/debug-toggle/` 2. The plugin structure should be: ``` site/plugins/debug-toggle/ ├── index.php ├── index.js ├── index.css ├── README.md └── LICENSE ``` ### Composer Installation [](#composer-installation) ``` composer require martino/kirby-debug-toggle ``` Configuration ------------- [](#configuration) **⚠️ Required:** Add the following to your `site/config/config.php`: ``` return [ // REQUIRED: Debug mode controlled by flag file // Replace any existing 'debug' => true with this closure 'debug' => (function() { $flag = __DIR__ . '/.debug_enabled'; if (!file_exists($flag)) return false; $data = @json_decode(file_get_contents($flag), true); if (!$data || empty($data['expires_at'])) return false; return time() < $data['expires_at']; })(), // OPTIONAL: Plugin configuration (uses defaults if omitted) 'Martino.debug-toggle.expiry-hours' => 4, // Hours until auto-disable (default: 4) 'Martino.debug-toggle.permission' => 'admin', // Who can toggle (default: 'admin') 'Martino.debug-toggle.panel-auto-debug' => true, // Auto-enable debug for panel (default: true) ]; ``` **Important:** The `debug` closure is required for the plugin to work. Without it, the panel UI will appear but debug mode won't actually activate when toggled. **Panel Auto-Debug:** By default, debug mode is automatically enabled in the panel for authorized users (even when the toggle is OFF). This prevents panel corruption from hiding errors. You can disable this by setting `'Martino.debug-toggle.panel-auto-debug' => false`. Configuration Options --------------------- [](#configuration-options) ### `Martino.debug-toggle.expiry-hours` [](#martinodebug-toggleexpiry-hours) **Type:** `int` **Default:** `4` Number of hours until debug mode automatically disables. ``` 'Martino.debug-toggle.expiry-hours' => 8, // 8 hours ``` ### `Martino.debug-toggle.permission` [](#martinodebug-togglepermission) **Type:** `string|callable` **Default:** `'admin'` Controls who can access and toggle debug mode. **Options:** 1. **`'admin'`** - Only users with admin status (uses `isAdmin()`) ``` 'Martino.debug-toggle.permission' => 'admin', ``` 2. **Role name** - Only users with specific role ``` 'Martino.debug-toggle.permission' => 'editor', 'Martino.debug-toggle.permission' => 'developer', ``` 3. **Custom callback** - Custom permission logic ``` 'Martino.debug-toggle.permission' => function($user) { return in_array($user->email(), ['dev@example.com', 'admin@example.com']); }, ``` ### `Martino.debug-toggle.panel-auto-debug` [](#martinodebug-togglepanel-auto-debug) **Type:** `bool` **Default:** `true` Automatically enables debug mode in the panel for authorized users, even when the toggle is OFF. **Why this exists:** If the panel breaks due to an error, you need debug mode to see what went wrong. With this enabled, authorized users always see panel errors, preventing you from being locked out. ``` 'Martino.debug-toggle.panel-auto-debug' => true, // Always show panel errors to authorized users 'Martino.debug-toggle.panel-auto-debug' => false, // Disable auto-debug (not recommended) ``` **Behavior:** - ✅ **Frontend:** Controlled by the toggle (manual) - ✅ **Panel (authorized users):** Always ON (auto-debug) - ✅ **Panel (public/unauthorized):** Controlled by the toggle Usage ----- [](#usage) 1. Log in to the Kirby panel as an authorized user 2. Click **Debug** in the sidebar menu 3. Click **Turn ON** to enable debug mode 4. Debug mode will automatically disable after the configured expiry time 5. Click **Turn OFF** to manually disable debug mode ### Panel Interface [](#panel-interface) The debug toggle interface displays: - **Status** - Current state (ON/OFF) - **Enabled by** - Email of user who enabled debug - **Expires at** - Timestamp when debug will auto-disable - **Warning message** - Reminder that errors are visible to all visitors - **Status indicator** - Visual dot (orange = active, gray = inactive) How It Works ------------ [](#how-it-works) ### Flag File System [](#flag-file-system) The plugin uses a flag file at `site/config/.debug_enabled` to control debug mode: ``` { "enabled_by": "admin@example.com", "enabled_at": 1712345678, "expires_at": 1712359678 } ``` **Benefits:** - No modification of `config.php` required - Git-safe (automatically added to `.gitignore`) - Automatic expiry prevents forgotten debug mode - Tracks who enabled debug and when ### Security [](#security) - All API routes require authentication and permission checks - Flag file is created with `chmod 0600` (owner read/write only) - Expired flags are automatically deleted on next state check - Default state is OFF (no flag file = no debug) API Routes ---------- [](#api-routes) The plugin provides two API endpoints: ### GET `/api/debug-toggle/state` [](#get-apidebug-togglestate) Returns current debug state and metadata. **Response:** ``` { "debug": true, "enabled_by": "admin@example.com", "enabled_at": "2024-04-05 14:00", "expires_at": "2024-04-05 18:00", "expired": false } ``` ### POST `/api/debug-toggle/state` [](#post-apidebug-togglestate) Toggles debug mode on or off. **Request:** ``` { "enabled": true } ``` **Response:** Same as GET endpoint Requirements ------------ [](#requirements) - Kirby 5.x - PHP 8.2+ - Panel access with appropriate permissions Troubleshooting --------------- [](#troubleshooting) ### Debug toggle menu not visible [](#debug-toggle-menu-not-visible) - Verify you're logged in as an admin user (or user with configured permission) - Check that the plugin files are in `site/plugins/debug-toggle/` - Hard refresh the panel (Cmd+Shift+R / Ctrl+Shift+R) ### Debug mode not working [](#debug-mode-not-working) - Verify the debug config closure is added to `config.php` - Check file permissions on `site/config/` directory - Ensure `.debug_enabled` file can be created/deleted ### Permission denied errors [](#permission-denied-errors) - Verify your user has the required permission level - Check the `Martino.debug-toggle.permission` config option Development ----------- [](#development) ### File Structure [](#file-structure) ``` site/plugins/debug-toggle/ ├── index.php # Backend: panel area, API routes, helpers ├── index.js # Frontend: Vue component ├── index.css # Styles: dark/light mode support ├── README.md # Documentation └── LICENSE # MIT License ``` ### Helper Functions [](#helper-functions) The plugin provides these helper functions: - `debugFlagPath()` - Returns path to flag file - `debugFlagData()` - Reads and decodes flag file - `debugFlagExpired()` - Checks if flag has expired - `debugFlagActive()` - Checks if debug is currently active - `debugHasPermission()` - Checks if current user has permission - `ensureGitIgnore()` - Adds flag file to `.gitignore` License ------- [](#license) MIT License - Copyright (c) 2026 João Martino / nonverbal See [LICENSE](LICENSE) file for details. Author ------ [](#author) **João Martino** nonverbal [nonverbalclub.pt](https://nonverbalclub.pt) Support ------- [](#support) For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/JoaoMartino/kirby-debug-toggle). **Questions or doubts:** - - --- Made with ❤️ for the Kirby community ### Health Score 35 — LowBetter than 80% of packages Maintenance95 Actively maintained with recent releases Popularity2 Limited adoption so far Community7 Small or concentrated contributor base Maturity33 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 32d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/cc37d8941ffc3ae3c17e4281eabad8e875d8bc41af23fce82e0df322d907e5bf?d=identicon)[JoaoMartino](/maintainers/JoaoMartino) --- Top Contributors [![JoaoMartino](https://avatars.githubusercontent.com/u/54320369?v=4)](https://github.com/JoaoMartino "JoaoMartino (11 commits)") --- Tags debugdevelopmentkirbykirby-pluginkirby-cmspanel ### Embed Badge ![Health badge](/badges/martino-kirby-debug-toggle/health.svg) ``` [![Health](https://phpackages.com/badges/martino-kirby-debug-toggle/health.svg)](https://phpackages.com/packages/martino-kirby-debug-toggle) ``` ### Alternatives [spatie/laravel-web-tinker Artisan Tinker in your browser 1.2k3.8M6](/packages/spatie-laravel-web-tinker)[bnomei/kirby3-janitor Kirby Plugin for running commands like cleaning the cache from within the Panel, PHP code or a cronjob 9339.9k2](/packages/bnomei-kirby3-janitor)[bnomei/kirby-janitor Kirby Plugin for running commands like cleaning the cache from within the Panel, PHP code or a cronjob 922.8k1](/packages/bnomei-kirby-janitor)[kktsvetkov/krumo Krumo is a debugging tool, which displays structured information about any PHP variable. It is a nice replacement for print\_r() or var\_dump() which are used by a lot of PHP developers. 8260.7k](/packages/kktsvetkov-krumo)[bnomei/kirby3-feed Generate a Atom/JSON/RSS-Feed and XML-Sitemap from Pages-Collections 7224.8k](/packages/bnomei-kirby3-feed)[belugadigital/kirby-navigation Kirby 5 field for hierarchical menus with drag & drop level indentation. 8713.4k](/packages/belugadigital-kirby-navigation) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)