feat: Add lightweight debug bar system for development

Author: jmrashed

.env.example

@@ -13,4 +13,8 @@ JWT_SECRET=your-secret-key-here
 JWT_EXPIRE=3600
 
 CACHE_DRIVER=file
-LOG_LEVEL=debug
+LOG_LEVEL=debug
+
+# Debug Bar Configuration
+DEBUGBAR_ENABLED=true
+DEBUGBAR_ALLOWED_IPS=127.0.0.1,::1

CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.1.0] - 2025-10-21
+
+### Added
+- **Debug Bar System** - Lightweight development debugging toolbar
+  - Real-time performance monitoring (execution time, memory usage)
+  - Database query tracking with timing information
+  - Debug message logging with different severity levels
+  - HTTP request information capture
+  - Timer functionality for measuring code execution
+  - Automatic PDO query interception and logging
+  - Safe by default - only enabled via environment configuration
+  - IP whitelist support for security
+  - Minimal overhead when disabled
+
+### Features
+- `CollectorInterface` - Base interface for debug collectors
+- `DebugBar` - Main singleton manager for debug functionality
+- Built-in collectors:
+  - `TimerCollector` - Measures execution times
+  - `MemoryCollector` - Tracks memory usage
+  - `MessageCollector` - Logs debug messages
+  - `QueryCollector` - Records database queries
+  - `RequestCollector` - Captures HTTP request data
+- `DebugPDO` - PDO wrapper for automatic query tracking
+- Helper functions: `debug()`, `timer_start()`, `timer_stop()`
+- Responsive debug toolbar UI with tabbed interface
+- Dual output support: HTML toolbar for web pages, JSON headers for APIs
+
+### Configuration
+- `DEBUGBAR_ENABLED` - Enable/disable debug bar
+- `DEBUGBAR_ALLOWED_IPS` - IP whitelist for security
+
+### Fixed
+- PHP 8+ compatibility issues with PDO return types
+- `getallheaders()` function compatibility for CLI environments
+
+### Security
+- Debug bar automatically disabled in production
+- IP-based access control
+- No sensitive data exposure in debug output

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Md Rasheduzzaman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -20,6 +20,7 @@ A production-ready Raw PHP REST API Starter Kit with JWT authentication, user ma
 - ✅ **Docker Support** - Containerized deployment
 - ✅ **PHPUnit Testing** - Comprehensive test suite
 - ✅ **API Documentation** - Complete endpoint docs
+- ✅ **Debug Bar** - Development debugging toolbar with performance monitoring
 
 ## 📁 Project Structure
 
@@ -29,6 +30,7 @@ A production-ready Raw PHP REST API Starter Kit with JWT authentication, user ma
 │   ├── controllers/     # Request handlers
 │   ├── core/           # Core framework classes
 │   ├── database/       # Migrations and seeders
+│   ├── debugbar/       # Debug bar system
 │   ├── exceptions/     # Exception handlers
 │   ├── helpers/        # Utility classes
 │   ├── middleware/     # Request middleware
@@ -58,6 +60,13 @@ cp .env.example .env
 # Edit .env with your database credentials
 ```
 
+**Debug Bar Configuration (Optional)**
+```bash
+# Enable debug bar for development
+DEBUGBAR_ENABLED=true
+DEBUGBAR_ALLOWED_IPS=127.0.0.1,::1
+```
+
 ### 3. Database Setup
 ```bash
 # Option 1: Import the complete database schema
@@ -185,6 +194,65 @@ The HRMS includes the following tables:
 - CORS middleware
 - SQL injection protection (prepared statements)
 
