Laravel Responder - a package for building API responses, integrating Fractal into Laravel and Lumen

Last update: May 22, 2022

Latest Stable Version Packagist Downloads Software License Build Status Code Quality Test Coverage Donate

Laravel Responder is a package for building API responses, integrating Fractal into Laravel and Lumen. It can transform your data using transformers, create and serialize success- and error responses, handle exceptions and assist you with testing your responses.

Table of Contents


Laravel lets you return models directly from a controller method to convert it to JSON. This is a quick way to build APIs but leaves your database columns exposed. Fractal, a popular PHP package from The PHP League, solves this by introducing transformers. However, it can be a bit cumbersome to integrate into the framework as seen below:

 public function index()
    $resource = new Collection(User::all(), new UserTransformer());

    return response()->json((new Manager)->createData($resource)->toArray());

Not that bad, but we all get a little spoiled by Laravel's magic. Wouldn't it be better if we could refactor it to:

public function index()
    return responder()->success(User::all())->respond();

The package will allow you to do this and much more. The goal has been to create a high-quality package that feels like native Laravel. A package that lets you embrace the power of Fractal, while hiding it behind beautiful abstractions. There has also been put a lot of focus and thought to the documentation. Happy exploration!


This package requires:

  • PHP 7.0+
  • Laravel 5.1+ or Lumen 5.1+


To get started, install the package through Composer:

composer require flugger/laravel-responder


Register Service Provider

Append the following line to the providers key in config/app.php to register the package:


The package supports auto-discovery, so if you use Laravel 5.5 or later you may skip registering the service provider and facades as they will be registered automatically.

Register Facades (optional)

If you like facades, you may also append the Responder and Transformation facades to the aliases key:

'Responder' => Flugg\Responder\Facades\Responder::class,
'Transformation' => Flugg\Responder\Facades\Transformation::class,

Publish Package Assets (optional)

You may additionally publish the package configuration and language file using the vendor:publish Artisan command:

php artisan vendor:publish --provider="Flugg\Responder\ResponderServiceProvider"

This will publish a responder.php configuration file in your config folder. It will also publish an errors.php file inside your lang/en folder which can be used for storing error messages.


Register Service Provider

Add the following line to app/bootstrap.php to register the package:


Register Facades (optional)

You may also add the following lines to app/bootstrap.php to register the facades:

class_alias(Flugg\Responder\Facades\Responder::class, 'Responder');
class_alias(Flugg\Responder\Facades\Transformation::class, 'Transformation');

Publish Package Assets (optional)

Seeing there is no vendor:publish command in Lumen, you will have to create your own config/responder.php file if you want to configure the package.


This documentation assumes some knowledge of how Fractal works.

Creating Responses

The package has a Responder service class, which has a success and error method to build success- and error responses respectively. To use the service and begin creating responses, pick one of the options below:

Option 1: Inject Responder Service

You may inject the Flugg\Responder\Responder service class directly into your controller methods:

public function index(Responder $responder)
    return $responder->success();

You can also use the error method to create error responses:

return $responder->error();

Option 2: Use responder Helper

If you're a fan of Laravel's response helper function, you may like the responder helper function:

return responder()->success();
return responder()->error();

Option 3: Use Responder Facade

Optionally, you may use the Responder facade to create responses:

return Responder::success();
return Responder::error();

Option 4: Use MakesResponses Trait

Lastly, the package provides a Flugg\Responder\Http\MakesResponses trait you can use in your controllers:

return $this->success();
return $this->error();

Which option you pick is up to you, they are all equivalent, the important thing is to stay consistent. The helper function (option 2) will be used for the remaining of the documentation.

Building Responses

The success and error methods return a SuccessResponseBuilder and ErrorResponseBuilder respectively, which both extend an abstract ResponseBuilder, giving them common behaviors. They will be converted to JSON when returned from a controller, but you can explicitly create an instance of Illuminate\Http\JsonResponse with the respond method:

return responder()->success()->respond();
return responder()->error()->respond();

The status code is set to 200 by default, but can be changed by setting the first parameter. You can also pass a list of headers as the second argument:

return responder()->success()->respond(201, ['x-foo' => true]);
return responder()->error()->respond(404, ['x-foo' => false]);

Consider always using the respond method for consistency's sake.

Casting Response Data

Instead of converting the response to a JsonResponse using the respond method, you can cast the response data to a few other types, like an array:

return responder()->success()->toArray();
return responder()->error()->toArray();

You also have a toCollection and toJson method at your disposal.

Decorating Response

A response decorator allows for last minute changes to the response before it's returned. The package comes with two response decorators out of the box adding a status and success field to the response output. The decorators key in the configuration file defines a list of all enabled response decorators:

