wip

README.md

@@ -1,39 +1,90 @@
-# Laravel API Response (Next version)
+# Laravel API Response v2
 
-> This version is still WORK IN PROGRESS.
+A helper package to return JSON Api Response in structured way.
 
-This package aims to help you standardize all your API responses in
-a simple and structured way.
-
-By default, the structure of the API response will look like this:
+By default, the structure of the response will look like this:
 
 ```jsonc
 {
   "success": true, // it was successfull or not
   "title": "Users", // the title/headline/section 
-  "message": "Active users only", // the message/description/hightlight
-  "data": [ // if it was successfull
+  "message": "Active users only", // the message/description/highlight
+  "data": { // if it was successfull
     // profile..
     // users..
     // products..
     // etc..
-  ],
-  "errors": [ // if it was not successfull
+  },
+  "errors": { // if it was not successfull
     // validation errors..
     // any other errors..
-  ]
+  }
+}
+```
+
+Example:
+
+```jsonc
+{
+  "success": true,
+  "title": "Users",
+  "message": "Succesfully create a user",
+  "data": {
+    "id": 1,
+    "name": "John Doe",
+    "address": "4th Semarang Raya",
+  },
 }
 ```
 
 ## Install
 
 ```sh
-$ composer require kodepandai/laravel-api-response:^2
+$ composer require kodepandai/laravel-api-response:^2.0
+```
+
+**Requirements:**
+* PHP ^8.1
+* Laravel ^10.0
+
+After installation, register api response handler in `app/Exceptions/Handler.php`
+
+```php
+use KodePandai\ApiResponse\ApiExceptionHandler;
+
+class Handler extends ExceptionHandler
+{
+    protected $dontReport = [
+        \KodePandai\ApiResponse\Exceptions\ApiException::class,
+        \KodePandai\ApiResponse\Exceptions\ApiValidationException::class,
+    ];
+
+    public function register()
+    {
+        $this->renderable(function (Throwable $e, Request $request) {
+            if ($request->wantsJson() || $request->is('*api*')) {
+                return ApiExceptionHandler::render($e, $request);
+            }
+        });
+    }
+}
+```
+
+The above handler will automatically transform any exception and render as ApiResponse.
+
+## Config
+
+Publish config file using vendor:publish command
+
+```sh
+$ php artisan vendor:publish --tag=api-response-config
 ```
 
 ## Usage
 
-TODO: complete this documentation, simplify the wordings.
+### Return Response
+
+### Throw Exception
 
 ## Develop
 

composer.json

@@ -14,7 +14,7 @@
     "laravel/framework": "^9.0|^10.0|^11.0"
   },
   "require-dev": {
-    "orchestra/testbench": "^7.0|^8.0",
+    "orchestra/testbench": "^7.0|^8.0|^9.0",
     "pestphp/pest": "1.0|^2.0",
     "pestphp/pest-plugin-laravel": "^1.0|^2.0"
   },

config/api-response.php

@@ -1,9 +1,6 @@
 <?php
 
-use Illuminate\Auth\AuthenticationException;
-use Illuminate\Database\Eloquent\ModelNotFoundException;
 use Illuminate\Http\Response;
-use Illuminate\Validation\ValidationException;
 
 return [
 
@@ -18,16 +15,16 @@
      * - return ApiResponse::error()..
      * - throw new ApiException('error')..
      */
-    'error_status_code' => \Illuminate\Http\Response::HTTP_INTERNAL_SERVER_ERROR,
+    'error_status_code' => Response::HTTP_INTERNAL_SERVER_ERROR,
 
     /**
      * List of exception status codes.
      * Override the default status code with custom one.
      */
     'exception_status_codes' => [
-        AuthenticationException::class => Response::HTTP_UNAUTHORIZED,
-        ModelNotFoundException::class => Response::HTTP_NOT_FOUND,
-        ValidationException::class => Response::HTTP_UNPROCESSABLE_ENTITY,
+        \Illuminate\Auth\AuthenticationException::class => Response::HTTP_UNAUTHORIZED,
+        \Illuminate\Database\Eloquent\ModelNotFoundException::class => Response::HTTP_NOT_FOUND,
+        \Illuminate\Validation\ValidationException::class => Response::HTTP_UNPROCESSABLE_ENTITY,
     ],
 
     /**
@@ -46,9 +43,9 @@
          * *Set to false to not show in all status codes.
          */
         'show_traces_in_codes' => [
-            \Illuminate\Http\Response::HTTP_BAD_GATEWAY,
-            \Illuminate\Http\Response::HTTP_BAD_REQUEST,
-            \Illuminate\Http\Response::HTTP_INTERNAL_SERVER_ERROR,
+            Response::HTTP_BAD_GATEWAY,
+            Response::HTTP_BAD_REQUEST,
+            Response::HTTP_INTERNAL_SERVER_ERROR,
         ],
 
         /**

src/Facades/ApiResponse.php

@@ -14,6 +14,7 @@
  * @method static \KodePandai\ApiResponse\ApiResponse forbidden(mixed $errors = [])
  * @method static \KodePandai\ApiResponse\ApiResponse badRequest(mixed $errors = [])
  * @method static \KodePandai\ApiResponse\ApiResponse invalid(string $key, string|array $messages)
+ * @method static \KodePandai\ApiResponse\ApiResponse validateOrFail(array $rules, array $messages, array $customAttributes, ?\Illuminate\Http\Request $request): array
  * @method \KodePandai\ApiResponse\ApiResponse statusCode(int $code)
  * @method \KodePandai\ApiResponse\ApiResponse successful()
  * @method \KodePandai\ApiResponse\ApiResponse notSuccessful()