Preliminary support for extensions and various refactoring

Author: tobyzerner

composer.json

@@ -3,6 +3,7 @@
     "description": "A fully automated JSON:API server implementation in PHP.",
     "require": {
         "php": ">=7.1",
+        "ext-json": "*",
         "doctrine/inflector": "^1.3",
         "json-api-php/json-api": "^2.2",
         "nyholm/psr7": "^1.3",

docs/.vuepress/config.js

@@ -50,6 +50,7 @@ module.exports = {
         collapsable: false,
         children: [
           'errors',
+          'extensions',
           'laravel',
         ]
       }

docs/.vuepress/styles/palette.styl

@@ -0,0 +1 @@
+$accentColor = #0000ff

docs/adapters.md

@@ -7,7 +7,7 @@ You'll need to supply an adapter for each [resource type](https://jsonapi.org/fo
 ```php
 use Tobyz\JsonApiServer\Schema\Type;
 
-$api->resource('users', $adapter, function (Type $type) {
+$api->resourceType('users', $adapter, function (Type $type) {
     // define your schema
 });
 ```
@@ -26,10 +26,10 @@ $adapter = new EloquentAdapter(User::class);
 When using the Eloquent Adapter, the `$model` passed around in the schema will be an instance of the given model, and the `$query` will be a `Illuminate\Database\Eloquent\Builder` instance querying the model's table:
 
 ```php
-$type->scope(function (Builder $query) { });
+$type->scope(function (Builder $query) {});
 
 $type->attribute('name')
-    ->get(function (User $user) { });
+    ->get(function (User $user) {});
 ```
 
 ### Custom Adapters

docs/create.md

@@ -24,22 +24,22 @@ $type->newModel(function (Context $context) {
 
 ## Events
 
-### `onCreating`
+### `creating`
 
-Run before the model is saved.
+Run after values have been set on the model, but before it is saved.
 
 ```php
-$type->onCreating(function (&$model, Context $context) {
+$type->creating(function (&$model, Context $context) {
     // do something
 });
 ```
 
-### `onCreated`
+### `created`
 
-Run after the model is saved.
+Run after the model is saved, and before it is shown in a JSON:API document.
 
 ```php
-$type->onCreated(function (&$model, Context $context) {
+$type->created(function (&$model, Context $context) {
     $context->meta('foo', 'bar');
 });
 ```

docs/delete.md

@@ -14,22 +14,22 @@ $type->deletable(function (Context $context) {
 
 ## Events
 
-### `onDeleting`
+### `deleting`
 
 Run before the model is deleted.
 
 ```php
-$type->onDeleting(function (&$model, Context $context) {
+$type->deleting(function (&$model, Context $context) {
     // do something
 });
 ```
 
-### `onDeleted`
+### `deleted`
 
 Run after the model is deleted.
 
 ```php
-$type->onDeleted(function (&$model, Context $context) {
+$type->deleted(function (&$model, Context $context) {
     // do something
 });
 ```

docs/extensions.md

@@ -0,0 +1,81 @@
+# Extensions
+
+[Extensions](https://jsonapi.org/format/1.1/#extensions) allow your API to support additional functionality that is not part of the base specification.
+
+## Defining Extensions
+
+Extensions can be defined by extending the `Tobyz\JsonApiServer\Extension\Extension` class and implementing two methods: `uri` and `process`.
+
+You must return your extension's unique URI from `uri`. 
+
+For every request that includes your extension in the media type, the `handle` method will be called. If your extension is able to handle the request, it should return a PSR-7 response. Otherwise, return null to let the normal handling of the request take place.
+
+```php
+use Tobyz\JsonApiServer\Extension\Extension;
+use Psr\Http\Message\ResponseInterface;
+
+use function Tobyz\JsonApiServer\json_api_response;
+
+class MyExtension extends Extension
+{
+    public function uri(): string
+    {
+        return 'https://example.org/my-extension';
+    }
+
+    public function handle(Context $context): ?ResponseInterface;
+    {
+        if ($context->getPath() === '/my-extension') {
+            return json_api_response([
+                'my-extension:greeting' => 'Hello world!'
+            ]);
+        }
+        
+        return null;
+    }
+}
+```
+
+::: warning
+The current implementation of extensions has no support for augmentation of standard API responses. This API may change dramatically in the future. Please [create an issue](https://github.com/tobyzerner/json-api-server/issues/new) if you have a specific use-case you want to achieve.
+:::
+
+## Registering Extensions
+
+Extensions can be registered on your `JsonApi` instance using the `extension` method:
+
+```php
+use Tobyz\JsonApiServer\JsonApi;
+
+$api = new JsonApi('/api');
+
+$api->extension(new MyExtension());
+```
+
+The `JsonApi` class will automatically perform appropriate [content negotiation](https://jsonapi.org/format/1.1/#content-negotiation-servers) and activate the specified extensions on each request.
+
+## Atomic Operations
+
+An implementation of the [Atomic Operations](https://jsonapi.org/ext/atomic/) extension is available at `Tobyz\JsonApi\Extension\Atomic`.
+
+When using this extension, you are responsible for wrapping the `$api->handle` call in a transaction to ensure any database (or other) operations performed are actually atomic in nature. For example, in Laravel:
+
+```php
+use Illuminate\Support\Facades\DB;
+use Tobyz\JsonApiServer\Extension\Atomic;
+use Tobyz\JsonApiServer\JsonApi;
+
+$api = new JsonApi('/api');
+
+$api->extension(new Atomic());
+
+/** @var Psr\Http\Message\ServerRequestInterface $request */
+/** @var Psr\Http\Message\ResponseInterface $response */
+try {
+    return DB::transaction(function () use ($api, $request) {
+        return $api->handle($request);
+    });
+} catch (Exception $e) {
+    $response = $api->error($e);
+}
+```

docs/filtering.md

@@ -23,7 +23,7 @@ GET /users?filter[postCount]=5..15
 
 ## Custom Filters
 
-To define filters with custom logic, or ones that do not correspond to an attribute, use the `filter` method:
+To define filters with custom logic, or ones that do not correspond to a field, use the `filter` method:
 
 ```php
 $type->filter('minPosts', function ($query, $value, Context $context) {
@@ -34,7 +34,7 @@ $type->filter('minPosts', function ($query, $value, Context $context) {
 Just like [fields](visibility.md), filters can be made conditionally `visible` or `hidden`:
 
 ```php
-$type->filter('email', $callback)
+$type->filter('minPosts', $callback)
     ->visible(function (Context $context) {
         return $context->getRequest()->getAttribute('isAdmin');
     });

docs/index.md

@@ -2,7 +2,7 @@
 
 json-api-server is a [JSON:API](http://jsonapi.org) server implementation in PHP.
 
-It allows you to define your API's schema, and then use an [adapter](adapters.md) to connect it to your application's models and database layer, without having to worry about any of the server boilerplate, routing, query parameters, or JSON:API document formatting.
+It allows you to define your API's schema, and then use an [adapter](adapters.md) to connect it to your application's database layer. You don't have to worry about any of the server boilerplate, routing, query parameters, or JSON:API document formatting.
 
 Based on your schema definition, the package will serve a **complete JSON:API that conforms to the [spec](https://jsonapi.org/format/)**, including support for:
 
@@ -15,7 +15,7 @@ Based on your schema definition, the package will serve a **complete JSON:API th
 - **Deleting** resources (`DELETE /api/articles/1`)
 - **Error handling**
 
-The schema definition is extremely powerful and lets you easily apply [permissions](visibility.md), [transformations](writing.md#transformers), [validation](writing.md#validation), and custom [filtering](filtering.md) and [sorting](sorting.md) logic to build a fully functional API in minutes.
+The schema definition is extremely powerful and lets you easily apply [permissions](visibility.md), [transformations](writing.md#transformers), [validation](writing.md#validation), and custom [filtering](filtering.md) and [sorting](sorting.md) logic to build a fully functional API with ease.
 
 ### Example
 
@@ -25,25 +25,26 @@ The following example uses Eloquent models in a Laravel application. However, js
 use App\Models\{Article, Comment, User};
 use Tobyz\JsonApiServer\JsonApi;
 use Tobyz\JsonApiServer\Schema\Type;
-use Tobyz\JsonApiServer\Laravel\EloquentAdapter;
+use Tobyz\JsonApiServer\Adapter\EloquentAdapter;
 use Tobyz\JsonApiServer\Laravel;
 
 $api = new JsonApi('http://example.com/api');
 
-$api->resource('articles', new EloquentAdapter(Article::class), function (Type $type) {
+$api->resourceType('articles', new EloquentAdapter(Article::class), function (Type $type) {
     $type->attribute('title')
         ->writable()
         ->validate(Laravel\rules('required'));
 
-    $type->hasOne('author')->type('users')
+    $type->hasOne('author')
+        ->type('users')
         ->includable()
         ->filterable();
 
     $type->hasMany('comments')
         ->includable();
 });
 
-$api->resource('comments', new EloquentAdapter(Comment::class), function (Type $type) {
+$api->resourceType('comments', new EloquentAdapter(Comment::class), function (Type $type) {
     $type->creatable(Laravel\authenticated());
     $type->updatable(Laravel\can('update-comment'));
     $type->deletable(Laravel\can('delete-comment'));
@@ -56,12 +57,13 @@ $api->resource('comments', new EloquentAdapter(Comment::class), function (Type $
         ->writable()->once()
         ->validate(Laravel\rules('required'));
 
-    $type->hasOne('author')->type('users')
+    $type->hasOne('author')
+        ->type('users')
         ->writable()->once()
         ->validate(Laravel\rules('required'));
 });
 
-$api->resource('users', new EloquentAdapter(User::class), function (Type $type) {
+$api->resourceType('users', new EloquentAdapter(User::class), function (Type $type) {
     $type->attribute('firstName')->sortable();
     $type->attribute('lastName')->sortable();
 });

docs/laravel.md

@@ -1,5 +1,7 @@
 # Laravel Helpers
 
+These helpers improve the ergonomics of your API resource definitions when using the Laravel framework.
+
 ## Validation
 
 ### `rules`
@@ -10,10 +12,20 @@ Use Laravel's [Validation component](https://laravel.com/docs/8.x/validation) as
 use Tobyz\JsonApiServer\Laravel;
 
 $type->attribute('name')
-    ->validate(Laravel\rules('required|min:3|max:20'));
+    ->validate(Laravel\rules(['required', 'min:3', 'max:20']));
+```
+
+Pass a string or array of validation rules to be applied to the value. Validating array contents is also supported:
+
+```php
+$type->attribute('jobs')
+    ->validate(Laravel\rules([
+        'required', 'array',
+        '*' => ['string', 'min:3', 'max:255']
+    ]));
 ```
 
-Pass a string or array of validation rules to be applied to the value. You can also pass an array of custom messages and custom attribute names as the second and third arguments.
+You can also pass an array of custom messages and custom attribute names as the second and third arguments.
 
 ## Authentication