README

Arya is a minimalist PHP web SAPI framework providing URI routing, dependency injection and middleware hooks. The framework leverages HTTP protocol adherence and SOLID design principles to maximize flexibility while maintaining simplicity and performance.

WARNING: Arya is still under development and there is very little unit-testing present at the moment. The project is moving towards an official v0.1.0 release but has not yet reached that point. Code may change at any time and without warning. Use at your own risk.

Basic Example

<?php
$app = (new Arya\Application)
    ->before(function($request) {...}) // <-- middleware before request handled
    ->route('GET', '/', 'anyFunction')
    ->route('GET', '/lambda', $anyClosure)
    ->route('GET', '/static', 'AnyClass::staticMethod')
    ->route('GET', '/instance', 'AnyClass::instanceMethod') // <-- auto dependency injection
    ->route('GET', '/args/{arg1:\d+}/{arg2:\d+}', 'numericArgsFunction')
    ->after(function($request, $response) { ... }) // <-- middleware before response sent
    ->run()
;

Project Goals

Model code on the HTTP/1.1 protocol as outlined in RFC 2616;
Build components using SOLID, readable and well-tested code;
Prevent vendor lock-in and static coupling;
Minimize performance overhead.

Requirements and Installation

Basic Requirements

PHP (5.4+)
FastRoute | high-performance routing
Auryn | automated dependency injection

Testing Requirements

PHPUnit | running automated tests
Artax | running automated tests

Download

Github

You can clone the latest Arya iteration at anytime from the Github repository. By using the --recursive option git will automatically retrieve dependency submodules for us.

$ git clone --recursive git://github.com/rdlowrey/Arya.git

Composer

$ php composer.phar create-project rdlowrey/arya /path/to/later/location/Arya dev-master

Manual Download

Archived tagged release versions are also available (or will be) for manual download on the project tags page.

Server Setup

Arya acts as a front-controller to route all requests. To make this work you must configure your front-facing server to direct all requests to a single file.

Apache

With Apache 2.2.16 or higher, you can use the FallbackResource directive in your configuration file (.htaccess/httpd.conf/vhost.conf):

FallbackResource /front_controller.php

If you have an older version of Apache you should instead add this block to your config file:

<IfModule mod_rewrite.c>
    Options -MultiViews

    RewriteEngine On
    RewriteBase /path/to/app
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ front_controller.php [QSA,L]
</IfModule>

Nginx

server {
  ...
  index front_controller.php;
  try_files $uri $uri/ /front_controller.php;
  ...
}

PHP Server

As of PHP 5.4 you can use the built-in development server to quickly run your application:

$ php -S localhost:8080 front_controller.php

Contributions

Contributions in the form of pull requests (PRs) are always appreciated! Before submitting a PR please read the CONTRIBUTORS file.

The Guide

Routing

Standard Route Targets
Extended Route Targets
Route Arguments
Route Execution Paths

Middleware

Before
After
Finalize

Dependency Injection

Auryn dependency injector

HTTP Protocol

The HTTP Request
Simple Responses
The HTTP Response
Callable Response Bodies

Other

App Options
Debug Mode
Custom Error Handlers

Server Setup

Apache
Nginx
PHP Server (5.4+)

Routing

Standard Route Targets

An Arya route definition consists of exactly three elements:

HTTP method verb
URI path
Target callable

Arya supports any valid PHP callable as a route target. This means that you can specify function names, lambdas, static class methods and array instance method constructions. Consider:

<?php
$app = (new Arya\Application)
    ->route('GET', '/', 'myFunctionName')
    ->route('GET', '/lambda-hello', function() { return 'Hello world'; })
    ->route('POST', '/static-method', 'MyClass::myStaticPostHandler')
    ->route('GET', '/array-callback', [$myObject, 'someMethod'])
    ->route('GET', '/instance-method', 'MyController::get') // <-- IMPORTANT
    ->run()
;

