usox / sharesta

Sharesta (Strict HAck RESTful Apis) is a micro framework to build simple and easy to use rest-like applications - written in strict hack.

Sharesta - Strict HAck RESTful Apis

A micro framework to build simple and easy to use rest-like apis - written in strict hack (Hack).

Usage

First, build some classes containing your logic..

final class HomeRoute implements \JsonSerializable {

    public function jsonSerialize(): string {
        return 'Welcome home';
    }
}

final class UpdateUserRoute implements \JsonSerializable {

    public function __construct(
        private int $user_id,
        private \Usox\Sharesta\RequestInterface $request
    ): void {
    }

    public function jsonSerialize(): bool {
        // do some magic, e.g. access the request body by $this->request
        return true;
    }

}

Now create a class containing your route configurations.

final class Routes implements Usox\Sharesta\RoutesInterface {

    public function registerRoutes(Usox\Sharesta\RouterInterface $router): void {
        $router->get(
            '/',
            (Usox\Sharesta\RequestInterface $request): \JsonSerializable ==> {
                return new HomeRoute();
            }
        );

        /**
         * Get variables from the path (e.g. `http://some.tld/users/123`)
         */
        $router->post(
            '/users/:id',
            (Usox\Sharesta\RequestInterface $request): \JsonSerializable ==> {
                return new UpdateUserRoute(
                    $request->getUriValues('id'),
                    $request->getRequestBody()
                );
            }
        );
    }
}

Setup sharesta, register your routes and let the application controller handle your requests.

<?hh // strict

require_once 'vendor/autoload.php';

<<__Entrypoint>>
function main(): noreturn {
	/* HH_IGNORE_ERROR[2050] */ $get_vars = dict($_GET);
	/* HH_IGNORE_ERROR[2050] */ $server_vars = dict($_SERVER);

    $factory = new Usox\Sharesta\ApiFactory();
    $router = $factory->createRouter(
        $server_vars,
        $get_vars
    );

    $routes = new Routes();
    $routes->registerRoutes($router);

    $router->route(
        '' // path to the file. Leave it empty if your server configuration defaults to index.hh
    );

    die(0);
}

Example

See example/webroot/index.hh for an example.

sharesta's Issues

Support of http request/response interface

see https://github.com/facebookexperimental/hack-http-request-response-interfaces

Drop mockery

Mockery is dropping hhvm support, so we are dropping mockery.

mockery/mockery#835

Introduce a factory

To simplify the class creation process and to allow more unit tests, a Factory class should be introduced

Methods to retrieve values from RequestBody with specific type

Currently, the only way to retrieve request values from the request body is accessing getBody(): Map<string, mixed> within RequestBody. All values within this Map are mixed, therefor various type-checks within the routes/handlers are necessary to maintain strict typing which results in code duplications.
Maybe it would make sense to provide a bunch of methods which retrieve the values from the Map and cast them automatically, e.g. for scalars and traversables.