bootstrap/app.php

<?php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;
use App\Shared\Exceptions\ApiException;
use App\Shared\Exceptions\ValidationExceptionMapper;
use App\Http\Middleware\AuthenticateAccessToken;
use App\Http\Middleware\RequirePermission;
use App\Http\Middleware\RequirePortal;
use App\Shared\Http\ApiResponse;
use App\Shared\Http\RequestIdMiddleware;
use Illuminate\Http\Middleware\HandleCors;
use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
        apiPrefix: 'api/v1',
    )
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->prepend([
            HandleCors::class,
            RequestIdMiddleware::class,
        ]);
        $middleware->alias([
            'mdn.auth' => AuthenticateAccessToken::class,
            'mdn.permission' => RequirePermission::class,
            'mdn.portal' => RequirePortal::class,
        ]);
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        $exceptions->shouldRenderJsonWhen(
            fn (Request $request) => $request->is('api/*'),
        );

        $exceptions->render(function (ApiException $exception, Request $request) {
            if (! $request->is('api/*')) {
                return null;
            }

            return ApiResponse::error(
                $exception->apiCode(),
                $exception->getMessage(),
                $exception->details(),
                $exception->status(),
            );
        });

        $exceptions->render(function (ValidationException $exception, Request $request) {
            if (! $request->is('api/*')) {
                return null;
            }

            return ApiResponse::error(
                'VALIDATION_FAILED',
                'The request payload is invalid.',
                ValidationExceptionMapper::details($exception),
                422,
            );
        });

        $exceptions->render(function (NotFoundHttpException $exception, Request $request) {
            if (! $request->is('api/*')) {
                return null;
            }

            return ApiResponse::error('NOT_FOUND', 'The requested endpoint was not found.', [], 404);
        });

        $exceptions->render(function (\Throwable $exception, Request $request) {
            if (! $request->is('api/*')) {
                return null;
            }

            if ($exception instanceof HttpExceptionInterface) {
                return ApiResponse::error(
                    'HTTP_ERROR',
                    $exception->getMessage() ?: 'The request could not be completed.',
                    [],
                    $exception->getStatusCode(),
                );
            }

            return ApiResponse::error(
                'INTERNAL_SERVER_ERROR',
                'An unexpected error occurred.',
                [],
                500,
            );
        });
    })->create();