The basics

EpiCode simplifies the most basic function of a website: handling requests. It maps a URI to a static method and provides functions to generate HTML, JSON or HTTP redirects.

Request Handling

In order to abstract the URI from the file system we need to tell Apache to hand all requests to our main controller file. We do this with mod_rewrite in the virtual host definition or a .htaccess file. You’ll need to add the following to one or the other:

  RewriteEngine on
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule ^(.*)\?*$ index.php?__route__=$1 [L,QSA]

This tells apache to rewrite every URI which does not match a file or directory. This is important because we want Apache to serve images, CSS, JavaScript and any other file it finds in the document root. It’s every other request which should be handed off to our main controller (in this case index.php_). The script will have access to the original URI via @$_GET[’_route__’]@.

Our main controller file will include EpiCode.php and call the EpiCode::getRoute() method. A basic controller looks like this:

  include 'routes.php';
  include 'EpiCode.php';
  EpiCode::getRoute($_GET['__route__'], $_['routes']);

Directories

This is entirely customizable but it’s worth mentioning that the recommended directory structure for a site adhere to the following pattern:

|-- html
|   |-- index.php
|-- lib
|   |-- routes.php
|   |-- classes
|   |-- views

This should be self explanatory but html is the document root, html/index.php is the controller, lib/routes.php defines the routes, lib/classes contain all class files, and lib/views contain all templates.

Routes

To handle requests you first need to specify routes. Routes are an array of URI paths beginning after the / immediately following the domain. For example http://www.example.com/my/page would be represented in the routes table as array('my/page' => array('Class','Method')). Of course you would have numerous routes defined. This may look something like:

  $_['routes'] = array(
    ''        => array('Site', 'home'),
    'sign_in' => array('Site', 'sign_in'),
    'search'  => array('Search', 'get')
  );

Helpers

There are several helper functions used to generate a response. A primary goal was to cover the most common uses which include typical HTML markup, AJAX responses in JSON, and HTTP redirects.

HTML

The most common response is HTML markup. EpiCode leverages PHP’s strength as a templating language. The templating functions are EpiCode::display() and EpiCode::get(). These functions behave identically except that display writes the contents to stdout and get returns the contents as a string. They each take two parameters: a template file and an array of key value pairs. The array is passed through PHP’s extract function which imports the keys as variables to the symbol table.

 // template.php
  <h1>Hello <?php echo $name; ?>!</h1>

 // classes.php
  class Site{
    public static function hello(){
      EpiCode::display('template.php', array('name' => 'Jaisen Mathai'));
    }
  }

The hello method calls EpiCode::display and passes in a template name and an array. EpiCode::display imports the keys from the array into the symbol table and processes the template file. This is written to stdout and you should see <h1>Hello Jaisen Mathai!</h1>

JSON

Serving JSON content is as simple as calling either the EpiCode::json or EpiCode::jsonResponse methods. Both take any valid data-type and convert it to JSON. The primary difference is that EpiCode::json will return the JSON string while EpiCode::jsonResponse will write out JSON headers and the JSON string. JSON headers are useful for JavaScript libraries which automatically parse the JSON string into native data-types.

  class Site{
    public static function hello(){
      $array = range(0,100);
      EpiCode::jsonResponse($array);
    }
  }

Redirects

The recommended policy is that the user be redirected after each write operation. This ensures that the user does not inadvertently rerun write operations by refreshing the browser. For POSTs it has the added benefit of hiding the ugly browser dialog from the user which asks if they want to resubmit their form data.

 // classes.php
  class Site{
    public static function hello(){
      EpiCode::redirect('http://www.example.com');
    }
  }