Refactor, docs

Author: tobyzerner

.gitignore

@@ -1,3 +1,4 @@
 composer.lock
 vendor
-.phpunit.result.cache
+node_modules
+.phpunit.result.cache

README.md

@@ -4,10 +4,10 @@
     "require": {
         "php": "^7.2",
         "doctrine/inflector": "^1.3",
-        "json-api-php/json-api": "^2.0",
+        "json-api-php/json-api": "^2.2",
+        "nyholm/psr7": "^1.3",
         "psr/http-message": "^1.0",
-        "psr/http-server-handler": "^1.0",
-        "zendframework/zend-diactoros": "^2.1"
+        "psr/http-server-handler": "^1.0"
     },
     "license": "MIT",
     "authors": [

composer.json

@@ -0,0 +1,60 @@
+module.exports = {
+  base: '/json-api-server/',
+  title: 'json-api-server',
+  description: 'A fully automated JSON:API server implementation in PHP.',
+  evergreen: true,
+  themeConfig: {
+    search: false,
+    nav: [
+      { text: 'Guide', link: '/' }
+    ],
+    sidebar: [
+      {
+        title: 'Getting Started',
+        collapsable: false,
+        children: [
+          '/',
+          'install',
+          'requests',
+        ]
+      },
+      {
+        title: 'Defining Resources',
+        collapsable: false,
+        children: [
+          'adapters',
+          'scopes',
+          'attributes',
+          'relationships',
+          'visibility',
+          'writing',
+          'filtering',
+          'sorting',
+          'pagination',
+          'meta',
+        ]
+      },
+      {
+        title: 'Endpoints',
+        collapsable: false,
+        children: [
+          'list',
+          'create',
+          'update',
+          'delete',
+        ]
+      },
+      {
+        title: 'Advanced',
+        collapsable: false,
+        children: [
+          'errors',
+          'laravel',
+        ]
+      }
+    ],
+    repo: 'tobyz/json-api-server',
+    editLinks: true,
+    docsDir: 'docs'
+  }
+}

docs/.vuepress/config.js

@@ -0,0 +1,4 @@
+.theme-default-content > h1 + p {
+  font-size: 140%;
+  line-height: 1.5;
+}

docs/.vuepress/styles/index.styl

@@ -0,0 +1,37 @@
+# Adapters
+
+Adapters connect your API schema to your application's data persistence layer.
+
+You'll need to supply an adapter for each [resource type](https://jsonapi.org/format/#document-resource-object-identification) you define. You can define resource types using the `resource` method. For example:
+
+```php
+use Tobyz\JsonApiServer\Schema\Type;
+
+$api->resource('users', $adapter, function (Type $type) {
+    // define your schema
+});
+```
+
+### Eloquent Adapter
+
+An `EloquentAdapter` is provided out of the box to hook your resources up with Laravel [Eloquent](https://laravel.com/docs/8.x/eloquent) models. Instantiate it with the model class that corresponds to your resource.
+
+```php
+use App\Models\User;
+use Tobyz\JsonApiServer\Adapter\EloquentAdapter;
+
+$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->attribute('name')
+    ->get(function (User $user) { });
+```
+
+### Custom Adapters
+
+For other ORMs or data persistence layers, you can [implement your own adapter](https://github.com/tobyz/json-api-server/blob/master/src/Adapter/AdapterInterface.php).

docs/adapters.md

@@ -0,0 +1,32 @@
+# Attributes
+
+Define an [attribute field](https://jsonapi.org/format/#document-resource-object-attributes) on your resource using the `attribute` method.
+
+```php
+$type->attribute('firstName');
+```
+
+By default, the attribute will read and write to the property on your model with the same name. (The Eloquent adapter will `snake_case` it automatically for you.) If you'd like it to correspond to a different property, use the `property` method:
+
+```php
+$type->attribute('firstName')
+    ->property('fname');
+```
+
+## Getters
+
+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;
+
+$type->attribute('firstName')
+    ->get(function ($model, Request $request, Attribute $attribute) {
+        return ucfirst($model->first_name);
+    });
+```
+
+::: tip
+If you're using Eloquent, you could also define attribute [casts](https://laravel.com/docs/8.x/eloquent-mutators#attribute-casting) or [accessors](https://laravel.com/docs/8.x/eloquent-mutators#defining-an-accessor) on your model to achieve a similar thing. However, the Request instance will not be available in this context.
+:::

docs/attributes.md

@@ -0,0 +1,45 @@
+# Creating Resources
+
+You can allow resources to be [created](https://jsonapi.org/format/#crud-creating) using the `creatable` and `notCreatable` methods on the schema builder. 
+
+Optionally pass a closure that returns a boolean value.
+
+```php
+$type->creatable();
+
+$type->creatable(function (Request $request) {
+    return $request->getAttribute('user')->isAdmin();
+});
+```
+
+## Customizing the Model
+
+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) {
+    return new CustomModel;
+});
+```
+
+## Events
+
+### `onCreating`
+
+Run before the model is saved.
+
+```php
+$type->onCreating(function ($model, Request $request) {
+    // do something
+});
+```
+
+### `onCreated`
+
+Run after the model is saved.
+
+```php
+$type->onCreated(function ($model, Request $request) {
+    // do something
+});
+```

docs/create.md

@@ -0,0 +1,35 @@
+# Deleting Resources
+
+You can allow resources to be [deleted](https://jsonapi.org/format/#crud-deleting) using the `deletable` and `notDeletable` methods on the schema builder. 
+
+Optionally pass a closure that returns a boolean value.
+
+```php
+$type->deletable();
+
+$type->deletable(function (Request $request) {
+    return $request->getAttribute('user')->isAdmin();
+});
+```
+
+## Events
+
+### `onDeleting`
+
+Run before the model is deleted.
+
+```php
+$type->onDeleting(function ($model, Request $request) {
+    // do something
+});
+```
+
+### `onDeleted`
+
+Run after the model is deleted.
+
+```php
+$type->onDeleted(function ($model, Request $request) {
+    // do something
+});
+```

docs/delete.md

@@ -0,0 +1,47 @@
+# Error Handling
+
+The `JsonApi` class can produce [JSON:API error responses](https://jsonapi.org/format/#errors) from exceptions.
+
+This is achieved by passing the caught exception into the `error` method.
+
+```php
+try {
+    $response = $api->handle($request);
+} catch (Exception $e) {
+    $response = $api->error($e);
+}
+```
+
+## Error Providers
+
+Exceptions can implement the `ErrorProviderInterface` to determine what status code will be used in the response, and any JSON:API error objects to be rendered in the document.
+
+The interface defines two methods:
+
+* `getJsonApiStatus` which must return a string.
+* `getJsonApiErrors` which must return an array of JSON-serializable content, such as [json-api-php](https://github.com/json-api-php/json-api) error objects
+
+```php
+use JsonApiPhp\JsonApi\Error;
+use Tobyz\JsonApiServer\ErrorProviderInterface;
+
+class ImATeapotException implements ErrorProviderInterface
+{
+    public function getJsonApiErrors(): array
+    {
+        return [
+            new Error(
+                new Error\Title("I'm a teapot"),
+                new Error\Status($this->getJsonApiStatus())
+            )
+        ];
+    }
+
+    public function getJsonApiStatus(): string
+    {
+        return '418';
+    }
+}
+```
+
+Exceptions that do not implement this interface will result in a generic `500 Internal Server Error` response.