A simple package allowing for consistent API responses throughout your Laravel application. Originally created to solve issues having with a large legacy project, see the package motivation section.

• PHP ^8.2
• Laravel ^12.0 or ^13.0

The package supports actively supported Laravel releases as per the official Laravel Support Policy.

Legacy versions of this package support older PHP / Laravel version, see the legacy section.

composer require f9webltd/laravel-api-response-helpers

Simply reference the required trait within your controller:

<?php

namespace App\Http\Api\Controllers;

use F9Web\ApiResponseHelpers;
use Illuminate\Http\JsonResponse;

class OrdersController
{
    use ApiResponseHelpers;

    public function index(): JsonResponse
    {
        return $this->respondWithSuccess();
    }
}

Optionally, the trait can be imported within a base controller.

Returns a 404 HTTP status code, an exception object can optionally be passed.

Returns a 200 HTTP status code, optionally $contents to return as json can be passed. By default returns ['success' => true].

Returns a 200 HTTP status code

Returns a 401 HTTP status code

Returns a 403 HTTP status code

Returns a 400 HTTP status code

Returns a 201 HTTP status code, with response optional data

Returns a 204 HTTP status code, with an empty response body (RFC 9110)

Returns a 202 HTTP status code, with response optional data

Returns a 409 HTTP status code, with response optional message. If the message is omitted a default is sent

Returns a 429 HTTP status code, with response optional message. If the message is omitted a default is sent

Optionally, replace the default ['success' => true] response returned by respondWithSuccess with $content. This method can be called from the constructor (to change default for all calls), a base API controller or place when required.

setDefaultSuccessResponse is a fluent method returning $this allows for chained methods calls:

$users = collect([10, 20, 30, 40]);

return $this->setDefaultSuccessResponse([])->respondWithSuccess($users);

Or

public function __construct()
{
    $this->setDefaultSuccessResponse([]);
}

...

$users = collect([10, 20, 30, 40]);

return $this->respondWithSuccess($users);

In addition to a plain PHP array, the following data types can be passed to relevant methods:

• Objects implementing the Laravel Illuminate\Contracts\Support\Arrayable contract
• Objects implementing the native PHP JsonSerializable contract

This allows a variety of object types to be passed and converted automatically.

Below are a few common object types that can be passed.

$users = collect([10, 20, 30, 40]);

return $this->respondWithSuccess($users);

$invoices = Invoice::pending()->get();

return $this->respondWithSuccess($invoices);

This package is intended to be used alongside Laravel's API resources and in no way replaces them.

$resource = PostResource::make($post);

return $this->respondCreated($resource);

For PHP ^8.2 with Laravel ^11.0 support, use package version ^3.1.

For PHP ^8.0 with Laravel ^8.0, ^9.0 and ^10.0 support use package version ^2.1.1.

For PHP ^7.4 and Laravel ^6.0 / ^7.0 support, use package version ^1.5.

Ensure consistent JSON API responses throughout an application. The motivation was primarily based on a very old inherited Laravel project. The project contained a plethora of methods/structures used to return an error:

• response()->json(['error' => $error], 400)
• response()->json(['data' => ['error' => $error], 400)
• response()->json(['message' => $error], Response::HTTP_BAD_REQUEST)
• response()->json([$error], 400)
• etc.

I wanted to add a simple trait that kept this consistent, in this case:

$this->respondError('Ouch')

Please see UPGRADING for details.

Any ideas are welcome. Feel free to submit any issues or pull requests.

composer test

If you discover any security related issues, please email rob@f9web.co.uk instead of using the issue tracker.

• Rob Allport for F9 Web Ltd.
• All Contributors

The MIT License (MIT). Please see License File for more information.