Routing

Building a performant web application with Aurora is easy due to its lightning fast router.

In its most simple form, a route can be a Closure:

router()->get('/index', function(ServerRequestInterface $request, ResponseInterface $response) {
    $response->getBody()->write('Hello world!');
});

First you get the Router instance with the router() function, then you call its get() method to register a route that responds to the HTTP GET verb and pass a Closure that takes two arguments: $request a ServerRequestInterface and $response a ResponseInterface (from PSR-7). This is your route handler.

A route handler should process the $request data and write the result to the $response body, be it a JSON payload, an HTML page, etc.

As mentioned earlier, the $request and $response objects are implementations of the PSR-7 ServerRequestInterface and ResponseInterface interfaces, so you can for example, get the request verb:

router()->all('/index', function(ServerRequestInterface $request, ResponseInterface $response) {
    switch ( $request->getMethod() ) {
        case 'GET':
            $response->getBody()->write('GET');
        break;
        case 'POST':
            $response->getBody()->write('POST');
        break;
    }
});

Note that this time we used the all() method to register a route handler for all the HTTP verbs, but you may use any of the following if you just need to process a single HTTP method:

• get
• post
• put
• patch
• delete
• options

Also there's a match() method that takes an array of supported verbs in case you need to mix and match them:

router()->match(['put', 'patch'], '/index', function(ServerRequestInterface $request, ResponseInterface $response) {
    $response->getBody()->write('PUT or PATCH');
});

There is too a view() method which will render a view from a template, but that is explained with greater detail in the next topic, Views.

Controllers

Although it is completely valid to have all your handlers in Closure form, you may end up with a code spaghetti: an unreadable mess of routes that is difficult to troubleshoot and diagnose.

Controllers offer a layer of separation for the different parts of your application, for example, you can have a controller for your Users module, another for Products, etc., keeping the logic of each module in a separate file.

To create a controller from the CLI just run:

php aurora create:controller UsersController

The above will create a file name UsersController.php in your app/Http/Controllers directory with the following structure:

<?php

declare(strict_types = 1);

namespace App\Http\Controllers;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

use Aurora\Router\Controller;

class UsersController extends Controller {

    /**
     * Index action
     * @param  ServerRequestInterface $request  Request object
     * @param  ResponseInterface      $response Response object
     * @return void
     */
    public function index(ServerRequestInterface $request, ResponseInterface $response): void {
        $response->getBody()->write('UsersController::index');
    }
}

Each controller can have any number of actions, that is, route handler functions. For example, you may want to add a create action to your controller:

public function create(ServerRequestInterface $request, ResponseInterface $response): void {
    $response->getBody()->write('UsersController::create');
}

Once you've created the controller, you may add it to the router, but this time we will use a handy concept, the Route groups.

Route groups

The router allows you to group your routes for a better, hierarchical structure.

For example, you may have an index and a create route for your Users module, both of them are under the /users prefix. Grouping them is easy:

router()->group('/users', function(RouteGroup $group) {
    $group->get('/', [UsersController::class, 'index']);
    $group->get('/create', [UsersController::class, 'create']);
});

Notice how we passed the handler functions: an array with the controller class name and the action method name.

Route groups can also have their own middleware stack:

router()->group('/users', function(RouteGroup $group) {
    $group->get('/', [UsersController::class, 'index']);
    $group->get('/create', [UsersController::class, 'create']);
})->with(AuthMiddleware::class);

Next up, Views.