Merge pull request #1 from hankz1108/feat/exception-handler-and-service-provider

Feat/exception handler and service provider

Author: hankz1108

composer.json

@@ -1,7 +1,14 @@
 {
     "name": "hankz/laravel-plus-api",
+    "description": "Convenient Laravel API response tools and automated error handling functionality are provided.",
     "type": "library",
     "license": "MIT",
+    "keywords": [
+        "laravel",
+        "laravel-plus",
+        "api",
+        "response"
+    ],
     "autoload": {
         "psr-4": {
             "Hankz\\LaravelPlusApi\\": "src/"
@@ -14,9 +21,14 @@
         }
     ],
     "require": {
-        "php": "^7.4|^8.0"
+        "php": "^7.4|^8.0",
+        "laravel/framework": ">=7"
     },
-    "require-dev": {
-        "laravel/framework": "7"
+    "extra": {
+        "laravel": {
+            "providers": [
+                "Hankz\\LaravelPlusApi\\LaravelPlusApiServiceProvider"
+            ]
+        }
     }
-}
+}

config/plus-api.php config/laravel-plus-api.phpconfig/plus-api.php renamed to config/laravel-plus-api.php

@@ -1,5 +1,7 @@
 <?php
 
+use Illuminate\Http\Response;
+
 return [
     /*
     |--------------------------------------------------------------------------
@@ -32,15 +34,25 @@
 
     'default_response' => [
         'success' => [
-            'api_code' => 0,
-            'http_code' => 200,
+            'api_code' => 200,
+            'http_code' => Response::HTTP_OK,
             'message' => 'Success',
         ],
 
         'error' => [
-            'api_code' => 1,
-            'http_code' => 400,
-            'message' => 'Unknown error',
+            'api_code' => 500,
+            'http_code' => Response::HTTP_INTERNAL_SERVER_ERROR,
+            'message' => 'Unknown server error',
+        ],
+
+        'unauthenticated' => [
+            'api_code' => 401,
+            'http_code' => Response::HTTP_UNAUTHORIZED,
+            'message' => 'Unauthenticated',
         ],
-    ]
+
+        'validation_fail' => [
+            'api_code' => 422,
+        ],
+    ],
 ];

readme.md

@@ -0,0 +1,91 @@
+# Laravel Plus API
+
+Convenient Laravel API response tools and automated error handling functionality are provided.
+
+## Requirement
+
+- PHP ^7.4|^8.0
+- Laravel >= 7
+
+## Installation
+
+### 1. Composer install
+Run the Composer require command from the Terminal:
+```bash
+composer require hankz/laravel-plus-api
+```
+### 2. Setup
+This package supports Laravel's auto-discovery feature and it's ready to use once installed.
+
+### 3. Publishing the config file
+You need publish the config file.
+```bash
+php artisan vendor:publish --provider="Hankz\LaravelPlusApi\LaravelPlusApiServiceProvider
+```
+
+### 4. Set Middleware
+Set middleware for routes where you intend to utilize API responses.
+
+ in `app/Http/Kernel.php`
+```php
+'api' => [
+    //...
+
+    \Hankz\LaravelPlusApi\Middleware\SetHeaderAcceptJson::class,
+]
+```
+
+Set the priority of the middleware.
+
+in `app/Http/Kernel.php`
+```php
+protected $middlewarePriority = [
+    \Illuminate\Session\Middleware\StartSession::class,
+    \Illuminate\View\Middleware\ShareErrorsFromSession::class,
+    \Hankz\LaravelPlusApi\Middleware\SetHeaderAcceptJson::class,
+    \Hankz\LaravelPlusApi\Exceptions\ApiException::class,
+    \App\Http\Middleware\Authenticate::class,
+    \Illuminate\Routing\Middleware\ThrottleRequests::class,
+    \Illuminate\Session\Middleware\AuthenticateSession::class,
+    \Illuminate\Routing\Middleware\SubstituteBindings::class,
+    \Illuminate\Auth\Middleware\Authorize::class,
+];
+```
+
+### 5. Exception Handler
+Override exception Handler.
+
+in `app/Exceptions/Handler.php`，加入：
+```php
+use Illuminate\Auth\AuthenticationException;
+use Illuminate\Validation\ValidationException;
+use Symfony\Component\HttpFoundation\Response as HttpResponse;
+use Hankz\LaravelPlusApi\Classes\ApiResponseBuilder;
+
+class Handler extends ExceptionHandler
+{
+    use ApiResponse;
+
+    //...
+
+    protected function invalidJson($request, ValidationException $exception)
+    {
+        return ApiResponseBuilder::validationError($exception);
+    }
+
+    protected function unauthenticated($request, AuthenticationException $exception)
+    {
+        return $this->error(config('plus-api.default_response.error.http_code'), Response::HTTP_UNAUTHORIZED);
+    }
+
+    protected function prepareJsonResponse($request, Throwable $e)
+    {
+        return $this->exceptionError(
+            $this->convertExceptionToArray($e),
+            config('plus-api.default_response.error.http_code'),
+            $this->isHttpException($e) ? $e->getStatusCode() : Response::HTTP_INTERNAL_SERVER_ERROR,
+            $e->getMessage()
+            $this->isHttpException($e) ? $e->getHeaders() : []
+        );
+    }
+```

src/Exceptions/ApiException.php

@@ -0,0 +1,67 @@
+<?php
+
+namespace Hankz\LaravelPlusApi\Exceptions;
+
+use Exception;
+use Hankz\LaravelPlusApi\Traits\ApiResponse;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
+
+abstract class ApiException extends Exception implements HttpExceptionInterface
+{
+    use ApiResponse;
+
+    public const API_CODE = Response::HTTP_INTERNAL_SERVER_ERROR;
+
+    public const HTTP_CODE = Response::HTTP_INTERNAL_SERVER_ERROR;
+
+    /**
+     * message.
+     *
+     * @var string
+     */
+    protected $message;
+
+    /**
+     * data.
+     *
+     * @var object|array|null data
+     */
+    protected $data;
+
+    public function __construct(string $message = null, $data = null)
+    {
+        parent::__construct($message);
+
+        if (!is_null($message)) {
+            $this->message = $message;
+        }
+
+        if (!is_null($data)) {
+            $this->data = $data;
+        }
+    }
+
+    /**
+     * Report the exception.
+     */
+    public function report(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Render the exception into an HTTP response.
+     */
+    public function render(Request $request): JsonResponse
+    {
+        return $this->error(
+            static::API_CODE,
+            static::HTTP_CODE,
+            $this->message,
+            $this->data
+        );
+    }
+}

src/LaravelPlusApiServiceProvider.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Hankz\LaravelPlusApi;
+
+use Hankz\LaravelPlusApi\Classes\ApiResponseBuilder;
+use Illuminate\Support\ServiceProvider;
+
+class LaravelPlusApiServiceProvider extends ServiceProvider
+{
+    /**
+     * Register any package services.
+     *
+     * @return void
+     */
+    public function register()
+    {
+        $this->mergeConfigFrom(__DIR__ . '/../config/laravel-plus-api.php', 'laravel-plus-api');
+    }
+
+    /**
+     * Get the services provided by the provider.
+     *
+     * @return array
+     */
+    public function provides()
+    {
+        return [ApiResponseBuilder::class];
+    }
+}

src/Middleware/SetHeaderAcceptJson.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Hankz\LaravelPlusApi\Middleware;
+
+use Closure;
+
+class SetHeaderAcceptJson
+{
+    /**
+     * Handle an incoming request.
+     *
+     * @param Illuminate\Http\Request $request
+     */
+    public function handle($request, Closure $next)
+    {
+        $request->headers->set('Accept', 'application/json');
+
+        return $next($request);
+    }
+}

src/Traits/ApiResponse.php

@@ -4,6 +4,7 @@
 
 use Hankz\LaravelPlusApi\Classes\ApiResponseBuilder;
 use Illuminate\Http\JsonResponse;
+use Illuminate\Validation\ValidationException;
 
 trait ApiResponse
 {
@@ -37,21 +38,52 @@ public static function success(
      * Builds error Response object. Supports optional arguments passed to Lang::get() if associated error
      * message uses placeholders as well as return data payload.
      *
-     * @param string      $apiCode  your API code to be returned with the response object
-     * @param string|null $message  error message
-     * @param int|null    $httpCode HTTP code to be used for HttpResponse sent or @null
-     *                              for default DEFAULT_HTTP_CODE_ERROR
-     * @param int|null    $headers  Http Header
+     * @param string            $apiCode  your API code to be returned with the response object
+     * @param string|null       $message  error message
+     * @param int|null          $httpCode HTTP code to be used for HttpResponse sent or @null
+     *                                    for default DEFAULT_HTTP_CODE_ERROR
+     * @param object|array|null $data     array of primitives and supported objects to be returned in 'data' node
+     * @param int|null          $headers  Http Header
      */
     public static function error(
         string $apiCode,
-        string $message = null,
         int $httpCode = null,
+        string $message = null,
+        $data = null,
         array $headers = null
     ): JsonResponse {
         return ApiResponseBuilder::asError($apiCode)
             ->withMessage($message)
             ->withHttpCode($httpCode)
+            ->withData($data)
+            ->withHttpHeaders($headers)
+            ->build();
+    }
+
+    /**
+     * return validation error response.
+     */
+    public static function validationError(ValidationException $e): JsonResponse
+    {
+        return ApiResponseBuilder::asError(config('plus-api.default_response.validation_fail.api_code'))
+            ->withErrors($e->errors())
+            ->withHttpCode($e->status)
+            ->build();
+    }
+
+    public static function exceptionError(
+        array $debug_data = null,
+        string $apiCode = null,
+        int $httpCode,
+        string $message = null,
+        array $headers = []
+    ): JsonResponse {
+        $apiCode = $apiCode ?? config('plus-api.default_response.error.api_code');
+
+        return ApiResponseBuilder::asError($apiCode)
+            ->withDebugData($debug_data)
+            ->withHttpCode($httpCode)
+            ->withMessage($message)
             ->withHttpHeaders($headers)
             ->build();
     }