<?php

namespace App\Core;

/**
 * MiddlewareInterface — Formal Middleware Contract
 *
 * Every middleware class in the Inveetaire pipeline MUST implement this
 * interface. The interface formalises the convention-only contract that
 * was enforced by method_exists() in MiddlewarePipeline::wrap() during
 * Sprint 0 (INIT-009).
 *
 * Contract:
 *   - Implementing classes must declare handle(Request, callable): void.
 *   - The $next callable continues execution to the next middleware layer
 *     or to the final controller action (the pipeline destination).
 *   - Middleware that must terminate early (e.g. CSRF failure → 403)
 *     does NOT call $next. Calling $next is optional; omitting it stops
 *     the pipeline.
 *
 * Extension Points:
 *   - All future middleware classes (CsrfMiddleware, AuthMiddleware,
 *     RoleMiddleware, etc.) implement this interface.
 *   - MiddlewarePipeline::wrap() verifies interface compliance via
 *     instanceof before dispatching (CORE-001 additive check).
 *
 * Scope:
 *   - This file is new in CORE-001. It does not modify any Sprint 0 file.
 *   - MiddlewarePipeline::wrap() receives one additive instanceof check
 *     (see MiddlewarePipeline.php @ref CORE-001).
 *
 * @package Inveetaire
 * @ref     DBP v1.1 Ch.4, SAD v1.1 Ch.5, SPRINT1_PLANNING.md §5, CORE-001
 */
interface MiddlewareInterface
{
    /**
     * Process the incoming request and, if appropriate, pass it to the next layer.
     *
     * Implementations must either:
     *   a) Call $next($request) to continue the middleware pipeline, or
     *   b) Terminate execution (send a response and return) without calling $next.
     *
     * @param Request  $request The current HTTP request object.
     * @param callable $next    The next middleware layer or controller action.
     *                          Signature: function(Request $request): void
     * @return void
     */
    public function handle(Request $request, callable $next): void;
}
