PRONTO WEB FRAMEWORK

Most of this manual will be long and boring, so for those of you who already know everything about everything, here are the barebones steps necessary to get Pronto up and running.

We'll assume you're using MySQL and Apache. Also, make sure AllowOverrides is enabled for your Pronto directory, so Apache will honor the .htaccess files within.

That's it! You should see a Pronto web page staring you in the face.

Like most web frameworks, Pronto is designed to ease the development of web applications by eliminating redundant code and promoting a logical separation of application logic, data/model logic, and presentation.

Pronto strives to maintain a loosely-coupled set of components that, when combined, form a a powerful web development stack. The reasoning behind our "loosely-coupled" mandate is that this encourages Pronto to assist the developer, not take over for her. If a developer prefers to forgo some of the facilities provided by Pronto, it should be relatively easy for her to do so, without having to step out of the framework entirely.

There are four core elements to Pronto.

Pronto also has plugin support for some layers.

Underneath the four high-level components, there are additional elements that support the framework.

The following diagram outlines the typical flow of execution when a web request is received:

The dispatcher is the traffic cop. It examines the request URI and decides which page controller it should pass control to, based on a series of regular expressions that define the URL->Controller mapping. The URL map is set in app/config/urls.php.

There is exactly one dispatch object at any point in the framework, and it is typically referred to as $web. The dispatcher receives control from the web execution profile and is charged with the task of determining which page controller it should pass control to.

The dispatcher also provides many lower-level facilities to controllers and plugins, such as:

Despite the numerous facilities the dispatcher provides, its core mission is to direct control to the proper page controller. This is configured using an array that maps URL patterns to their respective page controllers.

As the example suggests, each key in the $URLS associative array is a regular expression, and each value in the array is either the name of a specific controller class (string) or the name of a specific action within a specific controller class (array).

When routing a request, the dispatcher will choose the first array element that matches the current URL being requested. If the target is an entire controller (such as the /user/(.*) and /book(.*) examples above) then the portion of the regular expression surrounded by parentheses will be used to determine the action handler to be called within the page controller.

For example, if the browser issues a GET request to /user/list then the dispatcher will match the first rule in the $URLS array. It will then see that the list portion of the URL is the action handler requested, and will dispatch a request to pUser::GET_list().

If the action handler requested does not exist in the class, then the dispatcher will look for a "catch-all" handler for that request type. For example, if the browser issues a POST request for /user/list and the dispatcher cannot find a pUser::POST_list() method, then it will look for a pUser::POST() method instead.

The page controller is where most of your application logic will go. They are typically organized by the data entities they operate on, or a common theme of functionality. For example, one page controller may be responsible for allowing a user to register an account, login, change his/her password, etc. Another page controller may be used to manipulate blog posts, post comments, or both.

A page controller will receive control from the dispatcher and is responsible for a few things:

Page controllers are located in the app/pages directory. Each controller class name will be prefixed with a lowercase p, followed by the name of the controller itself. The file itself can technically be named anything you like, but conventionally it shares the same name as the controller. For example, the User page would have a class name of pUser and would be located in app/pages/user.php.

Within each page controller are a number of methods called action handlers. These methods are responsible for performing the logic required for the request(s) they are linked to.

To elucidate, let's begin with a simple example of a page controller.

Notice that action handler methods are prefixed with the type of HTTP request that was issued. This separation concept is adopted from the WebPY framework and its subsequent PHP clone, WebPHP.

While at first glance this may seem tedious, it actually proves to be a very effective way of logically separating your processes based on the type of request. Take a minute and think about the typical uses for a GET and POST, especially when handling form data. The GET request is responsible for GETting the record, populating the form, and showing it to the visitor. The POST request receives input back from the user and is in charge of validating and possibly updating the record.

There have been many PHP projects and frameworks that will use a GET/POST variable such as $op or $action to denote the current mode being requested (eg, if($op == 'edit') {} else if($op == 'update') {}).

By splitting our logic into separate methods, we avoid the cumbersome $action variable entirely. As a bonus, we can easily hook into other, lesser-used HTTP verbs if need be. For example, if you're writing an RSS-friendly blog, you may want to implement a HEAD request for your blog, as some readers will use this to retrieve the Last-Modified header or the E-Tag header. Or perhaps you'd like to write a RESTful API and need to leverage the PUT and DELETE verbs.

There are a few ways of collecting GET/POST data from within a controller. The first method is through the use of a couple convenience methods in the base Page class.

Page::param() is the quickest way to grab a specific parameter from the $_REQUEST array (which is a prioritized combination of GET and POST variables, POST taking precedence). If the variable requested is blank or does not exist, then the second parameter will be used as a default.

If you'd like to load the entire GET/POST data set into an associative array, then you can use Page::load_input().

