README

Part of the ndapi package. Provides discovery of entities and automatic API versioning, controllers, request and response generation, etc.

Usage

Entities

To generate a new entity in your application:

$ artisan make:entity Post

This will generate:

app/Models/Post.php
app/Http/V1/Controllers/PostController.php
app/Http/V1/Resources/PostResource.php
app/Http/V1/Requests/StorePostRequest.php
app/Http/V1/Requests/UpdatePostRequest.php
database/migrations/create_posts_table.php
app/Policies/PostPolicy.php

The generated controller extends the ndapi-entity ModelController which implements a standard set of REST endpoints for the entity.

You can immediately begin making requests like POST /posts to create a post, GET /posts to list all posts, GET /posts/1234 to get post 1234, PATCH /posts/1234 to patch the post, etc.

You can generate additional versions of an entity with:

$ artisan make:entity-version --api=v2

This will generate:

app/Http/V2/Controllers/PostController.php
app/Http/V2/Resources/PostResource.php
app/Http/V2/Requests/StorePostRequest.php
app/Http/V2/Requests/UpdatePostRequest.php

As well as add the appropriate v2 attribute to the originally generated model.

Attributes

Behaviour can be customized through the use of a variety of attributes:

Singular: Override the name for the singular form of this entity (Post)
Plural: Override the name for the plural form of this entity (Posts)
Request: Override the class used for Store/Update requests (StorePostRequest, UpdatePostRequest)
Route: Override the base route and controller for the entity (/posts, PostController)
```
     This can also disable automatic routes entirely by specifying `false`.
```

Each of these attributes is attached to the entity and each can have a version specified to allow updating behaviour between API versions.

Introspection

You can obtain information on any discovered Entity at runtime via the EntityManager class.

<?php

$entityManager = app()->make(\Nucleardog\Api\Entities\EntityManager::class);
$entity = $entityManager->for(\App\Models\Post::class, version: 'v1');
dump([
	'class' => $entity->class,
	'version' => $entity->version,
	'singular' => $entity->singular,
	'plural' => $entity->plural,
	'route' => $entity->route,
	'controller' => $entity->controller,
	'resource' => $entity->resource,
	'collection' => $entity->collection,
	'store' => $entity->store,
	'update' => $entity->update,
]);

TODO

Add Authorization calls to ModelController.

Tests

Phpunit is included in a separate composer file and must be explicitly installed:

$ cd tools/phpunit/
$ composer install

Once installed, the tests can be run from the root package folder with:

$ composer test

Legal

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

nucleardog / ndapi-entity

Maintainers

Details