README

This package contains some Laravel specific classes to make it easier to use swisnl/json-api-client with Laravel.

Installation

composer require swisnl/json-api-client-laravel

N.B. Make sure you have installed a PSR-18 HTTP Client and PSR-17 HTTP Factories before you install this package or install one at the same time e.g. composer require swisnl/json-api-client-laravel guzzlehttp/guzzle:^7.3.

HTTP Client

We are decoupled from any HTTP messaging client with the help of PSR-18 HTTP Client and PSR-17 HTTP Factories. This requires an extra package providing psr/http-client-implementation and psr/http-factory-implementation. To use Guzzle 7, for example, simply require guzzlehttp/guzzle:

composer require guzzlehttp/guzzle:^7.3

See Bind clients if you want to use your own HTTP client or use specific configuration options.

Service Provider and Facade Aliases

The required service provider and some facade aliases are automatically discovered by Laravel. However, if you've disabled package auto discover, you must add the service provider and optionally the facade aliases to your config/app.php file:

'providers' => [
    ...,
    \Swis\JsonApi\Client\Providers\ServiceProvider::class,
],
'aliases' => [
    ...,
    'DocumentFactory' => \Swis\JsonApi\Client\Facades\DocumentFactoryFacade::class,
    'DocumentParser' => \Swis\JsonApi\Client\Facades\DocumentParserFacade::class,
    'ItemHydrator' => \Swis\JsonApi\Client\Facades\ItemHydratorFacade::class,
    'ResponseParser' => \Swis\JsonApi\Client\Facades\ResponseParserFacade::class,
    'TypeMapper' => \Swis\JsonApi\Client\Facades\TypeMapperFacade::class,
],

Configuration

The following is the default configuration provided by this package:

return [
    /*
    |--------------------------------------------------------------------------
    | Base URI
    |--------------------------------------------------------------------------
    |
    | Specify a base uri which will be prepended to every URI.
    |
    | Default: empty string
    |
    */
    'base_uri' => '',
];

If you would like to make changes to the default configuration, publish and edit the configuration file:

php artisan vendor:publish --provider="Swis\JsonApi\Client\Providers\ServiceProvider" --tag="config"

Getting started

Simply let the container inject the DocumentClient and you're good to go!

use Swis\JsonApi\Client\DocumentClient;

class RecipeController extends Controller
{
    public function index(DocumentClient $client)
    {
        $document = $client->get('https://cms.contentacms.io/api/recipes');
    
        /** @var \Swis\JsonApi\Client\Collection&\Swis\JsonApi\Client\Item[] $recipes */
        $recipes = $document->getData();
        
        foreach ($recipes as $recipe) {
            // Do stuff with the recipe
        }
    }
}

Take a look at swisnl/json-api-client for more usage information.

Laravel HTTP Client

You can also use the built-in HTTP Client of Laravel if you prefer. Please note this requires Laravel 7+.

use Illuminate\Support\Facades\Http;
use Swis\JsonApi\Client\Facades\DocumentFactoryFacade;
use Swis\JsonApi\Client\Item;

$recipe = (new Item())
    ->setType('recipes')
    ->fill([
        'title' => 'Frankfurter salad with mustard dressing',
    ]);

$document = Http::asJsonApi() // Sets the Content-Type and Accept headers to 'application/vnd.api+json'.
    ->post('https://cms.contentacms.io/api/recipes', DocumentFactoryFacade::make($recipe))
    ->jsonApi(); // Parses the response into a JSON:API document.

Service Provider

The \Swis\JsonApi\Client\Providers\ServiceProvider registers the TypeMapper, JsonApi\Parser and both clients; Client and DocumentClient. Each section can be overwritten to allow extended customization.

Bind TypeMapper

The service provider registers the \Swis\JsonApi\Client\TypeMapper as a singleton so your entire application has the same mappings available.

Mapping types

You can manually register items with the TypeMapper or use the supplied TypeMapperServiceProvider:

use Swis\JsonApi\Client\Providers\TypeMapperServiceProvider as BaseTypeMapperServiceProvider;

class TypeMapperServiceProvider extends BaseTypeMapperServiceProvider
{
    /**
     * A list of class names implementing \Swis\JsonApi\Client\Interfaces\ItemInterface.
     *
     * @var string[]
     */
    protected $items = [
        \App\Items\Author::class,
        \App\Items\Blog::class,
        \App\Items\Comment::class,
    ];
}

Bind Clients

The service provider registers the Client and DocumentClient to your application. By default the Client uses php-http/discovery to find an available HTTP client, request factory and stream factory so you don't have to setup those yourself. You can specify your own HTTP client, request factory or stream factory by customizing the container binding. This is a perfect way to add extra options to your HTTP client or register a mock HTTP client for your tests:

class ServiceProvider extends \Illuminate\Support\ServiceProvider
{
    public function register()
    {
        $this->app->bind(\Swis\JsonApi\Client\Client::class, function ($app) {
            if ($app->environment('testing')) {
                $httpClient = new \Swis\Http\Fixture\Client(
                    new \Swis\Http\Fixture\ResponseBuilder('/path/to/fixtures')
                );
            } else {
                $httpClient = new \GuzzleHttp\Client(
                    [
                        'http_errors' => false,
                        'timeout' => 2,
                    ]
                );
            }
    
            return new \Swis\JsonApi\Client\Client($httpClient);
        });
    }
}

N.B. This example uses our swisnl/php-http-fixture-client when in testing environment. This package allows you to easily mock requests with static fixtures. Definitely worth a try!

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

composer test

Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please email security@swis.nl instead of using the issue tracker.

License

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

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

SWIS ❤️ Open Source

SWIS is a web agency from Leiden, the Netherlands. We love working with open source software.

swisnl / json-api-client-laravel

Maintainers

Details