pixelindustries / laravel-jsonapi
Laravel JSON-API Base.
Requires
- php: >=5.6.0
- czim/laravel-dataobject: ^1.0
- justinrainbow/json-schema: ^5.2
- myclabs/php-enum: ^1.5
Requires (Dev)
- mockery/mockery: 0.9.*
- orchestra/testbench: 3.3.*
- phpunit/phpunit: 5.*
- scrutinizer/ocular: ~1.1
This package is auto-updated.
Last update: 2020-01-19 19:08:20 UTC
README
This package is abandoned!
Please use czim/laravel-jsonapi instead.
JSON-API Base
Basic application elements for JSON-API projects.
Offers means for quickly scaffolding JSON-API compliance for Laravel applications.
This does NOT provide the means to set up the API or the means for user authorisation.
Version Compatibility
Laravel | Package |
---|---|
5.3.x | ? |
5.4.x | ? |
Installation
Via Composer
$ composer require pixelindustries/laravel-jsonapi
Add the JsonApiServiceProvider
to your config/app.php
:
Pixelindustries\JsonApi\Providers\JsonApiServiceProvider::class,
Publish the configuration file.
php artisan vendor:publish
Exceptions
In your App\Exceptions\Handler
, change the render()
method like so:
<?php public function render($request, Exception $exception) { if (is_jsonapi_request() || $request->wantsJson()) { return jsonapi_error($exception); } // ...
This will render exceptions thrown for all JSON-API (and JSON) requests as JSON-API error responses.
Middleware
To enforce correct headers, add the Pixelindustries\JsonApi\Http|Middleware\JsonApiHeaders
middleware
to the middleware group or relevant routes. You can do this by adding it to your App\Http\Kernel
class:
<?php protected $middlewareGroups = [ 'api' => [ // ... \Pixelindustries\JsonApi\Http\Middleware\RequireJsonApiHeader::class, ], ];
Note that this will block access to any consumers of your API that do not conform their HTTP header use to the JSON-API standard.
Documentation
Request Data
Request Query String Data
JSON-API suggests passing in filter and page data using GET
parameters, such as:
{API URL}?filter[id]=13&page[number]=2
This package offers tools for accessing this information in a standardized way:
Using the jsonapi_query()
global helper function.
This returns the singleton instance of Pixelindustries\JsonApi\Support\Request\RequestParser
.
<?php // Get the full filter data associative array. $filter = jsonapi_query()->getFilter(); // Get a specific filter key value, if it is present (with a default fallback). $id = jsonapi_query()->getFilterValue('id', 0); // Get the page number. $page = jsonapi_query()->getPageNumber();
You can ofcourse also instantiate the request parser yourself to access these methods:
<?php // Using the interface binding ... $jsonapi = app(\Pixelindustries\JsonApi\Contracts\Support\Request\RequestQueryParserInterface::class); // Or by instantiating it manually ... $jsonapi = new \Pixelindustries\JsonApi\Support\Request\RequestQueryParser(request()); // After this, the same methods are available $id = $jsonapi->getFilterValue('id');
Request Body Data
For PUT
and POST
requests with JSON-API formatted body content, a special FormRequest is provided to validate and access request body data (\Pixelindustries\JsonApi\Http\Requests\JsonApiRequest).
This class may be extended and used as any FormRequest class in Laravel.
There is also a global help function jsonapi_request()
, that returns an instance of this class (and thus mimics Laravel's request()
).
<?php // Get validated data for the current request $jsonApiType = jsonapi_request()->getType(); $jsonApiId = jsonapi_request()->getId();
Encoding
This package offers an encoder to generate valid JSON-API output for variable input content.
With some minor setup, it is possible to generate JSON output according to JSON-API specs for Eloquent models and errors.
Eloquent
models, single, collected or paginated, will be serialized as JSON-API resources.
More information on encoding and configuring resources.
Custom Encoding & Transformation
To use your own transformers for specific class FQNs for the content to be encoded, map them in the jsonapi.transform.map
configuration key:
<?php 'map' => [ \Your\ContentClassFqn\Here::class => \Your\TransformerClassFqn\Here::class, ],
This mapping will return the first-matched for content using is_a()
checks.
More specific matches should be higher in the list.
As a last resort, you can always extend and/or rebind the Pixelindustries\JsonApi\Encoder\Factories\TransformerFactory
to provide your own transformers based on given content type.
Contributing
Please see CONTRIBUTING for details.
Credits
License
The MIT License (MIT). Please see License File for more information.