README

Laravel API Response

Laravel and Lumen API response transformer/formatter.

Requirements

• PHP ^7.4 | ^8.0
• Laravel 7, 8, 9 or 10

Installation

Via Composer

$ composer require raditzfarhan/laravel-api-response

Configuration

The Laravel and Lumen configurations vary slightly, so here are the instructions for each of the frameworks.

Laravel

Edit the config/app.php file and add the following line to register the service provider:

'providers' => [
    ...
    RaditzFarhan\ApiResponse\ApiResponseServiceProvider::class,
    ...
],

Tip: If you're on Laravel version 5.5 or higher, you can skip this part of the setup in favour of the Auto-Discovery feature.

Lumen

Edit the bootstrap/app.php file and add the following line to register the service provider:

...
$app->register(RaditzFarhan\ApiResponse\ApiResponseServiceProvider::class);
...

You will also need to enable Facades in bootstrap/app.php:

..
$app->withFacades(true, [
    RaditzFarhan\ApiResponse\Facades\ApiResponse::class => 'ApiResponse'
]);
...

Usage

Example usage as below snippet:

// Success response

// using service container
$response = app('ApiResponse')->success();

// using alias
$response = \ApiResponse::success();

// Failed response
$response = \ApiResponse::failed();

The response will return a Illuminate\Http\Response instance just like when u call response() helper method.

By default, success will use http 200 code if not set, and failed will use http 500 code if not set.

Typical response content as follow:

Success

{
    "status": true,
    "http_code": 200,
    "message": "Success."
}

Failed

{
    "status": false,
    "http_code": 500,
    "message": "Failed."
}

Add/Change payload data by chaining more methods as below:

// Example #1
return ApiResponse::httpCode(201)->message('Created new record!')->data(['name' => 'Raditz Farhan', 'country' => 'MY'])->success();

// or can be shorten to
return ApiResponse::created(['name' => 'Raditz Farhan', 'country' => 'MY']);

// Example #2
return ApiResponse::httpCode(422)->message('Validation error!')->errors(['name' => ['Name field is required.']])->failed();

// or can be shorten to
return ApiResponse::validationError(['name' => ['Name field is required.']]);

Above call will result in below:

Example #1

{
    "status": true,
    "http_code": 201,
    "message": "Created new record!",
    "data": {
        "name": "Raditz Farhan",
        "country": "MY"
    }    
}

Example #2

{
    "status": false,
    "http_code": 422,
    "message": "Validation error!",
    "errors": {
        "name": [
            "Name field is required."
        ]
    },
}

Use collection method to return paginate result that includes meta and links attribute:

return ApiResponse::collection(App\Post::paginate());

Will return below result:

{
  "status": true,
  "http_code": 200,
  "message": "Success.",
  "data": [
    {
      "id": 1,
      "title": "First post",
      "slug": "first-post",
      "content": "This is the first post",
      "sort_order": 1,
      "created_at": "2020-04-21T13:40:45.000000Z",
      "updated_at": "2020-04-21T13:40:45.000000Z"
    },
    ...
  ],
  "meta": {
    "currenct_page": 1,
    "last_page": 3,
    "from": 1,
    "to": 25,
    "per_page": 25,
    "total": 60,
    "has_more_pages": true
  },
  "links": {
    "first": "http://your-app-url?page=1",
    "last": "http://your-app-url?page=3",
    "prev": null,
    "next": "http://your-app-url?page=2"
  }
}

Besides created and validationError, below shorthand methods are available for your convenience:

// return http 400 Bad request error.
return ApiResponse::badRequest('Optional message here'); 

// return http 401 Unauthorized error.
return ApiResponse::unauthorized(); 

// return http 403 Forbidden error.
return ApiResponse::forbidden(); 

// return http 404 Not found error.
return ApiResponse::notFound(); 

// return http 500 Internal server error.
return ApiResponse::internalServerError(); 

Tip: Pass a message to the method to put your own custom message.

Change log

Please see the changelog for more information on what has changed recently.

Credits

• Raditz Farhan

License

MIT. Please see the license file for more information.