Of course, you're free to access variables directly through the $_GET and $_POST superglobals, but Pronto will take care of any magic_quotes nonsense if you go through the Page class.

The Page::param() and Page::load_input() methods are useful when accessing standard GET/POST variables. But many applications today prefer to embed some variables inline. In other words, they appear in the URL itself, and not in the query string following.

For example, /user/edit?id=3 would become /user/edit/3.

To handle situations like these (and more), Pronto has introduced the concept of wildcard action handlers. These function like a typical action handler, except they can be called when only the beginning of the URL request matches the regexp in the $URLS routing table.

Once again, an example will elucidate.

Notice the two underscores trailing the method name. This denotes the action handler as a wildcard one. It means that, if an exact match cannot be found for the request (in this case, GET_hello()) then the dispatcher will look for a wildcard handler that matches. If it finds one, everything trailing after the matching portion will be treated as a variable, and passed into the action handler as such. So if the browser calls /user/hello/john, the dispatcher will call pUser::GET_hello__('john').

If a specific action cannot be found and a wildcard action cannot be found, then the dispatcher will default to the "catch-all" handler for that request type. In this case it would be GET(). If the catch-all does not exist either, then a 404 is issued.

It's very important to validate all data coming in from the web browser, both to ensure data integrity and maintain security.

Most validation is delegated to the data models, but there are times when it's necessary to validate some data that isn't destined for a data model. In these cases, you can validate the directory from within the page controller.

The class in charge of data validation is predictably called Validator. There are shortcut methods in the Page class, so the validation methods below can also be accessed through the shortcuts.

When using Validator::validate() and Validator::is_valid(), you can pass in any Perl-compatible regular expression. You can also use one of the regular expressions defined at the top of pronto/core/validator.php.

The typical flow of a Pronto web request usually only involves a single page controller, but there are some scenarios where it makes sense to call an action from another page controller. This is possible with the Page::render_element() method.

Most methods in a page controller start with an HTTP verb, such as GET_, POST_, or the lesser-used PUT_, DELETE_, etc. Page controller can also provide elements which are methods intended to be called from other page controllers. These methods must have a prefix of ELEM_.

Templates serve as the presentation layer of Pronto. When a page controller has finished its business, it will typically render a template via the Page::render() or Page::ajax_render() methods.

Templates are unique to Pronto, in that they aren't classes themselves, and they don't have access to other areas of Pronto, such as the dispatcher, controllers, models, or the database ($db). However, template files are managed by the Template class, which is ultimately in charge of setting/getting template variables, as well as the fetching/processing of templates themselves.

Pronto's template system is rather standard. You can use plain HTML and PHP as you wish. However, the only variables accessible are those set by the page controller via the Template::set() method.

Templates can also use any active template plugins, also called helpers. These will be covered later, though the example below makes use of the $html helper.

Templates are usually organized by page controller, since that's who typically renders them. The logical structure is to have subdirectories within the app/templates directory that match the names of the page controllers that will be rendering them. This is recommended but not necessary.

As shown in the example above, templates can reference their variables in the global scope, but they are limited only to variables that have been set using Template::set(), Page::tset(), or objects that serve as template plugins.

The Template class offers methods for setting, getting, and testing the existence of template variables.

There are three functions that can be used to render templates.

You'll probably use the Page::render() function the most, but Page::fetch() can be useful if you're combining templates, or rendering them somewhere other than the browser (eg, email). Both functions allow you pass in additional template variables that are not set globally via Template::set() or Page::tset().

Like the template methods, the real functionality is actually in the Template class itself. The methods in Page are merely convenience methods that call the real ones.

Layouts provide a way of establishing one or more outer structures to your web application. Most of the application's structure and styling will be relegated to the layout, leaving the core content in the templates themselves. While not considered a regular template, layouts still have access to template variables and plugins.

As you can see, all the "outer" stuff gets thrown in the layout. When a template is rendered within a layout, it will be substituted for the variable $CONTENT_FOR_LAYOUT. The other special layout variable is $HTML_HEAD, a placeholder variable for any additional tags that may need to be inserted into the <head> of your document.

Multiple layouts are supported. You can bind to a specific layout with the Page::render() method, or you can set a layout in a page controller's __init()__ method.

Models are responsible for any logic that surrounds the manipulation of a data entity. Its typical responsibilities are to faciliate create, retrieve, update and delete (CRUD) operations. If more advanced manipulation/processing functions are required for an entity, they will also be located here.

