Quick Start Rapid Prototyping

0: Understand the Basics

For an understanding of the high-level concepts involved see here:

Contextual,-Extendable-Configurations-and-More

Key-Configuration-Concepts

Also note that basic knowledge of Laravel is expected for this guide.

1: the Skeleton

The best place to start making a Scribe project is the Tempest Tools Skeleton project. It includes installation instructions in it's readme, it also has a vanilla branch if you want to make a project with out of the tests, or test related code in it.

tempest-tools-skeleton

2: the Entities

Make your entities as normal with a few small changes:

To use Scribe functionality Entities must extend: "TempestTools\Scribe\Laravel\Doctrine\EntityAbstract"

Entities need a getTTConfig method. Ideally, it should have a default context and placeholders for each mode.

public function getTTConfig(): array
{
	return [
		'default'=>[
			'create'=>[
			],
			'update'=>[
				'extends'=>[':default:create'],
			],
			'delete'=>[
				'extends'=>[':default:create'],
			],
			'read'=>[
				'extends'=>[':default:create']
			],
		],
	];
}

This will make an entity that is up for anything when the default context is called.

For info on how contexts work and how to build more functionality into your entities see here:

Setting-Up-Your-Entities

If you want to make building your entities as painlessly as possible I recommend the Skipper project:

www.skipper18.com

3: the Repositories

A Scribe Repository must extend "TempestTools\Scribe\Doctrine\RepositoryAbstract", or in the Skeleton application it can extend "App\Repositories\Repository".

It also needs a getTTConfig method. Ideally, it should have a placeholder for "default" context and "read" mode.

public function getTTConfig(): array
{
	return [
		'default'=>[
			'read'=>[
			]
		],
	];
}

This is a repository config that is up for anything.

For more information on setting up your repositories see here:

Setting-up-Your-Repositories

4: the Controllers

Scribe Controllers can be generated from the command line using the Skeleton application with the following command:

php artisan make:tempest-tools-controller {controller name} {repository name} '{namespace}'

For example:

php artisan make:tempest-tools-controller TestController TestRepository 'App\API\V1'

The command line tool dumps the new controllers above the correct directory in the Skeleton app and you will need to move them to the correct place.

The command line tool will make a getTTConfig method with a default context and placeholders for all the modes:

public function getTTConfig(): array
{
	return [
		'default'=>[
			'GET'=>[],
			'POST'=>[],
			'PUT'=>[],
			'DELETE'=>[]
		]
	];
}

This is a controller config that is up for anything.

5: the Routes

Lastly, you will need routes.

Routes are normal routes (using Dingo when done in the skeleton).

You will need to use the Tempest Tools Extractor on the route:

Laravel-Request-Extractor-Documentation

In order to use Scribe functionality on your routes, you will need to use the PrimeController Middleware.

You must add the Middleware to your Kernel.php in order to use it (handled for you in the skeleton):

\app\Http\Kernel.php

/**
 * The application's route middleware.
 *
 * These middleware may be assigned to groups or used individually.
 *
 * @var array
 */
protected $routeMiddleware = [
	'auth.basic' => AuthenticateWithBasicAuth::class,
	'throttle'   => ThrottleRequests::class,
	'acl' => AclMiddleware::class,
	'basic.extractor' => BasicDataExtractorMiddleware::class,
	'prime.controller' => PrimeControllerMiddleware::class
];

Your routes will need a "ttConfig" and a "ttFallback" to tell them what context to use for requests.

A very basic route just using a default context might look like this:

$api->version(
    'V1',
    [
        'middleware' => ['basic.extractor', 'prime.controller'],
        'provider'   => 'V1',
        'ttPath'=>['default'],
        'ttFallback'=>['default'],
    ],
    function () use ($api)
    {
        $api->resources([
            '/users'=> UserController::class
        ]);
    }
);

For detailed instructions on setting up your routes see here:

Setting-up-Your-Routes

Rapid Prototype Done

By default all Scribe functionality is wide open to allow the front end to make any request they want, so once you have finished this quick start guide you have a prototype your frontend team can start using for their development.

One thing you may need to do however is some index queries to your repository configs to make sure the frontend is receiving the data you expect them too.

Described here:

Setting-up-Your-Repositories

Now you can refine the rules and behaviors as you need.