groundwork/groundwork-hacklang

A Hack framework for making RESTful JSON APIs

groundwork-hacklang - A micro-framework for RESTful JSON API development

, _(*1)

written in (mostly) strict Hack., _(*2)

This is a rewrite of groundwork, from PHP to mostly strict Hack - "mostly" because there is currently no way to bootstrap Hack code in strict mode (since it doesn't allow top level code), and also due to some reliance on the $_SERVER super global., _(*3)

groundwork is a lightweight RESTful-like framework that is designed to accept input and output in JSON. It is designed to quickly get a backend communicating with a backbone.js, or equivalent, frontend., _(*4)

groundwork-hacklang offers the following features:

• Assign routes to a closure.
• Routes support parameters you can label and retrieve by name.
• Stateless i.e. no $_SESSION, $_COOKIE references in the core.
• JSON input decoding and output encoding (just as backbone.js expects).
• Easily respond to requests using common HTTP status codes.
• Simple handling of GET, POST, PUT and DELETE HTTP methods on resources.
• A footprint of about 20KB at the core.

Examples

In the following example, I'll setup a quick route to respond to the request /articles/199. In app/Config/Routes.php, add:, _(*5)

$router->register('articles/:id', function($ioc) {
    $request = $ioc->get('request');
    $response = $ioc->get('response');
    if ($request instanceof Request && $response instanceof Response) {
        $response->send(200, $request->routeParams);
    } else {
        throw new ServerException('IoC failed to resolve.');
    }
});

This will respond with {"id":"199"} in the response body when handed the request /articles/199, and a HTTP status code of 200. This is not HTTP request method specific., _(*6)

To make a route respond to specific HTTP request methods, you can replace register() with get(), post(), put() or delete(). E.g.:, _(*7)

$router->post('articles/:id', function($ioc) {
    $request = $ioc->get('request');
    $response = $ioc->get('response');
    if ($request instanceof Request && $response instanceof Response) {
        $response->send(200, $request->routeParams);
    } else {
        throw new ServerException('IoC failed to resolve.');
    }
});

This would respond to /articles/199 only when the request is a HTTP POST., _(*8)

Installation

• Requires HHVM. Tested on 3.0.1.
• Requires Composer

groundwork is designed to have the 'public' directory as the only directory in the package accessible externally. This means that if you're installing groundwork under a VirtualHost in Apache, the web root should point to the 'public' directory (e.g. /var/www/groundwork/public, perhaps). If you're installing groundwork under a sub directory of web root and not as its own virtual host, then you can setup an Apache alias to the public directory to achieve a nicer directory on the web side., _(*9)

The file app/Config/Config.php contains the baseurl property which you will need to change to reflect where groundwork exists relative to the web root - e.g. if it is installed into http://localhost/bar/, then '/bar/' would be your value for this., _(*10)

Run composer update from the project root. Groundwork has no inbuilt requirments as far as packages go, but does make use of the Composer class autoloading., _(*11)

Tests

A basic function test is provided inside app/Tests for the example home resource class. There are also unit tests available in framework/Tests. To run the tests, I've found this command works (from the root groundwork dir):, _(*12)

hhvm $(which phpunit), _(*13)

License

groundwork-hacklang is open-sourced software licensed under the MIT License., _(*14)