Routes are matched in the order in which they are assigned with the caveat that routes without arguments always take precedence over routes with arguments (see (Route Arguments)[#route-arguments]).

Extended Route Targets

You'll notice that in the above example code there's special attention paid to the final route, SomeClass::someMethod. We differentiate this route because it doesn't reference a static method. How is this possible? Well ...

Arya recursively instantiates and provisions classes for you using the include Auryn dependency injection library. Consider the following simple example in which our MyController class is automatically instantiated and invoked for requests to the / index resource:

<?php
class Templater {
    function render($uri) {
        return "<html><body><p>Hello from {$uri}!</p></body></html>";
    }
}
class MyController {
    private $templater;
    function __construct(Templater $tpl) {
        $this->templater = $tpl;
    }
    function get(Request $request) {
        return $this->templater->render($request['REQUEST_URI']);
    }
}

$app = (new Arya\Application)->route('GET', '/', 'MyController::get')->run();

IMPORTANT: Arya also recursively injects any dependencies you typehint in your controller method signatures. In the above example we use constructor injection to provide the Templater object that renders our HTML response. However, we could have alternatively typehinted the Templater in our MyController::get method signature and injected it at call time.

Route Arguments

Arya uses FastRoute for routing.

/lol-cats/{catType}/{catId:\d+}
/widgets/{widgetId:\d+}
/kumqats/{kumqatId}

When named URI arguments are matched they are available to route targets in two different ways:

As associative array keys in the $request['ROUTE_ARGS'] array
As parameters with matching names in the route target's method/function signature

So, let's consider a match for our /lol-cats route from above:

<?php

use Arya\Application;

function lolcatsFunction($request, $catType, $catId) {
    assert($catType === $request['ROUTE_ARGS']['catType']);
    assert($catId === $request['ROUTE_ARGS']['catId']);

    return '<html><body>woot!</body></html>';
}

$app = (new Application)
    ->route('GET', '/lol-cats/$catType/$#catId', 'lolcatsFunction')
    ->run();

The takeaway here is that you can accept your URI route arguments as parameters with matching names in your route target signature if you like but they'll always be available in the $request['ROUTE_ARGS'] array as well.

Route Execution Paths

Every client request follows one of three paths through the routing system:

No request URI match is found: 404 Not Found
A request URI is matched, but the HTTP verb does not match: 405 Method Not Allowed
The request URI and HTTP method match a route and the associated target is invoked

Middleware

One of Arya's goals is to retain PHP's ease of use while still exposing a standard API for middleware modification before and after each request.

Middleware Quick and Dirty

Arya uses universal Arya\Request and Arya\Response instances for each page load;
Middleware may modify the universal request/response instances before or after route handlers;
Middleware MUST return TRUE/FALSE/NULL and may only modify the request/response directly;
If a middleware returns TRUE then no more middleware of the same type (before/after/final) will execute;
"Before" middleware should only return TRUE if it assigns a response as Arya will treat this result as an indication that the route handler should not be invoked;
"After" middleware will always execute after "before" middleware and/or the routed application handler;
@TODO Mention "Final" middleware (not yet operational)

Before

@TODO Add URL rewriting example

After

The middleware concept is just as powerful for modifying responses after they're generated as it is for altering requests before they reach the application. Let's consider a standard use-case for an "after" middleware ...

Custom Error Pages

Arya provides no built-in abstraction for custom error pages because the middleware system exposes all the necessary tools for a manual implementation. Let's say we want to capture all error responses and replace them with our own custom error page. All we need to do is specify an "after" middleware callable to capture and modify such responses before they're sent to the client ...

<?php
use Arya\Response, Arya\Application;

function myErrorPageMiddleware(Response $response) {
    switch ($response->getStatus()) {
        case 404:
            $response->setBody('my custom 404 html');
            break;
        case 500:
            $response->setBody('my custom 500 html');
            break;
        default:
            // don't bother to modify any others
    }
}

(new Application)
    ->route('GET', '/', function() { return 'Hello World'; })
    ->after('myErrorPageMiddleware')
    ->run();

What's going on in this example? All we've done is register a middleware class method to be invoked after the application executes. Our myErrorPageMiddleware function simply checks to see if specific status codes were assigned and if so replaces the response entity body with our own custom HTML. Note that middleware callables are provisioned in the same way as applications; all we need to do is typehint our dependencies and they'll be provided automatically either in the constructor or callable signature (wherever the middleware asks for them).

Finalize

@TODO "Final" middleware not yet operational

Dependency Injection

Arya internally uses the Auyrn dependency injector.

To share our definitions, aliases etc. with Arya, we can pass our Auryn\Injector instance as the first argument to the Application constructor.

If no Auryn\Injector instance is passed, the Application class will instance its own injector.

HTTP Protocol

The HTTP Request

Arya represents every request as an Arya\Request instance. This class provides an object-oriented alternative to the superglobal anti-pattern present by default in PHP web SAPI environments.

Request Mutability

Request instances implement ArrayAccess to provide mutability for middleware callables. In this way it's possible for middleware components to alter the request to perform actions such as URI rewriting.

Request Provisioning

Because route targets are automatically provisioned they must typehint the Arya\Request class in their method signatures (extended instance method targets may also typehint in __construct). For example, the following route targets demonstrate equivalent ways to ask for the request instance in your application:

<?php
use Arya\Application, Arya\Request;

function myFunctionTarget(Request $request) {
    return "Hello from " . $request['REQUEST_URI'];
}

class MyCtorRouteClass {
    private $request;
    function __construct(Request $request) {
        $this->request = $request;
    }
    function myTarget() {
        return "Hello from " . $this->request['REQUEST_URI'];
    }
}

class MyMethodRouteClass {
    function myTarget(Request $request) {
        return "Hello from " . $request['REQUEST_URI'];
    }
}

$app = (new Application)
    ->route('GET', '/function', 'myFunctionTarget')
    ->route('GET', '/my-ctor-route', 'MyCtorRouteClass::myTarget')
    ->route('GET', '/my-method-route', 'MyMethodRouteClass::myTarget')
    ->run()
;

Simple Responses

One of the most user-friendly aspects of the PHP web SAPI is the ability to simply echo output as your HTTP response entity body. This approach, however, is suboptimal in terms of testability and enterprise sustainability. In the spirit of simplifying HTTP Arya allows application callables to return strings directly to generate a standard 200 response. Consider:

<?php
function helloWorld(Arya\Request $request) {
    return "Hello from " . $request['REQUEST_URI'];
}

$app = new Arya\Application;
$app->route('GET', '/', function(Arya\Request $request) {
    return "Hello from " . $request['REQUEST_URI'];
});
$app->run();

Arya actively prevents the manual output of response data via output buffering. If your application generates any output (including error output) the result is a 500 Internal Server Error response. When in DEBUG mode you'll receive a helpful print-out containing the output data. In production environments a generic 500 error message is displayed. This behavior is designed to funnel all output through your route target return values so that "after" middleware callables have an opportunity to inspect/modify output. Note that when in DEBUG mode this behavior also simplifies n00b-core browser output debugging at runtime.

The HTTP Response

When your application needs fine-grained control over the HTTP response a simple string is not enough. In these cases route targets may return an instance of the Arya\Response class.

@TODO Talk about status code

@TODO Talk about headers

@TODO Talk about entity body

Callable Response Bodies

@TODO

Other

@TODO Intro

App Options

@TODO

Debug Mode

@TODO

rdlowrey / arya

Maintainers

Details

README

Basic Example

Project Goals

Requirements and Installation

Basic Requirements

Testing Requirements

Download

Github

Composer

Manual Download

Server Setup

Apache

Nginx

PHP Server

Contributions

The Guide

Routing

Standard Route Targets

Extended Route Targets

Route Arguments

Route Execution Paths

Middleware

Before

After

Custom Error Pages

Finalize

Dependency Injection

HTTP Protocol

The HTTP Request

Simple Responses

The HTTP Response

Callable Response Bodies

Other

App Options

Debug Mode