Package Data | |
---|---|
Maintainer Username: | pegzi |
Maintainer Contact: | flugged@gmail.com (Alexander Tømmerås) |
Package Create Date: | 2017-08-11 |
Package Last Update: | 2017-08-11 |
Home Page: | |
Language: | PHP |
License: | MIT |
Last Refreshed: | 2024-12-15 15:07:20 |
Package Statistics | |
---|---|
Total Downloads: | 6 |
Monthly Downloads: | 0 |
Daily Downloads: | 0 |
Total Stars: | 0 |
Total Watchers: | 2 |
Total Forks: | 0 |
Total Open Issues: | 0 |
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.
Version 2.0 has been released with some changes and tons of new features. If you're migrating from an earlier version, make sure you read the changelog.
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:
To get started, install the package through Composer:
composer require flugger/laravel-responder
Notice: A recent change to the Laravel installer locks new projects to PHP 5.6. If you get an error about non-matching PHP version, make sure your composer.json doesn't contain a platform
field.
Append the following line to the providers
key in config/app.php
to register the package:
Flugg\Responder\ResponderServiceProvider::class,
The package supports auto-discovery, so if you use Laravel 5.5 or later you may skip registering the service provider and facades and instead run php artisan package:discover
.
If you like facades, you may also append the Responder
and Transformer
facades to the aliases
key:
'Responder' => Flugg\Responder\Facades\Responder::class,
'Transformer' => Flugg\Responder\Facades\Transformer::class,
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.
Add the following line to app/bootstrap.php
to register the package:
$app->register(Flugg\Responder\ResponderServiceProvider::class);
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\Transformer::class, 'Transformer');
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.
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:
Responder
ServiceYou 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();
responder
HelperIf you're a fan of Laravel's response
helper function, you may like the responder
helper function:
return responder()->success();
return responder()->error();
Responder
FacadeOptionally, you may use the Responder
facade to create responses:
return Responder::success();
return Responder->error();
MakesApiResponses
TraitLastly, 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.
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.
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.
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' => [
\Flugg\Responder\Http\Responses\Decorators\StatusCodeDecorator::class,
\Flugg\Responder\Http\Responses\Decorators\SuccessFlagDecorator::class,
],
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();
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
}
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.
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.
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];
})->respond();
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.
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\Transformers\TransformerResolver;
public function boot()
{
$this->app->make(TransformerResolver)->bind([
\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 to override this.
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": null,
"pagination": {
"total": 0,
"count": 0,
"perPage": 15,
"currentPage": 1,
"totalPages": 1
}
}
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();
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();
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) {
$query->whereNull('shipped_at');
}])->respond();
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
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();
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']
])->respond();
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
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
}
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.
A dedicated transformer class gives you a convenient location to transform data and allows you to use the same transformer multiple times. 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:
<?php
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, in the example above, 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"
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.
All transformers generated through the make:transformer
command will include a $relations
and $load
property, which are the equivalent to Fractal's $availableIncludes
and $defaultIncludes
. Fractal also requires you to to create methods in your transformer for all included relation. While this package also allows you to create such methods, it doesn't require it if you're transforming models.
For instance, if you're including a shipments
relation in a ProductTransformer
, the package will assume you have a shipments
relationship method in your Product
model and automatically fetch the relation. You can overwrite this by creating an includeShipments
method in ProductTransformer
, just like you would with Fractal:
/**
* Include related shipments.
*
* @param \App\Product $product
* @param array|null $parameters
* @return \League\Fractal\ResourceInterface
*/
public function includeShipments(Product $product, array $parameters = null)
{
return $this->resource($product->shipments);
}
The resource
method used above replaces Fractal's item
and collection
methods in the Transformer for creating a resource. It will automatically figure out wether it should be an item or collection resource based on the data. It will also resolve a transformer from the Shipment
model, if a transformer binding is set, just like the success
method. In fact, it accepts the exact same arguments as the success
method:
return $this->resource($product->shipments, new ShipmentTransformer);
You should be careful with executing any new database calls inside the include methods as you might end up with an unexpected amount of hits to the database.
The $relations
property specifies a list of relations available to be included. When you generate a transformer, the $relations
property will be equal to a wildcard, allowing all relations on the transformer:
protected $relations = ['*'];
If you only want to whitelist certain relations, you can instead set a list of relations you want to make available:
protected $relations = ['shipments', 'orders'];
Security warning: Since the transformer doesn't know what relations exists on a model unless you specify it in $relations
, you're technically allowing calls to any method on your model when using a wildcard. You should therefore consider always specifying a whitelist.
The $load
property specifies a list of relations to be autoloaded every time you transform data with the transformer. By mapping a transformer to the relation the package will also be able to automatically eager load all default relations, including nested ones:
protected $load = [
'shipments' => ShipmentTransformer::class,
'orders' => OrderTransformer::class,
];
If you're transforming non-model data or don't care about the eager loading, you can skip the transformer mapping and just specify a list of relations:
protected $load = ['shipments', 'orders'];
You don't have to add relations to both $relations
and $load
, all relations in $load
will be available by nature.
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);
});
}
We've already looked at how to transform data when creating success responses, however, you may want to transform data in other places than your controllers. An example of when you would want to transform data is in your broadcasted events. You're exposing data using websockets instead of HTTP, but you still want to receive the same transformed data in your frontend.
transform
HelperYou can use the transform
helper function to transform data without creating a response:
transform(Product::all());
Unlike the success
method, this wont serialize the data. However, it will resolve a transformer from the model if a binding is set, and you can overwrite the transformer by setting a second parameter. You can also specify a list of included relations as a third argument:
transform(Product::all(), new ProductTransformer, ['comments']);
In addition, if you want to blacklist any of the default loaded relations, you can fill the fourth parameter:
transform(Product::all(), new ProductTransformer, ['shipments'], ['orders']);
Transformer
FacadeInstead of using the transform
helper function, you can use the Transformer
facade to do the same thing:
Transformer::transform(Product::all(), new ProductTransformer, ['comments'], ['user']);
Transformer
ServiceBoth the helper method and facade uses the Flugg\Responder\Transformer
service class to apply the transformation. You can use the service yourself by injecting the service:
public function __construct(Transformer $transformer)
{
$transformer->transform(Product::all(), new ProductTransformer, ['comments'], ['user']);
}
Model attributes are traditionally specified in snake case, however, you might prefer to use camel case in your response data. A transformer makes for a perfect location to convert the attributes, like the soldOut
field in the example below:
return responder()->transform(Product::all(), function ($product) {
return ['soldOut' => (bool) $product->sold_out];
})->respond();
After responding with camel case, you probably want to let people send in request data using camel case parameters as well. The package provides a Flugg\Responder\Http\Middleware\ConvertToSnakeCase
middleware you may append to the $middleware
array in app/Http/Kernel.php
to convert all request parameters to snake case automatically:
protected $middleware = [
// ...
\Flugg\Responder\Http\Middleware\ConvertToSnakeCase::class,
];
The middleware will run before request validation, so you should specify your validation rules in snake case as well.
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. If using the default configuration, the above code would output the following JSON:
{
"success": false,
"status": 500,
"error": {
"code": null,
"message": null
}
}
You can fill the first parameter of the error
method to set an error code:
return responder()->error('sold_out_error')->respond();
You can also use integers as error codes.
Additionally, 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();
Alternatively, you can set the error messages in a language file, allowing for returning messages in different languages for different consumers. 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.',
];
ErrorMessageResolver
Instead of implementing the Transformable
contract for all models, an alternative approach is to bind the transformers using the bind
method on the TransformerManager
class. You can place the code below within AppServiceProvider
or an entirely new TransformerServiceProvider
:
use Flugg\Responder\ErrorMessageResolver;
public function boot()
{
$this->app->make(ErrorMessageResolver::class)->register([
'sold_out_error' => 'The requested product is sold out.',
]);
}
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": []
}
}
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.
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.
Handler
ClassTo 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.
ConvertsExceptions
TraitThe 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)
{
$this->convertDefaultException($exception);
if ($exception instanceof HttpException) {
return $this->renderResponse($exception);
}
return parent::render($request, $exception);
}
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 = [
ModelNotFoundException::class,
];
If you're using the trait option, you can disable all the default conversions by removing the call to convertDefaultException
in the render
method.
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);
},
]);
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:
<?php
namespace App\Exceptions;
use Flugg\Responder\Exceptions\Http\HttpException;
class SoldOutException extends HttpException
{
/**
* An HTTP status code.
*
* @var int
*/
protected $status = 400;
/**
* An error code.
*
* @var string|null
*/
protected $code = 'sold_out_error';
/**
* An 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:
vendor/bin/phpunit
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 flugged@gmail.com 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.