PHP DebugBar Middleware

Modern PSR-15 middleware for PHP DebugBar with automatic asset serving and zero configuration. Works seamlessly with Mezzio, Slim 4, Symfony, and any PSR-15 compatible framework.

✨ Features

• 🚀 Zero Configuration - Works out of the box
• 🎯 Automatic Asset Serving - No manual asset copying required
• 🔒 Security First - Path traversal protection and development-only activation
• ⚡ High Performance - Minimal overhead, production-safe
• 🎨 Full Styling - Complete CSS/JS with Font Awesome icons
• 🔧 Framework Agnostic - Works with any PSR-15 framework
• 📱 Modern PHP - Requires PHP 8.2+, strict types, comprehensive typing

📦 Installation

composer require --dev responsive-sk/php-debugbar-middleware

🚀 Quick Start

Mezzio / Laminas

// config/config.php
$configManager = new ConfigManager([
    ResponsiveSk\PhpDebugBarMiddleware\ConfigProvider::class,
    // ... your other config providers
]);

// config/pipeline.php
$app->pipe(ResponsiveSk\PhpDebugBarMiddleware\DebugBarMiddleware::class);

// src/App/RoutesDelegator.php (REQUIRED for assets)
$app->get('/debugbar/{file:.+}', [\ResponsiveSk\PhpDebugBarMiddleware\DebugBarAssetsHandler::class], 'debugbar::assets');

Slim 4

use ResponsiveSk\PhpDebugBarMiddleware\DebugBarMiddleware;
use ResponsiveSk\PhpDebugBarMiddleware\DebugBarAssetsHandler;

$app = AppFactory::create();

// Add middleware
$app->add(DebugBarMiddleware::class);

// Add asset route
$app->get('/debugbar/{file:.+}', DebugBarAssetsHandler::class);

Symfony (with PSR-15 Bridge)

// config/services.yaml
services:
    ResponsiveSk\PhpDebugBarMiddleware\DebugBarMiddleware:
        tags: ['middleware']

Manual Setup (Any PSR-15 Framework)

use ResponsiveSk\PhpDebugBarMiddleware\DebugBarMiddleware;
use ResponsiveSk\PhpDebugBarMiddleware\DebugBarAssetsHandler;

// Create middleware
$debugBarMiddleware = new DebugBarMiddleware();

// Add to your middleware stack
$middlewareStack->add($debugBarMiddleware);

// Add asset handler to your router
$router->get('/debugbar/{file:.+}', new DebugBarAssetsHandler());

🎛️ Configuration

Environment-Based Activation

DebugBar automatically activates in development and deactivates in production:

# Development (DebugBar active)
APP_ENV=development
DEBUG=true

# Production (DebugBar inactive)
APP_ENV=production
DEBUG=false

Custom Configuration

// config/autoload/debugbar.local.php
return [
    'debugbar' => [
        'enabled' => true,
        'collectors' => [
            'messages' => true,
            'time' => true,
            'memory' => true,
            'exceptions' => true,
            'request' => true,
        ],
        'asset_path' => '/debugbar',
    ],
];

🔧 Framework-Specific Examples

Mezzio Complete Setup

// config/config.php
use Laminas\ConfigAggregator\ConfigAggregator;
use ResponsiveSk\PhpDebugBarMiddleware\ConfigProvider;

$aggregator = new ConfigAggregator([
    ConfigProvider::class,
    // ... other providers
]);

return $aggregator->getMergedConfig();

// config/pipeline.php
$app->pipe(ResponsiveSk\PhpDebugBarMiddleware\DebugBarMiddleware::class);

// src/App/RoutesDelegator.php
public function __invoke(ContainerInterface $container, string $serviceName, callable $callback): Application
{
    /** @var Application $app */
    $app = $callback();

    // Your application routes
    $app->get('/', [HomePageHandler::class], 'home');

    // DebugBar assets route (REQUIRED for CSS/JS)
    $app->get('/debugbar/{file:.+}', [\ResponsiveSk\PhpDebugBarMiddleware\DebugBarAssetsHandler::class], 'debugbar::assets');

    return $app;
}

Slim 4 with Container

use DI\Container;
use ResponsiveSk\PhpDebugBarMiddleware\DebugBarMiddleware;

$container = new Container();
$app = AppFactory::createFromContainer($container);

// Register middleware
$container->set(DebugBarMiddleware::class, function() {
    return new DebugBarMiddleware();
});

$app->add(DebugBarMiddleware::class);

📊 What You Get

• Request Timeline - See exactly where time is spent
• Memory Usage - Track memory consumption
• Exception Tracking - Catch and display errors
• Request Data - Inspect GET/POST/COOKIE data
• Custom Messages - Add your own debug messages
• Database Queries - Monitor SQL performance (with additional collectors)

🛡️ Security

• Development Only - Automatically disabled in production
• Path Traversal Protection - Secure asset serving
• No External Dependencies - All assets served locally
• Environment Detection - Respects APP_ENV and DEBUG settings

🎨 Styling

DebugBar appears with full styling including:

• Font Awesome icons
• Responsive design
• Dark/light theme support
• Professional appearance
• Zero configuration required

🧪 Testing

# Run tests
composer test

# Run with coverage
composer test-coverage

# Static analysis
composer phpstan

# Code style check
composer cs-check

# Fix code style
composer cs-fix

# Run all quality checks
composer quality

📈 Performance

• Zero Production Impact - Completely disabled in production
• Minimal Development Overhead - Optimized for development workflow
• Efficient Asset Serving - Direct file serving without processing
• Memory Efficient - Lazy loading and minimal memory footprint

🎨 Custom Branding

Want to use your own logo instead of the default? Check out our comprehensive Branding Guide with examples for:

• Custom Logo Integration - Replace with your company logo
• Theme Customization - Match your brand colors
• Framework-Specific Examples - Ready-to-use configurations
• Best Practices - Design and performance guidelines

🚀 Roadmap & Future Enhancements

See our Roadmap for planned features and enhancement ideas:

• Database query collectors
• Advanced performance monitoring
• Mobile-responsive design
• Plugin system architecture
• Enterprise features

🔧 Troubleshooting

DebugBar appears but CSS/JS assets return 404

Problem: DebugBar HTML is injected but assets (CSS/JS) are not loading.

Solution: Make sure you've registered the assets route:

// In your RoutesDelegator or routes configuration
$app->get('/debugbar/{file:.+}', [\ResponsiveSk\PhpDebugBarMiddleware\DebugBarAssetsHandler::class], 'debugbar::assets');

DebugBar doesn't appear at all

Causes & Solutions:

1. Environment Detection: DebugBar only appears in development

   # Set environment variables
   export APP_ENV=development
   export DEBUG=true

2. Middleware Not Registered: Ensure middleware is in pipeline

   // config/pipeline.php
   $app->pipe(ResponsiveSk\PhpDebugBarMiddleware\DebugBarMiddleware::class);

3. ConfigProvider Not Loaded: Check config aggregation

   // config/config.php
   $configManager = new ConfigManager([
       ResponsiveSk\PhpDebugBarMiddleware\ConfigProvider::class,
       // ... other providers
   ]);

Class not found errors

Solution: Regenerate autoloader

composer dump-autoload

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

📄 License

This package is open-sourced software licensed under the MIT license.

🙏 Credits

• Built by Responsive.sk
• Based on PHP DebugBar by Maxime Bouroumeau-Fuseau
• Inspired by the Laravel DebugBar package

🔗 Related Packages

• php-debugbar/php-debugbar - The core DebugBar library
• responsive-sk/slim4-paths - Path management for PHP applications