'decorators' => [

You may disable a decorator by removing it from the list, or add your own decorator extending the abstract class Flugg\Responder\Http\Responses\Decorators\ResponseDecorator. You can also add additional decorators per response:

return responder()->success()->decorator(ExampleDecorator::class)->respond();
return responder()->error()->decorator(ExampleDecorator::class)->respond();

The package also ships with some situational decorators disabled by default, but which can be added to the decorator list:

  • PrettyPrintDecorator decorator will beautify the JSON output;
  • EscapeHtmlDecorator decorator, based on the "sanitize input, escape output" concept, will escape HTML entities in all strings returned by your API. You can securely store input data "as is" (even malicious HTML tags) being sure that it will be outputted as un-harmful strings. Note that, using this decorator, printing data as text will result in the wrong representation and you must print it as HTML to retrieve the original value.

Creating Success Responses

As briefly demonstrated above, success responses are created using the success method:

return responder()->success()->respond();

Assuming no changes have been made to the configuration, the above code would output the following JSON:

    "status": 200,
    "success": true,
    "data": null

Setting Response Data

The success method takes the response data as the first argument:

return responder()->success(Product::all())->respond();

It accepts the same data types as you would normally return from your controllers, however, it also supports query builder and relationship instances:

return responder()->success(Product::where('id', 1))->respond();
return responder()->success(Product::first()->shipments())->respond();

The package will run the queries and convert them to collections behind the scenes.

Transforming Response Data

The response data will be transformed with Fractal if you've attached a transformer to the response. There are two ways to attach a transformer; either explicitly by setting it on the response, or implicitly by binding it to a model. Let's look at both ways in greater detail.

Setting Transformer On Response

You can attach a transformer to the response by sending a second argument to the success method. For instance, below we're attaching a simple closure transformer, transforming a list of products to only output their names:

return responder()->success(Product::all(), function ($product) {
    return ['name' => $product->name];

You may also transform using a dedicated transformer class:

return responder()->success(Product::all(), ProductTransformer::class)->respond();
return responder()->success(Product::all(), new ProductTransformer)->respond();

You can read more about creating dedicated transformer classes in the Creating Transformers chapter.

Binding Transformer To Model

If no transformer is set, the package will search the response data for an element implementing the Flugg\Responder\Contracts\Transformable interface to resolve a transformer from. You can take use of this by implementing the Transformable interface in your models:

class Product extends Model implements Transformable {}

You can satisfy the contract by adding a transformer method that returns the corresponding transformer:

 * Get a transformer for the class.
 * @return \Flugg\Responder\Transformers\Transformer|string|callable
public function transformer()
    return ProductTransformer::class;

You're not limited to returning a class name string, you can return a transformer instance or closure transformer, just like the second parameter of the success method.

Instead of implementing the Transformable contract for all models, an alternative approach is to bind the transformers using the bind method on the TransformerResolver class. You can place the code below within AppServiceProvider or an entirely new TransformerServiceProvider:

use Flugg\Responder\Contracts\Transformers\TransformerResolver;

public function boot()
        \App\Product::class => \App\Transformers\ProductTransformer::class,
        \App\Shipment::class => \App\Transformers\ShipmentTransformer::class,

After you've bound a transformer to a model you can skip the second parameter and still transform the data:

return responder()->success(Product::all())->respond();

As you might have noticed, unlike Fractal, you don't need to worry about creating resource objects like Item and Collection. The package will make one for you based on the data type, however, you may wrap your data in a resource object to override this.

Setting Resource Key

If the data you send into the response is a model or contains a list of models, a resource key will implicitly be resolved from the model's table name. You can overwrite this by adding a getResourceKey method to your model:

public function getResourceKey(): string {
    return 'products';

You can also explicitly set a resource key on a response by sending a third argument to the ´success` method:

return responder()->success(Product::all(), ProductTransformer::class, 'products')->respond();

Paginating Response Data

Sending a paginator to the success method will set pagination meta data and transform the data automatically, as well as append any query string parameters to the paginator links.

return responder()->success(Product::paginate())->respond();

Assuming there are no products and the default configuration is used, the JSON output would look like:

    "success": true,
    "status": 200,
    "data": [],
    "pagination": {
        "total": 0,
        "count": 0,
        "perPage": 15,
        "currentPage": 1,
        "totalPages": 1,
        "links": []

Setting Paginator On Response

Instead of sending a paginator as data, you may set the data and paginator seperately, like you traditionally would with Fractal. You can manually set a paginator using the paginator method, which expects an instance of League\Fractal\Pagination\IlluminatePaginatorAdapter:

$paginator = Product::paginate();
$adapter = new IlluminatePaginatorAdapter($paginator);

return responder()->success($paginator->getCollection())->paginator($adapter)->respond();

Setting Cursor On Response

You can also set cursors using the cursor method, expecting an instance of League\Fractal\Pagination\Cursor:

if ($request->has('cursor')) {
    $products = Product::where('id', '>', request()->cursor)->take(request()->limit)->get();
} else {
    $products = Product::take(request()->limit)->get();

$cursor = new Cursor(request()->cursor, request()->previous, $products->last()->id ?? null, Product::count());

return responder()->success($products)->cursor($cursor)->respond();

Including Relationships

If a transformer class is attached to the response, you can include relationships using the with method:

return responder()->success(Product::all())->with('shipments')->respond();

You can send multiple arguments and specify nested relations using dot notation:

return responder()->success(Product::all())->with('shipments', 'orders.customer')->respond();

All relationships will be automatically eager loaded, and just like you would when using with or load to eager load with Eloquent, you may use a callback to specify additional query constraints. Like in the example below, where we're only including related shipments that hasn't yet been shipped:

return responder()->success(Product::all())->with(['shipments' => function ($query) {

Including From Query String

Relationships are loaded from a query string parameter if the load_relations_parameter configuration key is set to a string. By default, it's set to with, allowing you to automatically include relations from the query string:

GET /products?with=shipments,orders.customer

Excluding Default Relations

In your transformer classes, you may specify relations to automatically load. You may disable any of these relations using the without method:

return responder()->success(Product::all())->without('comments')->respond();

Filtering Transformed Data

The technique of filtering the transformed data to only return what we need is called sparse fieldsets and can be specified using the only method:

return responder()->success(Product::all())->only('id', 'name')->respond();

When including relationships, you may also want to filter fields on related resources as well. This can be done by instead specifying an array where each key represents the resource keys for the resources being filtered

return responder()->success(Product::all())->with('shipments')->only([
    'products' => ['id', 'name'],
    'shipments' => ['id']

Filtering From Query String

Fields will automatically be filtered if the filter_fields_parameter configuration key is set to a string. It defaults to only, allowing you to filter fields from the query string:

GET /products?only=id,name

You may automatically filter related resources by setting the parameter to a key-based array:

GET /products?with=shipments&only[products]=id,name&only[shipments]=id

Adding Meta Data

You may want to attach additional meta data to your response. You can do this using the meta method:

return responder()->success(Product::all())->meta(['count' => Product::count()])->respond();

When using the default serializer, the meta data will simply be appended to the response array:

    "success": true,
    "status": 200,
    "data": [],
    "count": 0

Serializing Response Data

After the data has been transformed, it will be serialized using the specified success serializer in the configuration file, which defaults to the package's own Flugg\Responder\Serializers\SuccessSerializer. You can overwrite this on your responses using the serializer method:

return responder()->success()->serializer(JsonApiSerializer::class)->respond();
return responder()->success()->serializer(new JsonApiSerializer())->respond();

Above we're using Fractal's JsonApiSerializer class. Fractal also ships with an ArraySerializer and DataArraySerializer class. If none of these suit your taste, feel free to create your own serializer by extending League\Fractal\Serializer\SerializerAbstract. You can read more about it in Fractal's documentation.

Creating Transformers

A dedicated transformer class gives you a convenient location to transform data and allows you to reuse the transformer at multiple places. It also allows you to include and transform relationships. You can create a transformer using the make:transformer Artisan command:

php artisan make:transformer ProductTransformer

The command will generate a new ProductTransformer.php file in the app/Transformers folder:

namespace App\Transformers;

use App\User;
use Flugg\Responder\Transformers\Transformer;

class ProductTransformer extends Transformer
     * List of available relations.
     * @var string[]
    protected $relations = [];

     * A list of autoloaded default relations.
     * @var array
    protected $load = [];

     * Transform the model.
     * @param  \App\Product $product
     * @return array
    public function transform(Product $product): array
        return [
            'id' => (int) $product->id,

It will automatically resolve a model name from the name provided. For instance, the package will extract Product from ProductTransformer and assume the models live directly in the app folder (as per Laravel's convention). If you store them somewhere else, you can use the --model (or -m) option to override it:

php artisan make:transformer ProductTransformer --model="App\Models\Product"

Creating Plain Transformers

The transformer file generated above is a model transformer expecting an App\Product model for the transform method. However, we can create a plain transformer by applying the --plain (or -p) modifier:

php artisan make:transformer ProductTransformer --plain

This will remove the typehint from the transform method and add less boilerplate code.

Setting Relationships

The $relations and $load properties in the transformer are the equivalent to Fractal's own $availableIncludes and $defaultIncludes. In addition to the slight name change, the package uses the $relations and $load properties to map out all available relationships for eager loading, so in contrast to Fractal, you should map the relationship to their corresponding transformer:

protected $relations = [
    'shipments' => ShipmentTransformer::class,

You can choose to skip the mapping and just pass the strings like with Fractal, but that means the package wont be able to eager load relationships automatically.

Setting Whitelisted Relationships

The $relations property specifies a list of relations available to be included. You can set a list of relations mapped to their corresponding transformers:

protected $relations = [
    'shipments' => ShipmentTransformer::class,
    'orders' => OrderTransformer::class,

Setting Autoloaded Relationships

The $load property specifies a list of relations to be autoloaded every time you transform data with the transformer:

protected $load = [
    'shipments' => ShipmentTransformer::class,
    'orders' => OrderTransformer::class,

You don't have to add relations to both $relations and $load, all relations in $load will be available by nature.

Including Relationships

While Fractal requires you to to create a method in your transformer for every included relation, this package lets you skip this when transforming models, as it will automatically fetch relationships from the model. You may of course override this functionality by creating an "include" method:

 * Include related shipments.
 * @param  \App\Product $product
 * @return mixed
public function includeShipments(Product $product)
    return $product->shipments;

Unlike Fractal you can just return the data directly without wrapping it in an item or collection method.

You should be careful with executing database calls inside the include methods as you might end up with an unexpected amount of hits to the database.

Using Include Parameters

Fractal can parse query string parameters which can be used when including relations. For more information about how to format the parameters see Fractal's documentation on parameters. You may access the parameters by adding a second parameter to the "include" method:

public function includeShipments(Product $product, Collection $parameters)
    return $product->shipments->take($parameters->get('limit'));

To be as decoupled from Fractal as possible the parameters (which are normally accessed using League\Fractal\ParamBag) are accessed as Laravel collections instead.

Adding Query Constraints

Just as you can specify a query constraint when including a relationship with the with method, you can also add query constraints as a "load" method on the transformer. This will automatically be applied when extracting relationships for eager loading.

 * Load shipments with constraints.
 * @param  \Illuminate\Database\Eloquent\Builder $query
 * @return \Illuminate\Database\Eloquent\Builder
public function loadShipments($query)
    return $query->whereNull('shipped_at');

Note: You cannot mix "include" and "load" methods because the package doesn't eager load relationships included with an "include" method.

Filtering Relationships

After a relation has been included, you can make any last second changes to it using a filter method. For instance, below we're filtering the list of related shipments to only include shipments that has not been shipped:

 * Filter included shipments.
 * @param  \Illuminate\Database\Eloquent\Collection $shipments
 * @return \Illuminate\Support\Collection
public function filterShipments($shipments)
    return $shipments->filter(function ($shipment) {
        return is_null($shipment->shipped_at);

Transforming Data

We've looked at how to transform response data of success responses, however, there may be other places than your controllers where you want to transform data. An example is broadcasted events where you're exposing data using websockets instead of HTTP. You just want to return the transformed data, not an entire response.

It's possible to simply transform data by newing up the transformer and calling transform:

return (new ProductTransformer)->transform(Product::first());

However, this approach might become a bit messy when building transformations with relationships:

return array_merge((new ProductTransformer)->transform($product = Product::first()), [
    'shipments' => $product->shipments->map(function ($shipment) {
        return (new ShipmentTransformer)->transform($shipment);

Yuck! Imagine that with multiple nested relationships. Let's explore a simpler way to handle this.

Building Transformations

The SuccessResponseBuilder actually delegates all of the transformation work to a dedicated Flugg\Responder\TransformBuilder class. We can use this class ourself to transform data. For instance, if the product and shipment transformers were bound to the models, we could replicate the code above in the following way:

public function index(TransformBuilder $transformation)
    return $transformation->resource(Product::all())->with('shipments')->transform();

Instead of using the success method on the Responder service, we use the resource method on the TransformBuilder with the same method signature. We also use transform to execute the transformation instead of respond as we did when creating responses. In addition to the with method, you also have access to the other transformation methods like without, only, meta and serializer.

Using toArray on the Responder service is almost the same as the code above, however, it will also include response decorators which might not be desired.

Transforming Without Serializing

When using the TransformBuilder to transform data it will still serialize the data using the configured serializer. Fractal requires the use of a serializer to transform data, but sometimes we're just interested in the raw transformed data. The package ships with a Flugg\Responder\Serializers\NoopSerializer to solve this, a no-op serializer which leaves the transformed data untouched:

return $transformation->resource(Product::all())->serializer(NoopSerializer::class)->transform();

If you think this is looking messy, don't worry, there's a quicker way. In fact, you will probably never even need to utilize the NoopSerializer or TransformBuilder manually, but it helps to know how it works. The Flugg\Responder\Transformation is a class which can be used for quickly transforming data without serializing.

Option 1: The Transformation Service

The Transformation class utilizes the TransformBuilder class to build a transformation using the NoopSerializer. You can inject the Transformation class and call make to obtain an instance of TransformBuilder which gives you access to all of the chainable methods including with, like below:

public function __construct(Transformation $transformation)

Option 2: The transformation Helper

You can use the transformation helper function to transform data without serializing:


Option 3: The Transformation Facade

You can also use the Transformation facade to achieve the same thing:


Transforming To Camel Case

Model attributes are traditionally specified in snake case, however, you might prefer to use camel case for the response fields. A transformer makes for a perfect location to convert the fields, as seen from the soldOut field in the example below:

return responder()->success(Product::all(), function ($product) {
    return ['soldOut' => (bool) $product->sold_out];    

Transforming Request Parameters

After responding with camel case, you probably want to let people send in request data using camel cased parameters as well. The package provides a Flugg\Responder\Http\Middleware\ConvertToSnakeCase middleware you can append to the $middleware array in app/Http/Kernel.php to convert all parameters to snake case automatically:

protected $middleware = [
    // ...

The middleware will run before request validation, so you should specify your validation rules in snake case as well.

Creating Error Responses

Whenever a consumer of your API does something unexpected, you can return an error response describing the problem. As briefly shown in a previous chapter, an error response can be created using the error method:

return responder()->error()->respond();

The error response has knowledge about an error code, a corresponding error message and optionally some error data. With the default configuration, the above code would output the following JSON:

    "success": false,
    "status": 500,
    "error": {
        "code": null,
        "message": null

Setting Error Code & Message

You can fill the first parameter of the error method to set an error code:

return responder()->error('sold_out_error')->respond();

You may optionally use integers for error codes.

In addition, you may set the second parameter to an error message describing the error:

return responder()->error('sold_out_error', 'The requested product is sold out.')->respond();

Set Messages In Language Files

You can set the error messages in a language file, which allows for returning messages in different languages. The configuration file has an error_message_files key defining a list of language files with error messages. By default, it is set to ['errors'], meaning it will look for an errors.php file inside resources/lang/en. You can use these files to map error codes to corresponding error messages:

return [
    'sold_out_error' => 'The requested product is sold out.',

Register Messages Using ErrorMessageResolver

Instead of using language files, you may alternatively set error messages directly on the ErrorMessageResolver class. You can place the code below within AppServiceProvider or an entirely new TransformerServiceProvider:

use Flugg\Responder\ErrorMessageResolver;

public function boot()
        'sold_out_error' => 'The requested product is sold out.',

Adding Error Data

You may want to set additional data on the error response. Like in the example below, we're returning a list of shipments with the sold_out error response, giving the consumer information about when a new shipment for the product might arrive.

return responder()->error('sold_out')->data(['shipments' => Shipment::all()])->respond();

The error data will be appended to the response data. Assuming we're using the default serializer and there are no shipments in the database, the code above would look like:

    "success": false,
    "status": 500,
    "error": {
        "code": "sold_out",
        "message": "The requested product is sold out.",
        "shipments": []

Serializing Response Data

Similarly to success responses, error responses will be serialized using the specified error serializer in the configuration file. This defaults to the package's own Flugg\Responder\Serializers\ErrorSerializer, but can of course be changed by using the serializer method:

return responder()->error()->serializer(ExampleErrorSerializer::class)->respond();
return responder()->success()->serializer(new ExampleErrorSerializer())->respond();

You can create your own error serializer by implementing the Flugg\Responder\Contracts\ErrorSerializer contract.

Handling Exceptions

No matter how much we try to avoid them, exceptions do happen. Responding to the exceptions in an elegant manner will improve the user experience of your API. The package can enhance your exception handler to automatically turn exceptions in to error responses. If you want to take use of this, you can either use the package's exception handler or include a trait as described in further details below.

Option 1: Replace Handler Class

To use the package's exception handler you need to replace the default import in app/Exceptions/Handler.php:

use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;

With the package's handler class:

use Flugg\Responder\Exceptions\Handler as ExceptionHandler;

This will not work with Lumen as its exception handler is incompatible with Laravel's. Look instead at the second option below.

Option 2: Use ConvertsExceptions Trait

The package's exception handler uses the Flugg\Responder\Exceptions\ConvertsExceptions trait to load of most of its work. Instead of replacing the exception handler, you can use the trait in your own handler class. To replicate the behavior of the exception handler, you would also have to add the following code to the render method:

public function render($request, Exception $exception)

    if ($exception instanceof HttpException) {
        return $this->renderResponse($exception);

    return parent::render($request, $exception);

If you only want to return JSON error responses on requests actually asking for JSON, you may wrap the code above in a wantsJson check as seen below:

if ($request->wantsJson()) {

    if ($exception instanceof HttpException) {
        return $this->renderResponse($exception);

Converting Exceptions

Once you've implemented one of the above options, the package will convert some of Laravel's exceptions to an exception extending Flugg\Responder\Exceptions\Http\HttpException. It will then convert these to an error response. The table below shows which Laravel exceptions are converted and what they are converted to. All the exceptions on the right is under the Flugg\Responder\Exceptions\Http namespace and extends Flugg\Responder\Exceptions\Http\HttpException. All exceptions extending the HttpException class will be automatically converted to an error response.

Caught Exceptions Converted To
Illuminate\Auth\AuthenticationException UnauthenticatedException
Illuminate\Auth\Access\AuthorizationException UnauthorizedException
Symfony\Component\HttpKernel\Exception\NotFoundHttpException PageNotFoundException
Illuminate\Database\Eloquent\ModelNotFoundException PageNotFoundException
Illuminate\Database\Eloquent\RelationNotFoundException RelationNotFoundException
Illuminate\Validation\ValidationException ValidationFailedException

You can disable the conversions of some of the exceptions above using the $dontConvert property:

 * A list of default exception types that should not be converted.
 * @var array
protected $dontConvert = [

If you're using the trait option, you can disable all the default conversions by removing the call to convertDefaultException in the render method.

Convert Custom Exceptions

In addition to letting the package convert Laravel exceptions, you can also convert your own exceptions using the convert method in the render method:

$this->convert($exception, [
    InvalidValueException => PageNotFoundException,

You can optionally give it a closure that throws the new exception, if you want to give it constructor parameters:

$this->convert($exception, [
    MaintenanceModeException => function ($exception) {
        throw new ServerDownException($exception->retryAfter);

Creating HTTP Exceptions

An exception class is a convenient place to store information about an error. The package provides an abstract exception class Flugg\Responder\Exceptions\Http\HttpException, which has knowledge about status code, an error code and an error message. Continuing on our product example from above, we could create our own HttpException class:

namespace App\Exceptions;

use Flugg\Responder\Exceptions\Http\HttpException;

class SoldOutException extends HttpException
     * The HTTP status code.
     * @var int
    protected $status = 400;

     * The error code.
     * @var string|null
    protected $errorCode = 'sold_out_error';

     * The error message.
     * @var string|null
    protected $message = 'The requested product is sold out.';

You can also add a data method returning additional error data:

 * Retrieve additional error data.
 * @return array|null
public function data()
    return [
        'shipments' => Shipment::all()

If you're letting the package handle exceptions, you can now throw the exception anywhere in your application and it will automatically be rendered to an error response.

throw new SoldOutException();


Contributions are more than welcome and you're free to create a pull request on Github. You can run tests with the following command:


If you find bugs or have suggestions for improvements, feel free to submit an issue on Github. However, if it's a security related issue, please send an email to [email protected] instead.


The package is completely free to use, however, a lot of time has been put into making it. If you want to show your appreciation by leaving a small donation, you can do so by clicking here. Thanks!


Laravel Responder is free software distributed under the terms of the MIT license. See for more details.

  • 1. Relationship filter parameters unsupported

    I haven't had time to test this too thoroughly, I will try and update this issue with more information when I do, but it doesn't appear that fractal's nested relationships are working correctly when used with this package. By that I mean url patterns like this:

    Getting the "author" relationship works, but getting the ".stores" portion of it does not.

    Reviewed by imjohnbon at 2016-10-25 03:30
  • 2. issue with the same type model relationships

    Hi flugger

    I've been using relations with this package and it works just fine. For example if I wanna send the owner of the comment it works just fine.

    On the other hand, I wanna send the children of comments (it's a tree-style comment system like Disqus) in my api, and only then(using relations to retrieve the same type of model) I get this error: "Data must only contain models implementing the Transformable contract."

    My relation implementation seems fine as it works just fine, it's just I need it in the API but it fails :(, any idea how to fix it?

    Thank your for your great package

    Reviewed by saleh-old at 2016-08-10 15:42
  • 3. null relation and NullResource return empty array instead of null

    In pure Fractal, when you return a null from an include the field is not added on the output array. If you return a NullResource I think it returns a "fieldname => null" instead (not 100% sure). In laravel-responder it returns an empty array in both cases, it seems.

    I actually recall that yesterday it returned a null field, but I don't remember if it was before or after i started playing with this library 🤔 Can you confirm this or it's a problem with my code? If it's the intended behaviour, would't it be better if it returned just null instead of an empty array?

    The use case scenario here is that I have users with an avatar which is optional, so the relation could return null. If it's not null, it returns the image transformed by its transformer as intended, If it's null, it returns an empty array.

    Reviewed by IlCallo at 2017-11-10 09:22
  • 4. Adding pivot data on loaded relation

    Here's the scenario: there are groups and users, much like a Whatsapp group could be. Groups and users are connected by a pivot table holding informations about when the user entered the group and whether or not he's an admin of that group.

    Obviously all members of a group are accessible from a relation called "members" which is mapped to a UserTransformer using "load" property as explained in docs, is there a way to also include pivot data from the includeMembers method on a GroupTransformer?

    I prefer to do the adding on the GroupTransformer rather than passing an option to the constructor of the UserTransformer which will manage members representation because other parts of the API will need to add pivot data to users about other relations in other situations and the code could become a bit messy.

    Laravel 5.5 has something similar called "Conditional Pivot Information", even if it's not exactly what I'm searching for, because that feature works on the user tranformer, which I want to avoid.

    It doesn't need to be related to pivot actually, any way of adding data to every single collection member after it has been processed by it's transformer would be fine.

    The solutions that get to my mind, even if a bit dirty, is to call transform on members relationship inside "includeMembers", then using a foreach to add pivot informations (which are stored on the Eloquent model but not on the transformed data at this point) and lastly return the newly generated array wrapping it up with the "resource()" method.

    If there could be a way to say, on UserTransformer, "when you are called by a XxxTransformer, merge the array resulting by function XxxModifier (which provides in input you the original model) to the transform() result", that could be an acceptable way to solve this problem even if the code is on UserTransformer and not GroupTransformer, because code would still be enough clean and ordered.

    On the other hand, moving that feature to the "related" transformer instead of the primary transformer seems to me a pain in the ass while testing, because tests about groups representation would be about UserTransformer methods instead of GroupTransformer.

    I'm sorry for all the issues I'm opening, but I guess I'll stick around a little bit while I try to use this library :P

    Reviewed by IlCallo at 2017-11-10 08:37
  • 5. error using composer update

    Generating optimized autoload files
    > Illuminate\Foundation\ComposerScripts::postAutoloadDump
    > @php artisan package:discover --ansi
    PHP Fatal error:  Declaration of Flugg\Responder\Exceptions\Handler::render($request, Throwable $exception) must be compatible with Illuminate\Foundation\Exceptions\Handler::render($request, Exception $e) in /Users/aligajani/Sites/shadow-platform/vendor/flugger/laravel-responder/src/Exceptions/Handler.php on line 16
    PHP Fatal error:  Uncaught ReflectionException: Class App\Exceptions\Handler does not exist in /Users/aligajani/Sites/shadow-platform/vendor/laravel/framework/src/Illuminate/Container/Container.php:803
    Stack trace:
    #0 /Users/aligajani/Sites/shadow-platform/vendor/laravel/framework/src/Illuminate/Container/Container.php(803): ReflectionClass->__construct('App\\Exceptions\\...')
    #1 /Users/aligajani/Sites/shadow-platform/vendor/laravel/framework/src/Illuminate/Container/Container.php(681): Illuminate\Container\Container->build('App\\Exceptions\\...')
    #2 /Users/aligajani/Sites/shadow-platform/vendor/laravel/framework/src/Illuminate/Foundation/Application.php(785): Illuminate\Container\Container->resolve('App\\Exceptions\\...', Array, false)
    #3 /Users/aligajani/Sites/shadow-platform/vendor/laravel/framework/src/Illuminate/Container/Container.php(265): Illuminate\Foundation\Application->resolve('App\\Exceptions\\...', Array, false)
    #4 /Users/aligajani/Sites/shadow-platform/vendor/laravel/framework/src/Illuminate/Container/Container. in /Users/aligajani/Sites/shadow-platform/vendor/laravel/framework/src/Illuminate/Container/Container.php on line 805
    Script @php artisan package:discover --ansi handling the post-autoload-dump event returned with error code 255
    Reviewed by aligajani at 2020-03-18 14:36
  • 6. Autoconvert relationship name to snakecase

    Hey there, I found myself in this situation in which all data I return have snake case keys, but relations composed by more than 1 words, by Laravel convention, are accessible only via the camel case name. When #84 will be fixed I'll probably be able to workaround this, but for some reason I feel that automatically translate relations names to snake case could be the right thing, or at least to give the possibility to do so, maybe with an option on the configuration file.

    Another option, which can be viable even if I don't like it that much, is to use a decorator to iterate on every key of the response, detect camel case keys and convert them. It seems a bit inefficient to me, but it's a possibility. The problem in this case is that while in output we'll have snake case, when defining available relationships or autoloaded relationships we'll still be using camel case, which is inconsistent (in my case) with all other data and includes I'll be returning.

    Any other ideas on how to tackle this problem?

    Reviewed by IlCallo at 2017-11-20 14:07
  • 7. [Question] Error handling

    Hi @flugger,

    I'm working on Lumen application and I was wondering if I can completely disable Whoops, looks like something went wrong. message and always receive the output like:

        "success": false,
        "status": 500,
        "error": {
            "code": null,
            "message": null

    I followed your guide and included the trait HandlesApiErrors, as well as added $this->transformException($exception); to my render method.

    Cheers, Evgenii

    Reviewed by nasyrov at 2017-07-25 09:50
  • 8. composer require - cannot install

    composer require flugger/laravel-responder gives me this output:

    Using version ^1.2 for flugger/laravel-responder
    ./composer.json has been updated
    Loading composer repositories with package information
    Updating dependencies (including require-dev)
    Your requirements could not be resolved to an installable set of packages.
      Problem 1
        - flugger/laravel-responder v1.2.1 requires league/fractal dev-master -> satisfiable by league/fractal[dev-master] but these conflict with your requirements or minimum-stability.
        - flugger/laravel-responder v1.2.0 requires league/fractal dev-master -> satisfiable by league/fractal[dev-master] but these conflict with your requirements or minimum-stability.
        - Installation request for league/fractal (locked at 0.16.0) -> satisfiable by league/fractal[0.16.0].
        - flugger/laravel-responder v1.2.10 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.11 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.12 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.13 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.14 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.15 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.16 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.17 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.18 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.19 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.20 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.21 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.22 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.4 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.5 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.6 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.7 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.8 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - flugger/laravel-responder v1.2.9 requires league/fractal ^0.14.0 -> satisfiable by league/fractal[0.14.0].
        - Conclusion: don't install league/fractal 0.14.0
        - flugger/laravel-responder v1.2.2 requires league/fractal ^0.13.0 -> satisfiable by league/fractal[0.13.0].
        - flugger/laravel-responder v1.2.3 requires league/fractal ^0.13.0 -> satisfiable by league/fractal[0.13.0].
        - Conclusion: don't install league/fractal 0.13.0
        - Installation request for flugger/laravel-responder ^1.2 -> satisfiable by flugger/laravel-responder[v1.2.0, v1.2.1, v1.2.10, v1.2.11, v1.2.12, v1.2.13, v1.2.14, v1.2.15, v1.2.16, v1.2.17, v1.2.18, v1.2.19, v1.2.2, v1.2.20, v1.2.21, v1.2.22, v1.2.3, v1.2.4, v1.2.5, v1.2.6, v1.2.7, v1.2.8, v1.2.9].
    Installation failed, reverting ./composer.json to its original content.

    My composer.json:

        "name": "laravel/laravel",
        "description": "The Laravel Framework.",
        "keywords": [
        "license": "MIT",
        "type": "project",
        "require": {
            "php": ">=5.6.4",
            "arcanedev/log-viewer": "~4.0",
            "arcanedev/no-captcha": "~3.0",
            "creativeorange/gravatar": "~1.0",
            "davejamesmiller/laravel-breadcrumbs": "^3.0",
            "dingo/api": "[email protected]",
            "hieu-le/active": "~3.0",
            "laravel/framework": "5.4.*",
            "laravel/socialite": "^3.0",
            "laravel/tinker": "~1.0",
            "laravelcollective/html": "5.4.*",
            "prettus/l5-repository": "^2.6",
            "sentry/sentry-laravel": "^0.6.1",
            "yajra/laravel-datatables-oracle": "^7.0"
        "require-dev": {
            "fzaninotto/faker": "~1.4",
            "mockery/mockery": "0.9.*",
            "phpunit/phpunit": "~5.7",
            "barryvdh/laravel-debugbar": "^2.1",
            "laravel/browser-kit-testing": "^1.0"
        "autoload": {
            "classmap": [
            "psr-4": {
                "App\\": "app/"
            "files": [
        "autoload-dev": {
            "psr-4": {
                "Tests\\": "tests/"
            "classmap": [
        "scripts": {
            "post-root-package-install": [
                "php -r \"file_exists('.env') || copy('.env.example', '.env');\""
            "post-create-project-cmd": [
                "php artisan key:generate"
            "post-install-cmd": [
                "php artisan optimize"
            "post-update-cmd": [
                "php artisan optimize"
        "config": {
            "preferred-install": "dist",
            "sort-packages": true

    I can't understand what's wrong. Can you please help me?


    Reviewed by eleftrik at 2017-04-30 14:33
  • 9. Add support for error presets

    This PR adds support for error presets which consist of an identifier, error code, status code and message.

    'access_denied' => [
        'errorCode'  => 'ERR-ACCESS-DENIED',
        'statusCode' => 403,
        'message'    => 'Access Denied',
    'bad_gateway' => [
        'errorCode'  => 'ERR-BAD-GATEWAY',
        'statusCode' => 502,
        'message'    => 'Bad Gateway',
    'bad_request' => [
        'errorCode'  => 'ERR-BAD-REQUEST',
        'statusCode' => 400,
        'message'    => 'Bad Request',

    This allows for an easier, faster and cleaner way of returning errors and stops the continuous repetition of error codes and messages in controllers.

    So instead of return responder()->error('ERR-ACCESS-DENIED', 403, 'Access Denied'); we could then do responder()->error('access_denied');.

    Reviewed by faustbrian at 2016-12-06 19:26
  • 10. Laravel Responder installation in Laravel 9 is not working.


    • composer required flugger/laravel-responder

    Error Result

    • flugger/laravel-responder[v3.1.0, ..., v3.1.2] require php ^7.0 -> your php version (8.1.3) does not satisfy that requirement.

    But the laravel 9 requires php 8^ to make it install

    Reviewed by markdark09 at 2022-03-13 06:58
  • 11. Relations with an includeXxx method won't be eager loaded anymore

    This opens up scenarios where there is a need to consider as a relation what in fact is just a method returning a Model or a Collection.

    This resolves the original question of #84

    Reviewed by IlCallo at 2017-12-06 11:02
  • 12. Include message in success response

    { "status": 200, "success": true, "message": "Logged out successfully!", "data": null }

    Is there any way to include a message to success respond like the above?

    Reviewed by LubySagia at 2022-01-31 12:34
  • 13. How do I use getResourceKey() on Relationship?

    Hi @flugg ,

    I have setup my models with getResourcKey() for both models:


    . . .
        public function getResourceKey(): string {
            return 'neliti-volumes';
    . . .


    . . .
        public function getResourceKey(): string {
            return 'neliti-publications';
    . . .

    When I try to get the result from the url using /neliti-volumes?include=neliti-publication, I get the type is using camel-case; not using the kebab-case that I already defined in the models:

      "data": [
          "type": "neliti-volumes",
          "id": "088f4670-8993-4ffc-86e4-58036442cebe",
          "attributes": {
            "volume": "BB",
            "number": "3",
          "relationships": {
            "neliti-publication": { // this one is from the url that mapped with the transformers
              "data": {
                "type": "nelitiPublication", // this one should be neliti-publications that get from getResourceKey()
                "id": "39676c75-6e03-11ea-9660-ed7fb61131c5"
        . . .

    Btw, I am using JSON API Serializer from PHP League...

    Did I miss something?

    Reviewed by wukongrita at 2021-03-09 19:03
  • 14. Transforming To Camel Case in Lumen

    Hi @flugg ,

    I would like to use the transforming camel case - snake case feature in lumen; but I get error something like this:


    How do I achieve this in lumen?

    Thank you

    Reviewed by wukongrita at 2021-02-28 23:03
  • 15. error

    Your requirements could not be resolved to an installable set of packages.

    Problem 1 - flugger/laravel-responder[v3.1.0, ..., v3.1.1] require illuminate/contracts 5.1.* || 5.2.* || 5.3.* || 5.4.* || 5.5.* || 5.6.* || 5.7.* || 5.8.* || ^6.0 || ^7.0 -> found illuminate/contracts[v5.1.1, ..., 5.8.x-dev, v6.0.0, ..., 6.x-dev, v7.0.0, ..., 7.x-dev] but these were not loaded, likely because it conflicts with another require. - flugger/laravel-responder[v3.1.2, ..., v3.1.3] require league/fractal ^0.17.0 -> found league/fractal[0.17.0] but the package is fixed to 0.19.2 (lock file version) by a partial update and that version does not match. Make sure you list it as an argument for the update command. - Root composer.json requires flugger/laravel-responder ^3.1 -> satisfiable by flugger/laravel-responder[v3.1.0, v3.1.1, v3.1.2, v3.1.3].

    Use the option --with-all-dependencies (-W) to allow upgrades, downgrades and removals for packages currently locked to specific versions.

    Reviewed by shijunti19 at 2021-02-17 02:29
  • 16. ConvertToSnakeCase throwing an "Undefined function" error

    When using the ConvertToSnakeCase middleware there is an undefined function error when using snake_case(). I believe this has now been updated by Laravel to use Illuminate\Support\Str::snake() instead.

    Reviewed by stuartowendev at 2021-01-31 23:41
  • 17. Transformer mappings circular dependencies

    Hey there, thanks for this awesome package. This particular issue has been mentioned and fixed previously in #106. I've got this:

    class VariationTransformer extends Transformer
        protected $load = [
            'product' => ProductTransformer::class
        public function transform(Variation $model): array
            return [
                'id' => $model->id,
                'sku' => $model->sku,
                'name' => $model->name

    And this.

    class ProductTransformer extends Transformer
        protected $load = [
            'variations' => VariationTransformer::class
        public function transform(Product $model): array
            return [
                'name' => $model->name,
                'description' => $model->description

    The problem seems to be caused by the $load relationships calling each other. I'm using the latest version (3.1.2).

    Reviewed by mauriciovillam at 2020-12-11 01:14
Laravel Segment is an opinionated, approach to integrating Segment into your Laravel application.

Laravel Segment Laravel Segment is an opinionated, approach to integrating Segment into your Laravel application. Installation You can install the pac

May 16, 2022
A simple package allowing for consistent API responses throughout your Laravel application
A simple package allowing for consistent API responses throughout your Laravel application

Laravel API Response Helpers A simple package allowing for consistent API responses throughout your Laravel application. Requirements PHP ^7.4 | ^8.0

May 11, 2022
A lightweight package for handling API error responses.

Laravel API Errors This package provides an easy way to manage and handle error response for JSON API's. Installation You can install the package via

Feb 9, 2022
Builds nice, normalized and easy to consume REST JSON responses for Laravel powered APIs.

REST API Response Builder for Laravel Master branch: Development branch: Table of contents Introduction Why should I use it? Usage examples Features E

May 23, 2022
Laravel Jsonable - Well-Formated Responses & Exceptions.
Laravel Jsonable - Well-Formated Responses & Exceptions.

Laravel Jsonable Well-Formated Responses & Exceptions. Documentation You can find the detailed documentation here in Laravel Jsonable Documentation. C

Mar 12, 2022
Caches responses as static files on disk for lightning fast page loads.

Laravel Page Cache This package allows you to easily cache responses as static files on disk for lightning fast page loads. Introduction Installation

May 26, 2022
Lumen rest api demo with Dingo/Api, JWT, CORS, PHPUNIT

lumen-api-demo 这是一个比较完整用 lumen 5.7 写的的 REST API 例子。使用了 dingo/api ,jwt 实现登录,功能上很简单,登录,注册,发帖,评论,单元测试(正在补充)。 lumen5.x 请看对应的分支 有需要随时联系我 lumen/laravel/rest

May 8, 2022
Laravel-FCM is an easy to use package working with both Laravel and Lumen for sending push notification with Firebase Cloud Messaging (FCM).

Laravel-FCM Introduction Laravel-FCM is an easy to use package working with both Laravel and Lumen for sending push notification with Firebase Cloud M

Dec 29, 2021
Public API for the project Made in PHP 8.0 with Lumen 8, PHP-FPM, NGINX and MySQL 8.
Public API for the project Made in PHP 8.0 with Lumen 8, PHP-FPM, NGINX and MySQL 8. API Uma API feita apenas para passar o tempo, montando uma API para o site <>. Sinta-se livre para usar esse código como es

Dec 29, 2021
Laravel Boilerplate provides a very flexible and extensible way of building your custom Laravel applications.
Laravel Boilerplate provides a very flexible and extensible way of building your custom Laravel applications.

Laravel Boilerplate Project Laravel Boilerplate provides a very flexible and extensible way of building your custom Laravel applications. Table of Con

May 20, 2022
Package to parse DNA kit files, and import them into Laravel

Package to parse DNA kit files, and import them into Laravel

Feb 18, 2022
Smeify is a Stable Automated Solution for Airtime and Data businesses in Nigeria, this package helps you integrate smeify easily into your laravel application.

Smeify is a Stable Automated Solution for Airtime and Data businesses in Nigeria, this package helps you integrate smeify easily into your laravel application.

Nov 1, 2021
LERN is a Laravel package that will record exceptions into a database and will notify you via Email, Pushover or Slack.

LERN is a Laravel package that will record exceptions into a database and will notify you via Email, Pushover or Slack.

Feb 13, 2022
Live Helper Chat - live support for your website. Featuring web and mobile apps, Voice & Video & ScreenShare. Supports Telegram, Twilio (whatsapp), Facebook messenger including building a bot.

Live helper chat It's an open-source powered application, which brings simplicity and usability in one place. With live helper chat you can bring live

May 16, 2022
📦 Adds Laravel Packages Support to Lumen and Vendor Publish Artisan Command.
📦 Adds Laravel Packages Support to Lumen and Vendor Publish Artisan Command.

Laravel Package Support for Lumen: Makes Lumen compatible with Laravel Packages. You can use any Laravel Packages in Lumen by installing Larasupport Package.

May 19, 2022
A collection of generators for Lumen and Laravel 5.

Lumen generators A collection of generators for Lumen and Laravel 5. Contents Why ? Installation Quick Usage Detailed Usage Model Generator Migration

Mar 24, 2022
CORS (Cross-Origin Resource Sharing) support for Laravel and Lumen

Description This package adds Cross-Origin Resource Sharing (CORS) support to your Laravel application. The package is based on Framework agnostic (PS

Feb 1, 2020
A Laravel and Lumen Badges Generator

Laravel and Lumen Badge Generator That package is a easy wrapper to Badges/Poser. #Installing composer require vluzrmos/laravel-badge-poser Laravel co

Jun 10, 2020
Laravel and Lumen Auto Hard Deleter
Laravel and Lumen Auto Hard Deleter

Laravel Auto Hard Deleter This package deletes soft deleted rows automatically after a time interval that you define. For Laravel and Lumen 6, 7, 8 In

Apr 27, 2022