Getting started
Download the library, place it in your PHP include path and you're ready to go.
The best way to get started is to use the build script to generate a new project:
peej@xyzzy:/usr/share/php/tonic$ php tonic.php Tonic project tools. Usage: tonic.php [start|serve] /path/to/your/new/project peej@xyzzy:/usr/share/php/tonic$ php tonic.php start ~/www/testapp Creating new Tonic project at '/home/peej/www/testapp' Creating project directory...done Creating project subdirectories... /home/peej/www/testapp/lib...done /home/peej/www/testapp/resources...done /home/peej/www/testapp/scratch...done Creating dispatcher...done Creating .htaccess file...done Copying default Tonic resources... /home/peej/www/testapp/resources/^...done Finished. peej@xyzzy:/usr/share/php/tonic$
Now you can either point a Web server at your new project or if you're feeling brave, use the Tonic development server (a very light Web server written in PHP).
The library files
Tonic is made up of three main library files that model each part of the HTTP cycle:
- Request
-
The request class models the incoming HTTP request. It is responsible for collecting all the information from the request and turning it into a usable form.
The request object contains the following request information:
- HTTP method
- Request URL
- Array of acceptable response formats
- Array of acceptable response languages
- Request body information
- HTTP match headers
- HTTP authentication data
- Resource
-
The resource class models a resource, where in REST terminology, a resource is an abstract concept enbodying a useful object within our system. They are the heart and soul of any Web system, accessed by URLs they provide our application logic and contain our server data.
The resource class is what you extend to add functionality to your application, by overwriting the methods that are called once a resource is loaded by the request object, you can build up your app in a RESTful way.
- Response
-
The response object models the generated outgoing HTTP response. It is built by the loaded resource and contains:
- HTTP response code
- HTTP response headers
- Response body (aka the representation)
URLs
So we've got these three parts, how do we tie them together? Resources are nothing without being able to access them and without being able to turn them into a string to send to the client.
We access our resources by URLs and we turn them into strings via representations.
Persistance adapters
Resources need to be stored somewhere which is where the persistance adapters come in. They provide a common interface for Tonic to load and save resource data, whether the data is being loaded from the filesystem, a database, or another source. Data within the adapter is exposed via Tonic as resources.
Tonic has two persistance adapters out of the box, the filesystem adapter which is the default and loads resource data from files on the filesystem, and a MySQL adapter that loads data from the popular database server.
Representations
A representation is a resource (within an adapter, everything is a resource) that contains the output format we want to send to the browser. For example, this representation that you're looking at right now looks a little bit like this:
mimetype: text/html
class: SmartyResource
title: The Anatomy of Tonic
section: docs
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
<title>Tonic: {$resource->title}</title>
...
resources/anatomy.html
So now a HTTP request to /anatomy.html will grab this representation, load
the SmartyResource resource class and call it's get() method.
Representations are tied to a resource by setting the resources "representation" property to the URLs of one or more representation. A resource can have multiple representations, Tonics in built support for content negotiation will pick the most appropriate representation for the client.
The front controller, aka, the dispatcher
To get things going, by default Tonic uses the front controller pattern to direct all HTTP requests to a single PHP script, the dispatcher. This script creates the request object and persistance adapter, loads the relevant resource object and runs it generating a response object.
The Tonic start tool will build a fresh dispatcher.php script to get you started, but then you are on your own.
Model, view, controller (MVC)
MVC frameworks are very popular, they separate applications into three component parts; the data model logic, the output view logic/format, and the processing control (aka controllers).
Although Tonic isn't an MVC framework, it does separate these concerns but in a RESTful way. To model our data, we write a data persistance adapter to expose it as resources. Our representations provide the views of our resources, and our resource classes provide any processing logic that's required.
Back to documentation home