+## 🔧 Debug Bar
+
+The built-in debug bar provides real-time development insights with minimal performance impact.
+
+### Features
+- **Performance Monitoring** - Execution time and memory usage tracking
+- **Database Queries** - All SQL queries with timing information
+- **Debug Messages** - Categorized logging (info, warning, error)
+- **Request Data** - HTTP method, URI, headers, and parameters
+- **Custom Timers** - Measure specific code execution times
+
+### Configuration
+
+Add to your `.env` file:
+```bash
+# Enable debug bar (disabled by default)
+DEBUGBAR_ENABLED=true
+
+# Optional: Restrict access by IP (comma-separated)
+DEBUGBAR_ALLOWED_IPS=127.0.0.1,::1,192.168.1.100
+```
+
+### Usage
+
+#### Debug Messages
+```php
+// Log debug messages with different levels
+debug('User login attempt', 'info');
+debug('Invalid credentials', 'warning');
+debug('Database connection failed', 'error');
+```
+
+#### Performance Timing
+```php
+// Measure execution time
+timer_start('api_call');
+// ... your code ...
+timer_stop('api_call');
+```
+
+#### Automatic Features
+- **Database Queries**: All PDO queries are automatically tracked
+- **Memory Usage**: Current and peak memory consumption
+- **Request Info**: HTTP method, URI, headers automatically captured
+
+### Output Modes
+
+**HTML Pages**: Debug toolbar appears at the bottom of the page
+**JSON APIs**: Debug data included in `X-Debugbar-Data` response header (Base64 encoded JSON)
+
+### Security
+- Automatically disabled when `DEBUGBAR_ENABLED=false`
+- IP whitelist support for production-like environments
+- No sensitive data exposure (credentials are filtered)
+- Zero performance impact when disabled
+
+### Test Debug Bar
+Visit `http://localhost:8000/welcome` to see the debug bar in action.
+
 ## 🧪 Testing
 
 ```bash

app/config/env.php

@@ -27,4 +27,20 @@ public static function get($key, $default = null)
     {
         return self::$variables[$key] ?? $default;
     }
+
+    public static function getLogLevel()
+    {
+        return self::get('LOG_LEVEL', 'INFO');
+    }
+
+    public static function isDebugBarEnabled(): bool
+    {
+        return self::get('DEBUGBAR_ENABLED', 'false') === 'true';
+    }
+
+    public static function getDebugBarAllowedIps(): array
+    {
+        $ips = self::get('DEBUGBAR_ALLOWED_IPS', '');
+        return $ips ? explode(',', $ips) : [];
+    }
 }

app/controllers/ExampleController.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace App\Controllers;
+
+use App\Core\Controller;
+use App\Core\Request;
+use App\Core\Response;
+use App\Helpers\Logger;
+
+class ExampleController extends Controller
+{
+    public function index(Request $request, Response $response)
+    {
+        Logger::info('ExampleController index method accessed.', ['user_id' => 123, 'ip_address' => $request->ip()]);
+        return $response->json(['message' => 'Example index response']);
+    }
+
+    public function show(Request $request, Response $response, $id)
+    {
+        Logger::warning('ExampleController show method accessed with ID.', ['id' => $id, 'user_id' => 123]);
+        return $response->json(['message' => "Showing example with ID: {$id}"]);
+    }
+
+    public function store(Request $request, Response $response)
+    {
+        $data = $request->json();
+        if (empty($data['name'])) {
+            Logger::error('Attempted to store example with missing name.', ['request_data' => $data]);
+            return $response->json(['error' => 'Name is required'], 400);
+        }
+        Logger::info('New example stored successfully.', ['data' => $data]);
+        return $response->json(['message' => 'Example stored', 'data' => $data], 201);
+    }
+}

app/controllers/LeaveTypeController.php

@@ -13,16 +13,16 @@ public function index()
         $perPage = $this->request->get('per_page', 10);
         $page = $this->request->get('page', 1);
         $leaveTypes = LeaveType::paginate($perPage, $page);
-        return Response::json($leaveTypes);
+        return Response::success('Leave Types retrieved successfully', $leaveTypes);
     }
 
     public function show($id)
     {
         $leaveType = LeaveType::find($id);
         if (!$leaveType) {
-            return Response::json(['error' => 'Leave Type not found'], 404);
+            return Response::error('Leave Type not found', 404);
         }
-        return Response::json($leaveType);
+        return Response::success('Leave Type retrieved successfully', $leaveType);
     }
 
     public function store()
@@ -34,16 +34,16 @@ public function store()
         $leaveType->max_days = $data['max_days'] ?? null;
 
         if ($leaveType->save()) {
-            return Response::json(['message' => 'Leave Type created successfully', 'leave_type' => $leaveType], 201);
+            return Response::success('Leave Type created successfully', ['leave_type' => $leaveType], 201);
         }
-        return Response::json(['error' => 'Failed to create leave type'], 500);
+        return Response::error('Failed to create leave type', 500);
     }
 
     public function update($id)
     {
         $leaveType = LeaveType::find($id);
         if (!$leaveType) {
-            return Response::json(['error' => 'Leave Type not found'], 404);
+            return Response::error('Leave Type not found', 404);
         }
 
         $data = $this->request->json();
@@ -52,21 +52,21 @@ public function update($id)
         $leaveType->max_days = $data['max_days'] ?? $leaveType->max_days;
 
         if ($leaveType->save()) {
-            return Response::json(['message' => 'Leave Type updated successfully', 'leave_type' => $leaveType]);
+            return Response::success('Leave Type updated successfully', ['leave_type' => $leaveType]);
         }
-        return Response::json(['error' => 'Failed to update leave type'], 500);
+        return Response::error('Failed to update leave type', 500);
     }
 
     public function destroy($id)
     {
         $leaveType = LeaveType::find($id);
         if (!$leaveType) {
-            return Response::json(['error' => 'Leave Type not found'], 404);
+            return Response::error('Leave Type not found', 404);
         }
 
         if ($leaveType->delete()) {
-            return Response::json(['message' => 'Leave Type deleted successfully']);
+            return Response::success('Leave Type deleted successfully');
         }
-        return Response::json(['error' => 'Failed to delete leave type'], 500);
+        return Response::error('Failed to delete leave type', 500);
     }
 }