README

Web and REST tools built largely on top of Slim (previous iterations were based more substantially initially on Silex and subsequently Symfony components)

Initial installation

composer require getinstance/api_util

Generating a skeleton

You don't need to do this, but it can save time.

Skeleton: server mode

TODO - create a core-only generation.

api_util includes some skeleton generation tools. This one generates core components and an API endoint

$ php ./vendor/getinstance/api_util/bin/tools.php genendpoint dashserver getops\\dashboard\\server hello world,universe

genendpoint is the subcommand
dashserver is the name of the app. It should consist only of alphanumeric characters without symbols, punctuation, or spaces.
myorg\\dashserver is the package name (the double backslashes are required: The package will be rendered as myorg\dashserver in namespace and use statements)
hello is the endpoint name -- so we'll be calling GET /hello, POST /hello etc
world,universe are the fields relating the endpoint. There should be nothing but a comma between the fields.

This command will generate a controller, commands, a model class, a mapper. It will generate SQL for Mariadb. This will need to be tweaked since it does not add indexes and uses only the VARCHAR data type.

You can run the tool multiple times for different endpoints and the system will refuse to clobber existing files, writing them instead to the local tmp/ directory. You can then cut and paste the generated content.

TODO - improve tool to support a descriptor of multiple endpoints. Allow for injection of new endopoint into existing system (probably using comment tokens in source).

In the above case genendpoint wrote:

/scripts/* -- schemas and small scripts
- In particualar here look at create-db.sql and create-schema.sql. The first creates the database instance and corresponding database user. The second is the schema definitions of the database generated by the first script.
web/index.php -- the entry point to the system.
src/controller/Controller.php -- the InitWareInterface implementing component that runs routing. In the main index.php, an instance of this is added to the api_util FrontController component that handles the application lifecycle.
- api_util uses Slim's routing components
src/command/*.php classes for implementing GET, PUT, POST, DELETE endpoints for manipulating Hello data.
src/model/Hello.php -- a model class encapsulating the endpoint data.
src/model/HelloMapper.php -- writes and retrieves Hello data from the database
dockerbuild/ and docker-compose.yaml -- files for running the project in a Docker container

Skeleton: web mode

api_util was originally written as a quick way of generating APIs for micro-services. However, it has proved useful also as a Web micro-framework. As such it has evolved to support quite a few Web-UI related tools.

Here is how to generate a Web UI skeleton:

php ./vendor/getinstance/api_util/bin/tools.php genweb dashfe getops\\dashboard\\fe

This command generates the same core elements as the genendpoint command. Instead of individual command classes, though it creates a single controller command file: src/command/Main.php. It also generates a Twig template.

Here is the rundown of generated files:

/scripts/* -- schemas and small scripts
web/index.php -- the entry point to the system.
src/controller/Controller.php -- the InitWareInterface implementing component that runs routing. In the main index.php, an instance of this is added to the api_util FrontController component that handles the application lifecycle.
- api_util uses Slim's routing components
src/command/Main.php a central controller class which can be extended with new controller methods as needed.
dockerbuild/ and docker-compose.yaml -- files for running the project in a Docker container

Running the skeleton in Docker

Whether you have generated a API or a Web project you should be able to run a test instance in the same way if you have Docker installed:

docker compose up

This will generate an instance running on PHP's in-built server and accessible via localhost port 8080. If, as we often do, you wish to create both an API and a Web instance that work together, we recommend you combine their docker-compose.yaml files into a single instance that sits above both your repositories. You will want to adjust the public ports in this case so that they don't collide.

TODO - strip the Mariadb container from the Web generation templates

InitWare: Routing and Configuration

The main controller will invoke any classes which implement getinstance\api_util\controller\InitWareInterface. Here is that interface:

namespace getinstance\api_util\controller;

use DI\ContainerBuilder;
use Slim\App;


interface InitWareInterface
{
    public function handleConfiguration(ContainerBuilder $builder, Conf $conf): void;
    public function handleRouting(App $app): void;
}

You will likely only need to create one of these implementing classes for your routing. You can add this to the system in your index.php by calling FrontController::addInitWare()

require_once __DIR__.'/../vendor/autoload.php';

use getinstance\api_util\controller\FrontController;
use sulis\admonkey\controller\Controller;

$controller = new FrontController();
$controller->addInitWare(new Controller());
$controller->init(['confpath'=>__DIR__."/../conf/", 'confname'=>'myapp']);
$response = $controller->execute();

getinstance / api_util

Maintainers

Details