Error Handling Middleware

Introduction

The Error Middleware intercepts unhandled exceptions and PHP errors within your application. It converts them into standardized, API-friendly JSON responses, ensuring that your API consumers never encounter raw HTML stack traces or silent failures.

Key features include:

• Automated JSON Formatting: Catches all Throwables and returns a structured JSON payload.
• Environment Awareness: Displays detailed stack traces when debug is enabled, and generic messages in production.
• Logging Integration: Automatically logs exceptions to the built in logger (e.g., Monolog) based on your verbosity settings.

Installation

Install the middleware via composer by running:

composer require kipchak/middleware-error

Configuration

Unlike other middlewares, the Error Middleware typically relies on your global application configuration found in kipchak.api.php. It uses the global debug and logging flags to determine its behavior.

Configuration Keys

The below properties are configured in kipchak.api.php.

• debug (bool):
  • true: The middleware will return detailed JSON responses including file, line, and trace. (Development mode).
  • false: The middleware returns a generic "Internal Server Error" message to prevent information leakage. (Production mode).
• logExceptions (bool):
  • If true, exceptions are sent to the registered Logger instance.
• logExceptionDetails (bool):
  • If true, the log entry will include the full stack trace.

Example Configuration

<?php

use function Kipchak\Core\env;

return [
    // ... other settings ...
    'debug' => (bool) env('DEBUG', true),
    'logExceptions' => true,
    'logExceptionDetails' => true,
];

Usage

Once enabled, this middleware works automatically.

Response Formats

1. Production Response (debug => false)

When an error occurs in production, the details are suppressed.

{
    "message": "Internal Server Error",
    "exception": [
        {
            "type": "Exception",
            "code": 500,
            "message": "Internal Server Error",
            "file": "/path/to/app/src/Core/ErrorHandler.php",
            "line": 42
        }
    ]
}
// Note: The structure may vary slightly, but sensitive trace data is hidden.

2. Debug Response (debug => true)

In development, you get full visibility to debug issues quickly.

{
    "message": "Call to undefined function missing_function()",
    "exception": [
        {
            "type": "Error",
            "code": 500,
            "message": "Call to undefined function missing_function()",
            "file": "/var/www/html/src/Controllers/UserController.php",
            "line": 25,
            "trace": [
                "#0 /var/www/html/vendor/slim/slim/Slim/Handlers/Strategies/RequestResponse.php(43): App\\Controllers\\UserController->__invoke(...)",
                "#1 ..."
            ]
        }
    ]
}

You'll see these in the container logs on a single line formatted as JSON .

Git Repository

The source code for this driver is available on 1x.ax at https://1x.ax/mamluk/kipchak/middlewares/error.