Looking at how we respond as an api

Author: JustSteveKing

app/Enum/Error.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enum;
+
+enum Error: string
+{
+    case AUTH_001 = 'https://docs.api.com/errors/auth_001';
+    case AUTH_002 = 'https://docs.api.com/errors/auth_002';
+    case AUTH_003 = 'https://docs.api.com/errors/auth_003';
+    case AUTH_004 = 'https://docs.api.com/errors/auth_004';
+}

app/Exceptions/Handler.php

@@ -7,44 +7,22 @@
 use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
 use Throwable;
 
-class Handler extends ExceptionHandler
+final class Handler extends ExceptionHandler
 {
-    /**
-     * A list of exception types with their corresponding custom log levels.
-     *
-     * @var array<class-string<\Throwable>, \Psr\Log\LogLevel::*>
-     */
-    protected $levels = [
-        //
-    ];
+    protected $levels = [];
 
-    /**
-     * A list of the exception types that are not reported.
-     *
-     * @var array<int, class-string<\Throwable>>
-     */
-    protected $dontReport = [
-        //
-    ];
+    protected $dontReport = [];
 
-    /**
-     * A list of the inputs that are never flashed to the session on validation exceptions.
-     *
-     * @var array<int, string>
-     */
     protected $dontFlash = [
         'current_password',
         'password',
         'password_confirmation',
     ];
 
-    /**
-     * Register the exception handling callbacks for the application.
-     */
     public function register(): void
     {
         $this->reportable(function (Throwable $e) {
-            //
+            dd($e);
         });
     }
 }

app/Http/Controllers/FallbackController.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers;
+
+use App\Enum\Error;
+use App\Http\Responses\ApiErrorResponse;
+use Illuminate\Http\Request;
+use JustSteveKing\StatusCode\Http;
+
+final class FallbackController
+{
+    public function __invoke(Request $request)
+    {
+        return new ApiErrorResponse(
+            title: 'Oops',
+            description: 'Oops I broke something.',
+            code: Error::AUTH_001,
+            status: Http::I_AM_A_TEAPOT,
+        );
+    }
+}

app/Http/Kernel.php

@@ -4,6 +4,7 @@
 
 namespace App\Http;
 
+use App\Http\Middleware\JsonApiResponseMiddleware;
 use Illuminate\Foundation\Http\Kernel as HttpKernel;
 
 class Kernel extends HttpKernel
@@ -44,6 +45,7 @@ class Kernel extends HttpKernel
             \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
             \Illuminate\Routing\Middleware\ThrottleRequests::class.':api',
             \Illuminate\Routing\Middleware\SubstituteBindings::class,
+            JsonApiResponseMiddleware::class,
         ],
     ];
 

app/Http/Middleware/JsonApiResponseMiddleware.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+final class JsonApiResponseMiddleware
+{
+    /**
+     * Handle an incoming request.
+     *
+     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
+     */
+    public function handle(Request $request, Closure $next): Response
+    {
+        /**
+         * @var Response $response
+         */
+        $response = $next($request);
+
+        $response->headers->set(
+            key: 'Content-Type',
+            values: 'application/vnd.api+json',
+        );
+
+        return $response;
+    }
+}

app/Http/Responses/ApiErrorResponse.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Responses;
+
+use App\Enum\Error;
+use Illuminate\Contracts\Support\Responsable;
+use Illuminate\Http\JsonResponse;
+use JustSteveKing\StatusCode\Http;
+use Symfony\Component\HttpFoundation\Response;
+
+final readonly class ApiErrorResponse implements Responsable
+{
+    public function __construct(
+        private string $title,
+        private string $description,
+        private Error $code,
+        private Http $status = Http::INTERNAL_SERVER_ERROR,
+    ) {}
+
+    public function toResponse($request): Response
+    {
+        return new JsonResponse(
+            data: [
+                'title' => $this->title,
+                'description' => $this->description,
+                'code' => $this->code->value,
+                'staus' => $this->status->value,
+            ],
+            status: $this->status->value,
+        );
+    }
+}

app/Providers/RouteServiceProvider.php

@@ -17,7 +17,7 @@ public function boot(): void
         $this->configureRateLimiting();
 
         $this->routes(function () {
-            Route::middleware('api')
+            Route::middleware(['api', 'treblle'])
                 ->as('api:')
                 ->group(
                     base_path('routes/api.php')

app/Services/Cache/StorageService.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Cache;
+
+use Closure;
+use Illuminate\Support\Facades\Cache;
+
+final class StorageService
+{
+     public function remember(string $key, Closure $callback, int $ttl = 3600): mixed
+     {
+         return Cache::remember(
+             key: $key,
+             ttl: $ttl,
+             callback: $callback,
+         );
+     }
+}

composer.json

@@ -12,7 +12,8 @@
         "laravel/framework": "^10.2",
         "laravel/sanctum": "^3.2.1",
         "laravel/tinker": "^2.8.1",
-        "timacdonald/json-api": "v1.0.0-beta.4"
+        "timacdonald/json-api": "v1.0.0-beta.4",
+        "treblle/treblle-laravel": "^2.8"
     },
     "require-dev": {
         "fakerphp/faker": "^1.21.0",