Pass around new Context object; update docs; implement once()

Author: tobyzerner

README.md

@@ -18,11 +18,10 @@ $type->attribute('firstName')
 Use the `get` method to define custom retrieval logic for your attribute, instead of just reading the value straight from the model property.
 
 ```php
-use Psr\Http\Message\ServerRequestInterface as Request;
-use Tobyz\JsonApiServer\Schema\Attribute;
+use Tobyz\JsonApiServer\Context;
 
 $type->attribute('firstName')
-    ->get(function ($model, Request $request, Attribute $attribute) {
+    ->get(function ($model, Context $context) {
         return ucfirst($model->first_name);
     });
 ```

docs/attributes.md

@@ -7,7 +7,7 @@ Optionally pass a closure that returns a boolean value.
 ```php
 $type->creatable();
 
-$type->creatable(function (Request $request) {
+$type->creatable(function (Context $context) {
     return $request->getAttribute('user')->isAdmin();
 });
 ```
@@ -17,7 +17,7 @@ $type->creatable(function (Request $request) {
 When creating a resource, an empty model is supplied by the adapter. You may wish to override this and provide a custom model in special circumstances. You can do so using the `newModel` method:
 
 ```php
-$type->newModel(function (Request $request) {
+$type->newModel(function (Context $context) {
     return new CustomModel;
 });
 ```
@@ -29,7 +29,7 @@ $type->newModel(function (Request $request) {
 Run before the model is saved.
 
 ```php
-$type->onCreating(function ($model, Request $request) {
+$type->onCreating(function ($model, Context $context) {
     // do something
 });
 ```
@@ -39,7 +39,7 @@ $type->onCreating(function ($model, Request $request) {
 Run after the model is saved.
 
 ```php
-$type->onCreated(function ($model, Request $request) {
-    // do something
+$type->onCreated(function ($model, Context $context) {
+    $context->meta('foo', 'bar');
 });
 ```

docs/create.md

@@ -7,7 +7,7 @@ Optionally pass a closure that returns a boolean value.
 ```php
 $type->deletable();
 
-$type->deletable(function (Request $request) {
+$type->deletable(function (Context $context) {
     return $request->getAttribute('user')->isAdmin();
 });
 ```
@@ -19,7 +19,7 @@ $type->deletable(function (Request $request) {
 Run before the model is deleted.
 
 ```php
-$type->onDeleting(function ($model, Request $request) {
+$type->onDeleting(function ($model, Context $context) {
     // do something
 });
 ```
@@ -29,7 +29,7 @@ $type->onDeleting(function ($model, Request $request) {
 Run after the model is deleted.
 
 ```php
-$type->onDeleted(function ($model, Request $request) {
+$type->onDeleted(function ($model, Context $context) {
     // do something
 });
 ```

docs/delete.md

@@ -24,7 +24,7 @@ GET /users?filter[postCount]=5..15
 To define filters with custom logic, or ones that do not correspond to an attribute, use the `filter` method:
 
 ```php
-$type->filter('minPosts', function ($query, $value, Request $request) {
+$type->filter('minPosts', function ($query, $value, Context $context) {
     $query->where('postCount', '>=', $value);
 });
 ```

docs/filtering.md

@@ -1,8 +1,8 @@
 # Introduction
 
-**json-api-server** is an automated [JSON:API](http://jsonapi.org) server implementation in PHP.
+json-api-server is a comprehensive [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 models and database layer, without having 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:
 
@@ -19,7 +19,7 @@ The schema definition is extremely powerful and lets you easily apply [permissio
 
 ### Example
 
-The following example uses Eloquent models in a Laravel application. However, json-api-server can be used with any framework that can deal in PSR-7 Requests and Responses. Custom [Adapters](adapters.md) can be used to support other ORMs and data persistence layers.
+The following example uses Eloquent models in a Laravel application. However, json-api-server can be used with any framework that can deal in PSR-7 Requests and Responses. Custom [adapters](adapters.md) can be used to support other ORMs and data persistence layers.
 
 ```php
 use App\Models\{Article, Comment, User};

docs/index.md

@@ -7,7 +7,7 @@ If you want to restrict the ability to list a resource type, use the `listable`
 ```php
 $type->notListable();
 
-$type->listable(function (Request $request) {
+$type->listable(function (Context $context) {
     return $request->getAttribute('user')->isAdmin();
 });
 ```
@@ -19,7 +19,7 @@ $type->listable(function (Request $request) {
 Run before [scopes](scopes.md) are applied to the `$query` and results are retrieved.
 
 ```php
-$type->onListing(function ($query, Request $request) {
+$type->onListing(function ($query, Context $context) {
     // do something
 });
 ```
@@ -29,7 +29,7 @@ $type->onListing(function ($query, Request $request) {
 Run after models and relationships have been retrieved, but before they are serialized into a JSON:API document.
 
 ```php
-$type->onListed(function ($models, Request $request) {
+$type->onListed(function ($models, Context $context) {
     // do something
 });
 ```

docs/list.md

@@ -4,11 +4,13 @@ You can add meta information at various levels of the document using the `meta`
 
 ## Document Meta
 
-To add meta information at the top-level, call `meta` on the `JsonApi` instance:
+To add meta information at the top-level of a document, you can call the `meta` method on the `Context` instance which is available inside any of your schema's callbacks.
+
+For example, to add meta information to a resource listing, you might call this inside of an `onListed` listener:
 
 ```php
-$api->meta('requestTime', function (Request $request) {
-    return new DateTime;
+$type->onListed(function ($models, Context $context) {
+    $context->meta('foo', 'bar');
 });
 ```
 
@@ -17,7 +19,7 @@ $api->meta('requestTime', function (Request $request) {
 To add meta information at the resource-level, call `meta` on the schema builder.
 
 ```php
-$type->meta('updatedAt', function ($model, Request $request) {
+$type->meta('updatedAt', function ($model, Context $context) {
     return $model->updated_at;
 });
 ```

docs/meta.md

@@ -50,12 +50,11 @@ Be careful when making to-many relationships includable as pagination is not sup
 Relationships included via the `include` query parameter are automatically [eager-loaded](https://laravel.com/docs/8.x/eloquent-relationships#eager-loading) by the adapter, and any type [scopes](scopes) are applied automatically. You can also apply additional scopes at the relationship level using the `scope` method:
 
 ```php
-use Psr\Http\Message\ServerRequestInterface as Request;
-use Tobyz\JsonApiServer\Schema\HasOne;
+use Tobyz\JsonApiServer\Context;
 
 $type->hasOne('users')
     ->includable()
-    ->scope(function ($query, Request $request, HasOne $field) {
+    ->scope(function ($query, Context $context) {
         $query->where('is_listed', true);
     });
 ```
@@ -84,7 +83,7 @@ $api->resource('categories', new EloquentAdapter(Models\Category::class), functi
 $api->resource('posts', new EloquentAdapter(Models\Post::class), function (Type $type) {
     $type->hasOne('user') // 2
         ->includable()
-        ->load(function (array $models, array $relationships, Request $request, HasOne $field) {
+        ->load(function (array $models, array $relationships, Context $context) {
             // Since this request is to the `GET /categories` endpoint, $models
             // will be an array of Category models, and $relationships will be
             // an array containing the objects [1, 2] above.
@@ -114,7 +113,7 @@ You can add meta information to a relationship using the `meta` method:
 
 ```php
 $type->hasOne('user')
-    ->meta('updatedAt', function ($model, $user, Request $request) {
+    ->meta('updatedAt', function ($model, $user, Context $context) {
         return $user->updated_at;
     });
 ```

docs/relationships.md

@@ -7,8 +7,8 @@ This `scope` method allows you to modify the query builder object provided by th
 For example, to make it so the authenticated user can only see their own posts:
 
 ```php
-$type->scope(function ($query, ServerRequestInterface $request) {
-    $query->where('user_id', $request->getAttribute('userId'));
+$type->scope(function ($query, Context $context) {
+    $query->where('user_id', $context->getRequest()->getAttribute('userId'));
 });
 ```