Rack'em

Getting Started

The easiest way to get up and running is by installing Composer. Go ahead and install it now if you haven't already.

Once composer is installed, you can require rackem/rackem as a dependency of your project.

		$ composer require rackem/rackem:@stable

Installing Rack'em globally is also pretty cool:

		$ composer global require rackem/rackem:@stable

If you have installed rackem globally, you can serve Rack'em applications as simply as rackem

Supported web servers

Your first Rack'em application

The best way to explain how Rack'em works is to dive right in with a tutorial.

Create a project

Create a project and require rackem/rackem

	$ mkdir tutorial
$ cd tutorial
$ composer require rackem/rackem:@stable
$ composer install

Create an application

A Rack'em application is any object that reponds to the method call() or a function closure. The rackem utility by default will look for config.php as your main application script, so we will create one now.

	$ touch config.php
	
<?php
# config.php
return \Rackem::run(function($env) {
		return array(
			200,
			array("Content-Type"=>"text/html"),
			array("<h1>Hello, from Rack'em!</h1>")
		);
});

A Rack'em application must return an array containing the HTTP response status, headers, and body. In our example application you can see that we are specifying a 200 response code, setting the Content Type to text/html, and supplying a short html greeting.

Run it

Once you have your config.php saved, all you need to do is run the rackem utility, and your first application is running!

	$ vendor/bin/rackem
== Rack'em on http://0.0.0.0:9393
>> Rack'em web server
>> Listening on 0.0.0.0:9393, CTRL+C to stop

Browse to http://localhost:9393 to see your application in action.

rackem

The rackem utility is a tiny web server that can serve up any Rack'em application. Though it is pretty fast when used developing locally, I would not recommend using it as a production web server.

When running the server, it will by default look for your main application script in config.php, you can alternatively specify the name of your main application script.

	$ vendor/bin/rackem index.php

By default rackem will run on localhost with port 9393. Both host and port are configurable:

	$ vendor/bin/rackem index.php --host dev.local --port 3000

If you pass --basic rackem will give you a basic html web server for serving up static websites.

	$ vendor/bin/rackem --basic

Class Reference

Rackem

Probably the class you are looking for. Provides helper functions for quickly creating and managing application stacks. Utilizes a single Rackem\Builder instance.

Rackem\Builder

Builder is the bread and butter of creating a Rack'em application stack.

Rackem\Exception

Halt an application with a specified response array.

Example:

<?php

public function call($env)
{
	throw new \Rackem\Exception(404, array("text/plain"), array("Not found"));
}

Rackem\File

An application used for serving file requests through Rack'em. Uses $env['PATH_INFO'] to determine the path to the file.

Example:

<?php

public function call($env)
{
	$file = new \Rackem\File(__DIR__);
	return $file->call($env);
}

Rackem\Middleware

This is a base class used as a starting point when creating new middleware. Abstract class intended for extending.

Rackem\Protection

A middleware that will help protect your application from common web exploits.

Protects against:

Rackem\Request

Easily get particular types of information from an http request.

Example:

<?php

public function call($env)
{
	$req = new \Rackem\Request($env);

	$req->base_url();
	$req->path_info();
	$req->content_type();
}

Rackem\Response

Used to easily formulate a response array. Will also attempt to normalize some headers like Content-Length.

Example:

<?php

// Application example
public function call($env)
{
	$res = new \Rackem\Response(array(), 200, array("Content-Type"=>"text/html"));
	$res[] = "<h1>Hello down there!</h1>";
	return $res->finish();
}

// Middleware example
public function call($env)
{
	$res = new \Rackem\Response($this->app->call($env));
	$res[] = "Adding some content to the response...";
	return $res->finish();
}