link-hack/router

Link-Hack is a Hack Lang HHVM version of Amanpreet Singh's Simple PHP Router

Link-Hack is a Hack Lang HHVM version of Amanpreet Singh's minimal PHP Router https://github.com/apsdehal/Link

A minimal router for your webapps and APIs that effortlessly links all of your project. Its fast and to the point., _(*1)

Features

• RESTful routing
• Wildcards to help simplify writing routes
• Regex routes to unleash any possibility
• Named routes to help you create links easily
• Before and after routes function support
• Tested with Ubuntu 14.04, hhvm 3.2.0-dev+2014.06.18 (rel), nginx 1.4.6

Dependencies

Hack HHVM

http://docs.hhvm.com/manual/en/install.php, _(*2)

Nginx

http://wiki.nginx.org/Install, _(*3)

Install

Manual Include

    require("Link-Hack/src/Link.hh");

Composer

    composer require link-hack/router

Config

Nginx

server {
        listen 80 default_server;
        listen [::]:80 default_server ipv6only=on;

        root /path/Link-Hack/src/; # Changet to path of your environment
        server_name _; #catchall

    if (!-e $request_filename)
    {
            rewrite ^/(.*)$ /YourRouter.hh?/$1 last;
            break;
    }

        location / {

        root /path/Link-Hack/src/; # Changet to path of your environment
        fastcgi_pass   127.0.0.1:9000; #Whatever HHVM daemon is set to run on.
        # or if you used a unix socket
        # fastcgi_pass   unix:/var/run/hhvm/hhvm.sock;
        fastcgi_index  YourRouter.hh;
        fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include        fastcgi_params;

        }

}

Basics

Simple Routing

function routeMe(): void
{
    echo 'I am routed';
}

Link::all( Map{
    '/' => Map{'routeMe' => []}
});

Named Routing

In Link-Hack routes can be named and then further used generating links in a simple and elegant way., _(*4)

function nameMe() :void
{
    echo 'I am named';
}

Link::all( Map{
    '/named' => Map{'nameMe' => [], 'Its my name' => []}
});

Names to routes must be given as second argument in array while the first being the route handler., _(*5)

Usage

These named routes can be used in creating in hassle free links., _(*6)

    <a href="<?hh echo Link::route('Its my name') ?>">Go to named route</a>

Routing with classes

Link can handle classes as Route handler easily, but remember non-static class will be handled both on construct and RESTfully., _(*7)

$routes = Map{
    '/' => Map{'IndexController::getMeHome' => []}, // Static function
    '/home' =>  Map{'HomeController' => []}, // Class
    '/office' =>  Map{'OfficeController' => []} // Class
});

Link::all($routes);

RESTful routing

RESTful routing is a breeze for Link-Hack., _(*8)

class HomeController
{

    function get() :void
    {
        echo 'You have got to home :)';
    }

    function post() :void
    {
        echo 'You have posted to home';
    }

    function put() :void
    {
        echo 'You have put to home';
    }

    function delete() :void
    {
        echo 'You have deleted the home :(';
    }
}

Link::all( Map{
    '/' => Map{'HomeController' => [], 'HomeRoute' => []}
});

Dynamic Routes

Regex Shorthands

Link-Hack supports numbers, string and alphanumeric wildcards which can be used as {i} {s} {a} respectively., _(*9)

$routes = Map{
    '/' => Map{'IndexController' => []},
    '/{i}' => Map{'IndexController' => []},
        // Parameter in place of {i} will be passed to IndexController
    '/posts/{a}/{i}/{s}' => Map{'PostsController' => []}
};

Link::all($routes);

Pure Regex

Link-Hack supports writing your own regex based routes., _(*10)

$routes = Map{
    '/regex/([\d]+)/([a-zA-Z]+)/([a-zA-Z]+)' => Map{'regexController' => []}
};

Link::all($routes);

Supplementary Handlers

Through Link-Hack, universal before and after handlers can be added, such that these are executed always before and after any route is routed. This can be done as follows:, _(*11)

function universalBeforeHandler( $id ) :void
{
    echo 'Hello I occurred before with ' . $id . '\n';
}

function universalAfterHandler( ?$id ) :void
{
    if( $id )
        echo 'Hello I occurred after with ' . $id;
    else
        echo 'I simply occurred after';
}

function main() :void
{
    echo 'I simply occurred\n'
}

Link::before( Map{'universalBeforeHandler' => array('12')} ); // If you want to pass parameters to them, pass them as arrays
Link::after( Map{'universalAfterHandler' => []} ); // else just don't specify them.

Link::all( Map{
    '/' => Map{'main' => []}
})

Now go to '/' in your browser to find:, _(*12)

Hello I occurred before with 12

I simply occurred

I simply occurred after.

Passing Parameters to Named Routes

You can pass parameters to named routes if the have wildcards in the route path, this will thus generate dynamic links through a single named route., _(*13)

function nameMe( $i, $s ) :void
{
    echo 'I am named and I have been passed ' . $i . $s ;
}

Link::all( Map{
    '/named/{i}/{s}' => Map{'nameMe' => [], 'Its my name' => []}
});

Now generate a link through Link, _(*14)

echo Link::route( 'Its my name', array(1, 'Me') );

This in turn will generate /named/1/Me and the browser will return I am named and I have been passed 1Me, _(*15)

[404,500] Errors

You should probably add a 404 handler to your routes Map, Link will take care of handling routes that are not found. In case, Link-Hack doesn't find a 404/500 route defined, it will just send the appropriate header. The 500 route will be executed if there is any exceptions thrown from the controllers/methods/functions/closure called., _(*16)

function notFound() :void
{
    echo 'This page is missing';
}

function errorFound() :void
{
    echo 'Oops, something went wrong, try again later';
}

function mainPage() :void
{
    throw new Exception('Meh? :(');
}

Link::all( Map{
    '/' => Map{'mainPage' => []},
    '404' => Map{'notFound' => []},
    '500' => Map{'errorFound' => []}
});

License

Creative Commons Attribution-ShareAlike 3.0 Unported

http://creativecommons.org/licenses/by-sa/3.0/, _(*17)