isaackearl/artisan-api

An api service for Laravel or Lumen. Helps you send responses with the proper status and code. Uses Fractal for items and collections.

Artisan API

![Latest Unstable Version][ico-poser-unstable] ![Software License][ico-license] [![Coverage Status][ico-coveralls]][link-coveralls] , _(*1)

An api service for Laravel or Lumen. Helps you send responses with the proper status and code. Uses Fractal for items and collections., _(*2)

Setup/Install

Require it with Composer, _(*3)

``` bash $ composer require isaackearl/artisan-api, <sub>(*4)</sub>

Add the service provider to config/app.php

```php
// For Laravel add this to config/app.php
IsaacKenEarl\LaravelApi\Providers\ArtisanApiServiceProvider::class

// For Lumen add this to bootstrap/app.php 
$app->register(IsaacKenEarl\LaravelApi\Providers\ArtisanApiServiceProvider::class);

(Optional) Add the API facade in config/app.php, <sub>(*5)</sub>

'Api' => IsaacKenEarl\LaravelApi\Facades\Api::class,

Usage

In your controllers you can do stuff like this:, <sub>(*6)</sub>

``` php // do stuff like this public function show() { return Api::respondWithItem($user, new UserTransformer()); }, <sub>(*7)</sub>

// or like this:, <sub>(*8)</sub>

return Api::respondNotFound();, <sub>(*9)</sub>

There are alot of options.  Include the ArtisanApiInterface in your controller constructor and you can use it without the facade.

```php
    private $api;

    public function __construct(ArtisanApiServiceInterface $apiService)
    {
        $this->api = $apiService;
    }

    public function index()
    {
        $users = User::all();
        return $this->api->respondWithCollection($users, new UserTransformer());
    }

You can do custom stuff too and chain methods, <sub>(*10)</sub>

// you can respondWithError or respondWithMessage and customize the status code 
// and response code etc
return $this->api
            ->setStatus(401)
            ->setResponseCode(ResponseCodes::UNAUTHORIZED)
            ->respondWithError('Not logged in');

Take a look at the ArtisanApiInterface to see all the supported methods. You can find that here:, <sub>(*11)</sub>

ArtisanApiInterface, <sub>(*12)</sub>

Transformers

Transformers allow you to control how the data is presented in the response of your API. A typical transformer looks like this:, <sub>(*13)</sub>

class UserTransformer extends Transformer
{
    function transform($user)
    {

        return [
            'id' => $user->id,
            'name' => $user->name,
            'date_of_birth' => $user->date_of_birth->toDateString(),
            'email' => $user->getPrimaryEmail()
        ];
    }
}

You can generate a transformer with the make:transformer command, <sub>(*14)</sub>

php artisan make:transformer UserTransformer

This package uses laravel-fractal as it's fractal implementation. Check out their docs on their github page for more specific usage information and examples., <sub>(*15)</sub>

Since we are using the laravel-fractal package you can also publish the laravel-fractal config to customize the response data., <sub>(*16)</sub>

php artisan vendor:publish --provider="Spatie\Fractal\FractalServiceProvider"

Testing

bash $ composer test, <sub>(*17)</sub>

Contributing

Please see CONTRIBUTING and CONDUCT for details., <sub>(*18)</sub>

Credits

• Isaac Earl
• All Contributors

License

The MIT License (MIT). Please see License File for more information., <sub>(*19)</sub>