README

The signifly/laravel-api-responder package allows you to easily return API responses in your Laravel app.

Below is a small example of how to use it:

use Signifly\Responder\Concerns\Respondable;

class ProductController extends Controller
{
    use Respondable;

    public function index()
    {
        $paginator = Product::paginate();

        return $this->respond($paginator);
    }

    public function store(Request $request)
    {
        $product = Product::create($request->all());

        return $this->respond($product->fresh())
            ->setStatusCode(201); // responds with a 201 status code
    }

    public function show(Product $product)
    {
        return $this->respond($product);
    }

    public function destroy(Product $product)
    {
        $product->delete();

        return $this->respond($product); // return an empty 204 json response
    }
}

It will automatically resolve resources for the provided data if they exist.

Documentation

To get started follow the installation instructions below.

Installation

You can install the package via composer:

composer require signifly/laravel-api-responder

The package will automatically register itself.

You can optionally publish the config file with:

php artisan vendor:publish --tag="responder-config"

This is the contents of the published config file:

return [

    /*
     * The namespace to use when resolving resources.
     */
    'namespace' => 'App\\Http\\Resources',

    /*
     * Force the usage of resources.
     * 
     * It will throw a ResourceNotFoundException 
     * if it does not resolve a resource.
     */
    'force_resources' => false,

    /*
     * Indicates if the resources uses a naming convention with a type suffix.
     * 
     * If it is set to true it will try to resolve `UserResource`.
     */
    'use_type_suffix' => false,
    
];

Usage

The responder can be used in several ways.

Using the Facade

use Signifly\Responder\Facades\Responder;

class ProductController
{
    public function show(Product $product)
    {
        return Responder::respond($product);
    }
}

Using the Trait

use Signifly\Responder\Concerns\Respondable;

class ProductController
{
    use Respondable;

    public function show(Product $product)
    {
        return $this->respond($product);
    }
}

Using the Service Container

use Signifly\Responder\Contracts\Responder;

class ProductController
{
    public function show(Product $product, Responder $responder)
    {
        return $responder->respond($product);
    }
}

Custom response codes

You can set the status code of the response by using the setStatusCode method on the response from the responder.

return Responder::respond($data)
    ->setStatusCode(201);

Specific resource classes

If you would like to specify a resource class it can be passed as the second parameter to the respond method:

return Responder::respond($data, UserResource::class);

Forcing the usage of API resources

If you want to force the usage of API resources, you have to set the force_resources option to true in the config/responder.php file.

When set to true it will throw a ResourceNotFoundException if a resource for the associated model could not be found.

Using type suffixes

If you are using type suffixes as naming convention, when creating new resources, then you should set the use_type_suffix option to true in the config/responder.php file.

When set to true it expects your resources to be named like UserResource instead of just User.

Testing

composer test

Security

If you discover any security issues, please email dev@signifly.com instead of using the issue tracker.

Credits

License

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

signifly / laravel-api-responder

Maintainers

Details