realpage / json-api-for-lumen
Lumen helpers to help ease implementation of json-api standards
Installs: 14 180
Dependents: 0
Suggesters: 0
Security: 0
Stars: 10
Watchers: 4
Forks: 7
Open Issues: 5
Requires
- php: ^7.0
- illuminate/http: ^5.4
- illuminate/support: ^5.4
- neomerx/json-api: 1.*
Requires (Dev)
- mockery/mockery: 1.0.0-alpha1
- phpunit/phpunit: ^6.0
- scrutinizer/ocular: ~1.1
- squizlabs/php_codesniffer: ~2.8
README
Lumen helpers to help ease implementation of json-api standards
Install
Via Composer
$ composer require realpage/json-api-for-lumen
Lumen
You can register the service provider in bootstrap/app.php
$app->register(RealPage\JsonApi\Lumen\ServiceProvider::class);
Usage
Middleware
Enforcing Media Types
Fulfills the server responsibilities section of the json-api docs. This should wrap all endpoints that are json-api spec compliant.
You can register the middleware in bootstrap/app.php
$app->routeMiddleware([ 'json-api.enforce-media-type' => RealPage\JsonApi\Middleware\EnforceMediaType::class, ]);
You can then use the middleware within your routes.php
file
$app->get('quotes', ['middleware' => 'json-api.enforce-media-type', function () { // }]);
Validation
Use Laravel's validation capabilities to validate your requests and this package will handle converting failed validation to valid json-api responses.
Add this entry to your exception handler
use Illuminate\Http\Response; use Neomerx\JsonApi\Encoder\Encoder; use Neomerx\JsonApi\Exceptions\JsonApiException; use Neomerx\JsonApi\Contracts\Http\Headers\MediaTypeInterface; // automatically encode exceptions as valid json-api json responses if ($e instanceof JsonApiException) { return new Response(Encoder::instance()->encodeErrors($e->getErrors()), $e->getHttpCode(), [ 'Content-Type' => MediaTypeInterface::JSON_API_MEDIA_TYPE, ]); }
Extending a few classes is all that's needed:
use RealPage\JsonApi\Validation\ValidatesRequests; class MyValidator extends ValidatesRequests { public function rules() : array { return array_merge(parent::rules(), [ 'data.attributes.name' => 'required', ]); } public function messages() : array { return array_merge(parent::messages(), [ 'data.attributes.name.required' => 'A name is required', ]); } }
use RealPage\JsonApi\Requests\Request; use RealPage\JsonApi\Validation\ValidatesRequests; class MyRequest extends Request { public function validator() : ValidatesRequests { return new MyValidator(); } }
In the controller you'd just call validate on the request:
public function store(MyRequest $request) { $request->validate(); // do stuff }
Encoder
Configures instances of Neomerx\JsonApi\Encoder\Encoder
to encode your JSONAPI responses.
You can configure a default encoder like so in config/json-api.php
:
<?php return [ 'media-type' => 'application/vnd.api+json', 'schemas' => [ App\Models\MyModel::class => App\Schemas\MySchema::class, ], 'jsonapi' => true, 'encoder-options' => [ 'options' => JSON_PRETTY_PRINT, ], 'meta' => [ 'apiVersion' => '1.1', ], ];
You can then retrieve the encoder in your Controller class:
<?php namespace App\Http\Controllers; use Illuminate\Http\Request; use Illuminate\Support\Facades\Log; use RealPage\JsonApi\EncoderService; use App\Model\MyModel; class MyController extends ApiController { protected $status; protected $encoder; public function __construct(EncoderService $encoder) { $this->encoder = $encoder->getEncoder(); } public function index(Request $request) { $data = [ new MyModel(1, 'Some', "Attribute") ]; return response($this->encoder->encodeData($data)); } }
Additional named encoders can be configured like:
<?php return [ 'media-type' => 'application/vnd.api+json', 'schemas' => [ App\Models\MyModel::class => App\Schemas\MySchema::class, ], 'jsonapi' => true, 'encoder-options' => [ 'options' => JSON_PRETTY_PRINT, ], 'meta' => [ 'apiVersion' => '1.1', ], 'encoders' => [ 'custom' => [ 'jsonapi' => true, 'encoder-options' => [ 'options' => JSON_PRETTY_PRINT, ], 'meta' => [ 'apiVersion' => '2.0', ], ] ] ];
and then retrieved like:
$this->encoder = $encoder->getEncoder('custom');
Change log
Please see CHANGELOG for more information what has changed recently.
Testing
$ composer test
Contributing
Please see CONTRIBUTING for details.
License
The MIT License (MIT). Please see License File for more information.