A Laravel Fractal package for building API responses, giving you the power of Fractal with Laravel's elegancy.


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 license.md for more details.

  • Relationship filter parameters unsupported

    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.

    opened by imjohnbon 38
  • issue with the same type model relationships

    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

    opened by saleh-old 22
  • null relation and NullResource return empty array instead of null

    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.

    in progress 
    opened by IlCallo 17
  • Adding pivot data on loaded relation

    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

    opened by IlCallo 17
  • error using composer update

    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
    opened by aligajani 15
  • Autoconvert relationship name to snakecase

    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?

    opened by IlCallo 15
  • [Question] Error handling

    [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

    opened by nasyrov 15
  • composer require - cannot install

    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": "1.0.x@dev",
            "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?


    opened by eleftrik 13
  • Add support for error presets

    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');.

    opened by faustbrian 12
  • Laravel Responder installation in Laravel 9 is not working.

    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

    opened by markdark09 11
  • Relations with an includeXxx method won't be eager loaded anymore

    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

    opened by IlCallo 11
  • I wish there was an *except* method

    I wish there was an *except* method

    The way "only" is available I wish there was an "except" or "exclude" method as well. That can be handy if you have a large amount of data to return and you can't want to go through the pain of adding all those data just to exclude only one data. Like so;

     return responder()->success(User::all())->only('id', 'name', 'height', 'dob', 'hair_color', 'gender', 'contact', 'email', 'residential_address', 'country_of_residence')->respond();

    Then you can;

     return responder()->success(User::all())->exclude('create_at', 'updated_at')->respond();
    opened by nanadjei 0
  • Include message in success response

    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?

    opened by LubySagia 1
  • How do I use getResourceKey() on Relationship?

    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?

    opened by wukongrita 0
  • Transforming To Camel Case in Lumen

    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

    opened by wukongrita 0
  • 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.

    opened by shijunti19 1
Alexander Tømmerås
A web developer with a passion for open source and beautiful code.
Alexander Tømmerås
An easy to use Fractal wrapper built for Laravel and Lumen applications

An easy to use Fractal wrapper built for Laravel and Lumen applications The package provides a nice and easy wrapper around Fractal for use in your La

Spatie 1.8k Dec 30, 2022
The 1Password Connect PHP SDK provides your PHP applications access to the 1Password Connect API hosted on your infrastructure and leverage the power of 1Password Secrets Automation

1Password Connect PHP SDK The 1Password Connect PHP SDK provides your PHP applications access to the 1Password Connect API hosted on your infrastructu

Michelangelo van Dam 12 Dec 26, 2022
A REST API that should power the Agile Monkeys CRM Service

This is a simple REST API that purposes to power the Agile Monkeys CRM service

Dickens odera 3 Jul 31, 2021
GraphQL implementation with power of Laravel

Laravel GraphQL Use Facebook GraphQL with Laravel 5.2 >=. It is based on the PHP implementation here. You can find more information about GraphQL in t

Studionet 56 Mar 9, 2022
STEAM education curriculum centered on building a new civilization entirely from trash, which provides all human needs for free directly to the local community

TRASH ACADEMY STEAM(Science Technology Engineering Art Math) education curriculum centered around building self-replicating technology from trash whic

Trash Robot 3 Nov 9, 2021
PSR-7 middleware foundation for building and dispatching middleware pipelines

laminas-stratigility From "Strata", Latin for "layer", and "agility". This package supersedes and replaces phly/conduit. Stratigility is a port of Sen

Laminas Project 47 Dec 22, 2022
Provides tools for building modules that integrate Nosto into your e-commerce platform

php-sdk Provides tools for building modules that integrate Nosto into your e-commerce platform. Requirements The Nosto PHP SDK requires at least PHP v

Nosto 5 Dec 21, 2021
Laravel api tool kit is a set of tools that will help you to build a fast and well-organized API using laravel best practices.

Laravel API tool kit and best API practices Laravel api tool kit is a set of tools that will help you to build a fast and well-organized API using lar

Ahmed Esa 106 Nov 22, 2022
Simple and effective multi-format Web API Server to host your PHP API as Pragmatic REST and / or RESTful API

Luracast Restler ![Gitter](https://badges.gitter.im/Join Chat.svg) Version 3.0 Release Candidate 5 Restler is a simple and effective multi-format Web

Luracast 1.4k Dec 14, 2022
This plugin lets you to get spawners that when you break them they regenerates themselves!

ItemSpawners This plugin lets you to get spawners that when you break them they regenerates themselves! How to use? For any information: https://githu

Oğuzhan 6 Jan 16, 2022
Laravel A2Reviews Client API lets you build apps, extensions, or plugins to get reviews from the A2reviews APP.

Overview Laravel A2Reviews Client API lets you build apps, extensions or plugins to get reviews from the A2reviews APP. Including adding reviews to a

Be Duc Tai 2 Sep 26, 2021
Package Repository Website - try https://packagist.com if you need your own -

Packagist Package Repository Website for Composer, see the about page on packagist.org for more. This project is not meant for re-use. It is open sour

Composer 1.6k Dec 27, 2022
This PHP library will help you to work with your Pinterest account without using any API account credentials.

Pinterest Bot for PHP A PHP library to help you work with your Pinterest account without API credentials. The Pinterest API is painful: receiving an a

Sergey Zhuk 414 Nov 21, 2022
A RESTful API package for the Laravel and Lumen frameworks.

The Dingo API package is meant to provide you, the developer, with a set of tools to help you easily and quickly build your own API. While the goal of

null 9.3k Jan 7, 2023
JSON API (jsonapi.org) package for Laravel applications.

cloudcreativity/laravel-json-api Status This package has now been rewritten, substantially improved and released as the laravel-json-api/laravel packa

Cloud Creativity 753 Dec 28, 2022
Phalcon PHP REST API Package, still in beta, please submit issues or pull requests

PhREST API A Phalcon REST API package, based on Apigees guidelines as found in http://apigee.com/about/content/web-api-design Please see the skeleton

PhREST 29 Dec 27, 2022
This package makes it easy for developers to access WhatsApp Cloud API service in their PHP code.

The first PHP API to send and receive messages using a cloud-hosted version of the WhatsApp Business Platform

NETFLIE 135 Dec 29, 2022
PHP Package for Autentique API-v2

PHP Package for Autentique API-v2

Vinicius Morais Dutra 32 Nov 22, 2022
This API aims to present a brief to consume a API resources, mainly for students in the early years of Computer Science courses and the like.

Simple PHP API v.1.0 This API aims to present a brief to consume a API resources, mainly for students in the early years of Computer Science courses a

Edson M. de Souza 14 Nov 18, 2021