# Laravel API Response Helpers: one trait for consistent JSON responses

> Laravel API Response Helpers is a small MIT licensed package that gives a Laravel controller a trait with one method per HTTP status, so error responses stop taking four different shapes. It requires PHP 8.2 and Laravel 12 or 13, and it is meant to sit alongside Laravel's own API resources rather than replace them.

**f9webltd/laravel-api-response-helpers** — :rocket: A simple package allowing for consistent API responses throughout your Laravel application

- Repository: https://github.com/f9webltd/laravel-api-response-helpers
- Stars: 647 · Forks: 51
- Language: PHP
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/f9webltd-laravel-api-response-helpers

## The problem it was written to solve

The README's motivation section is the most useful part of the documentation, because it describes a real codebase rather than an ideal one. The goal is to ensure consistent JSON API responses throughout an application, and the motivation was primarily based on a very old inherited Laravel project. That project contained a plethora of methods and structures used to return an error, and the README lists four of them.

```php
- `response()->json(['error' => $error], 400)`
- `response()->json(['data' => ['error' => $error], 400)`
- `response()->json(['message' => $error], Response::HTTP_BAD_REQUEST)`
- `response()->json([$error], 400)`
```

Four different envelopes for the same condition, spread across the codebase. The author's response was to add a single trait that kept this consistent, in this case a call to respondError with the message. That is the whole product, and saying so plainly is a strength rather than a weakness, because a developer can see in ten seconds whether it fits their situation.

## The method list, which is really the API contract

The available methods are the specification of what you get, and the README lists them with their status codes. There is respondNotFound taking a string or an exception and an optional key, returning 404. There is respondWithSuccess accepting an array, an Arrayable, a JsonSerializable or null and returning 200, and by default returning a success flag set to true. There is respondOk returning 200 with a message, respondUnAuthenticated returning 401, respondForbidden returning 403, respondError returning 400, respondCreated returning 201 with optional data, respondNoContent returning 204 with an empty body as the README notes per RFC 9110, respondAccepted returning 202 with optional data, respondConflict returning 409 with an optional message and a default when omitted, and respondTooManyRequests returning 429 with the same optional message behaviour. The error methods all take an optional key that defaults to error, which is how you localise or reshape the error field.

## Installing it and using the trait in a controller

Installation is one Composer command, and the trait is then referenced inside a controller.

```bash
composer require f9webltd/laravel-api-response-helpers
```

```php
<?php

namespace App\Http\Api\Controllers;

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

class OrdersController
{
    use ApiResponseHelpers;

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

The README also notes that the trait can optionally be imported within a base controller, which is the natural place for it if you have one. The requirements are PHP 8.2 and Laravel 12.0 or 13.0, and the package says it supports actively supported Laravel releases under the official Laravel support policy. The trait lives in the F9Web namespace, so the import is F9Web\ApiResponseHelpers, which is worth noting because the package name and the namespace do not match.

## setDefaultSuccessResponse, and the fluent alternative

One method is more interesting than the rest. setDefaultSuccessResponse optionally replaces the default success payload returned by respondWithSuccess with content of your choosing, and the README says it can be called from the constructor to change the default for all calls, from a base API controller, or wherever it is required. It is fluent, returning the same instance so calls can be chained.

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

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

The alternative to that is to set the default once in the constructor, and the README shows that form too, with the same collection passed to respondWithSuccess afterwards. The reason to prefer the constructor form is that it applies everywhere, while the chained form applies to one call site. Which you want depends on whether your API has one envelope or several.

## What you can pass in, and where API resources still belong

The package accepts more than a plain PHP array. Besides an array you can pass objects implementing the Laravel Arrayable contract and objects implementing the native PHP JsonSerializable contract, and the README says this allows a variety of object types to be passed and converted automatically. It gives three common examples: a Laravel collection built with collect, an Eloquent collection such as a filtered query result, and a Laravel API resource. There is also a clear statement of scope about that last one. This package is intended to be used alongside Laravel's API resources and in no way replaces them, and the example builds a resource and passes it to respondCreated, which returns a 201 with the resource as the payload. That boundary is the one to hold on to, because the temptation with a helper like this is to start shaping payloads inside the trait, and then the resource layer stops being the place where a response's structure is defined.

## Version compatibility, and the legacy branches

The package publishes four lines of support, and the README is precise about which is which. The current line needs PHP 8.2 and Laravel 12.0 or 13.0. For PHP 8.2 with Laravel 11.0 you use version 3.1. For PHP 8.0 with Laravel 8.0, 9.0 and 10.0 you use version 2.1.1. For PHP 7.4 with Laravel 6.0 or 7.0 you use version 1.5. The repository is not archived, the last push was on 2026-06-20, and the recent releases are 4.0.0 from that date, 3.1.0 from 2026-05-31 and 3.0.1 from 2026-02-22. The upgrade path itself is documented separately in UPGRADING.md. The MIT licence permits commercial use, provided the copyright and licence notice are kept, which is the other piece of the calculation for anyone weighing it against writing the same few methods themselves.

## The limits, and the alternative to weigh

Three things to weigh. The first is that the envelope is fixed by the trait, and the methods cover the common statuses but not everything, so a response shape outside the list still needs hand work, and the README does not list a paginated helper, which is the one most Laravel APIs need. The second is that the default success payload is a success flag, which is thin for an API that wants a data envelope, and the fix is the setDefaultSuccessResponse call, which means every base controller has to remember it. The third is the testing and tooling surface. The README says the tests run with composer test, and the repository carries phpunit.xml.dist, an .editorconfig, a SECURITY.md and a .github/ directory with a test workflow badge, so the package is maintained, but it is a single trait with no release automation described beyond the tagged versions. The alternative to weigh is writing the same methods into your own base controller, which takes an hour and gives you full control over the envelope, or using a full response contract library if your API has more than one frontend and needs a shared schema. The trait wins when the problem is exactly the one described in the motivation section, and loses when consistency is a design decision rather than a cleanup.

## Conclusion

Adopt Laravel API Response Helpers if you maintain a Laravel API where each controller hand-rolls its error JSON and you want the shape fixed without rewriting your controllers. Do not adopt it if your project already has a response contract, a formatter or a shared resource layer, because a trait that sets the envelope for every controller is a decision you then have to keep. Before you install, read UPGRADING.md, because the package is at 4.0.0 and the legacy branches exist for older PHP and Laravel combinations. Check that your Laravel version is 12 or 13 and your PHP is 8.2 or newer, and pick the branch that matches if you are on an older stack.

## FAQ

### What does Laravel API Response Helpers do?

It is a simple package allowing for consistent API responses throughout a Laravel application. You reference the ApiResponseHelpers trait in a controller and then call one method per HTTP status, such as respondWithSuccess, respondError or respondNotFound, instead of hand-writing response()->json calls.

### What are the requirements for Laravel API Response Helpers?

The current version requires PHP 8.2 and Laravel 12.0 or 13.0, and the package says it supports actively supported Laravel releases under the official Laravel support policy. Older PHP and Laravel combinations are served by the legacy 3.1, 2.1.1 and 1.5 branches.

### Which HTTP status codes does the Laravel API Response Helpers trait cover?

The README lists methods for 200, 201, 202, 204, 400, 401, 403, 404, 409 and 429, including respondWithSuccess, respondOk, respondCreated, respondAccepted, respondNoContent, respondError, respondUnAuthenticated, respondForbidden, respondNotFound, respondConflict and respondTooManyRequests.

### Does Laravel API Response Helpers replace Laravel API resources?

No. The README states the package is intended to be used alongside Laravel's API resources and in no way replaces them, and its example builds a resource with PostResource::make and passes it to respondCreated, which returns a 201 with that resource as the payload.

### How do I change the default success response in Laravel API Response Helpers?

Call setDefaultSuccessResponse, optionally with content of your own, which replaces the default success payload returned by respondWithSuccess. The README says it can be called from the constructor to change the default for all calls, from a base API controller, or wherever required, and it returns the same instance so it can be chained onto respondWithSuccess.

## Sources

- [f9webltd/laravel-api-response-helpers on GitHub](https://github.com/f9webltd/laravel-api-response-helpers)
- [Issues](https://github.com/f9webltd/laravel-api-response-helpers/issues)
- [License: MIT](https://github.com/f9webltd/laravel-api-response-helpers/blob/master/LICENSE)
- [README](https://github.com/f9webltd/laravel-api-response-helpers/blob/master/README.md)
- [Releases](https://github.com/f9webltd/laravel-api-response-helpers/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/f9webltd-laravel-api-response-helpers