Models do not actually perform any data introspection or Object Relational Mapping (ORM) by default. They simply act as a place to store functions that relate directly to a data entity. You are still responsible for writing your own SQL for the most part. The creation and execution of safe SQL is reinforced by a well-designed database abstraction class that focuses on the DRY (Don't Repeat Yourself) principle.

While Pronto does not provide any full ORM capabilities, the base Model class does provide some convience functions for the more simple queries, such as PK-based lookups or lookups with a single column in the WHERE clause.

The base Model class provides an interface for the common operations associated with a simple data entity.

Depending on your data entity, some or all of these functions may not be relevant. If you are using the specialized controller Page_CRUD, then it will expect these functions to be complete.

For extremely simple entites, the implementation within the base Model class will probably suffice. For all others, you will want to override the functionality within your own model class.

Model class names are prefixed with a lowercase m.

The gatekeeper to all database access is the $db object. Like $web, it is available pretty much everywhere (either through $web or directly), though it is typically most used within data models.

The DB class provides some simple convenience methods for selects, inserts, and updates, while using the third-party SafeSQL library for parameter substitution and protection against SQL injection attacks.

An example is below, though you'll want to consult the API documentation for a full list of methods available.

As you can see, you can use placeholders within your SQL queries to denote variables that can be substituted by SafeSQL when it's time to execute the query. This is the recommended method of using variables in your queries, as SafeSQL can ensure that any malicious SQL (or other poorly-formed data) is properly escaped before being passed to the database engine.

There are different types of placeholders you can use, depending on what type of data you'll be passing in. If the variable type does not match the placeholder, SafeSQL will attempt to cast it.

In a well-organized application, almost all of your DB work will be in the models themselves. But just in case, $db is available to the dispatch and page controllers. It can be passed to plugins as well, though there are usually better ways of doing this.

Of all the operations listed in the beginning of this section, the one that probably stands out is the last one, Model::list_params(). Within the Pronto framework itself, this method is only used by one method, and that is Page_CRUD::GET_list(). The Page_CRUD class will be covered later, but Model::list_params() can be used by application code that you write as well, so we'll cover it here.

The purpose of Model::list_params() is to return the information required to construct a SQL query that will return a useful dataset to populate a record listing.

That's a bit of a mouthful, so perhaps a well-contrived example will serve us better.

Let's say you need to show a tabled list of records for a data entity. In a perfect world, you could just issue a "SELECT * FROM $table" and pass it to a template plugin that generates the table. But what if some columns are not mapped directly to a column in your table? What if you need to join against other tables, or restrict your data with a WHERE clause?

All of this is a cinch to do with SQL (that's what it was designed for, after all), but if a plugin or controller action is in charge of deciding which field to sort by or which data to restrict, then it can be easier to start by separating your query into its logical segments. That's what Model::list_params() does.

Model::list_params() returns an associative array, that contains six elements.

If you'd like to see how this data is used, take a look at the Page_CRUD::GET_list() method in pronto/core/page_crud.php.

Let's look at a simple example of a model and how it might be used from a page controller.

Now we can create a page controller that uses these methods. Our basic controller will provide a registration facility for new users.

As you can see, the separation of data logic and controller logic makes for some well-organized, readable code, and the GET/POST split in the controller makes it easy to tell which stage we're at in the signup process.

It's possible for a model to depend on other models. This occurs a lot when you have entities that link to each other. A model for managing users probably shouldn't directly modify another entity type, so instead it can ask the respective model to do the work on its behalf.

There is no special facility in place for storing and retrieving session data, so you can use the standard PHP superglobal $_SESSION just as you would in a basic PHP script.

Likewise, there is no policy on authentication either, though Pronto does provide a facility for access control lists (ACLs) and access checks.

What this means is that you're free to authenticate your users however you like. Once authenticated, you can use Pronto's access control features to keep track of whether a user is logged in or not, and what areas of the web application they are allowed to access.

In Pronto, there are two pieces of data that constitute your access policy framework: The access model and the access keys.

An access key, when assigned to a user, gives that user access to parts of the site that require it. The access model determines how the access key structure will be interpreted and used.

There are two primary access models in Pronto: roles and discrete. In both models, your access keys will be an associative array of keys and values.

If you're not sure which one to use, start with the roles model. Conceptually, it is simpler, analagous to assigning a "rank" to each user in the system.

Both the access model and the access_keys are configured in app/config/access.php.

To protect your controllers (or actions within) against unauthorized access, you can use the Web::check_access() method.

Also, once a user is logged in, Pronto's access layer will set the constant ACCESS_ID to the unique ID of that user. You can use this constant throughout the web application to check if a user is logged in (regardless of access keys assigned) and to link entities to the logged-in user.

You can also use Web::has_access() if you merely want to see if the user has valid access, but not act on the result. There is also a global shortcut function to Web::has_access() called a(), which can be used anywhere in Pronto, even where $web is not accessible.

So now that we know how to test for proper access, how do we tell Pronto that a user is authenticated?

The $web object holds a reference to the Access class, which is the brains of Pronto's access control facility. To set, get, or clear keys, we go through $web->access.

Let's add a couple methods to our mUser model class that can handle authentication.