Common Patterns

General Paradigms

The first important paradigm of Pragwork is the idea called Model - View - Controller. It reflects the responsibility of particular parts of the application for appropriate groups of tasks. That approach in Pragwork is similar to the one in Ruby on Rails. The Model controls data processing, the View decides how the application looks like, and the logic combining these two together is up to the Controller. In Pragwork, models and controllers are classes and views are just template files.

It is worth mentioning that Pragwork applies also a unified manner of expressing single and multiple things. If passing multiple things requires an array, usually it is allowed to omit the array if there is only one single object in it. In most cases through the whole framework this rule is maintained, even in the ActiveRecord module (see below).

Coding Conventions

Pragwork coding conventions are both modern and succinct. The naming rules are similar to Ruby ones. Class names are written without underscores, starting with upper case, and having all elements of the name joined together. Also, class names begin with the capital letter. This is so called CamelCase. The CamelCase is also applied to namespaces. The directory and file names follow the same rules.

Local variables, parameters, fields, properties, methods, and functions are written with the snake_case - where elements are separated with the underscore sign. Private fields (static and instance ones) have a leading underscore additionally as well as internal functions (not methods). It helps to distinguish internal and private stuff, which is often not intended to be reached explicitly by framework users.

The braces policy follows the BSD / Allman scheme. Almost each curly brace is placed on a new line. Moreover, if there is a single, obvious statement in the code block, enclosed within curly braces, the braces may be omitted at all (of course, if such omitting is allowed by the language syntax).

The line length should not exceed 120 characters per line. It is strongly preserved in the strict PHP files and advised, but not required, in the template files, where PHP code is mixed with other code (e.g. HTML). See also a similar approach in Zend Framework Coding Conventions.

Static Definitions

Many things in models or controllers can be set up by static definitions. That is by defining static properties. However in the current PHP version (5.3) such definitions have some limitations. For example, you cannot put anonymous functions inside static variables.

The way of setting things through static definitions is common across the whole framework. Consider following definitions from the SiteMessage model (btw. it is a real code used at the Pragwork site):

class SiteMessage extends \ActiveRecord\TablelessModel
{
    # ...

    static $validates_presence_of = array('name', 'email', 'message');

    static $validates_size_of = array(
        array('message', 'maximum' => 1024),
        array('token', 'maximum' => 3),
        'name',
        'email',
        'www',
        'maximum' => 128,
    );

    # ...
}

We can distinguish something like two levels of specifying things: the outer one - more general and the inner one - more particular. The inner level is used to alter the general behavior defined in the outer level. In the $validates_size_of example, the outer level sets the maximum of all fields to 128. But two fields (message and token) have this property altered (the inner level). The altered property is grouped with the fields in the inner array. The outer array represents the general level.

As said before, we can leave the array if there is only one element in it. Therefore, if the $validates_presence_of had had only one field in the array, we would have left the array at all, e.g.:

static $validates_presence_of = 'name';

This is also an important change comparing to the original PHP ActiveRecord library. The second improvement visible here is the TablelessModel class. However, the details will be explained later.

The static definitions syntax is common through the whole framework. The same rules can be found in the controller static definitions, like e.g. $before_filter or $caches_action and so on.

url_for() Pattern

The url_for() function is probably the most important standalone function of Pragwork. Its syntax is used widely in many other functions and methods. Generally, methods and functions using URLs have two forms. One form has ends with the _to_url (or similar) suffix and accept the URL as a parameter (and possibly an array of options), whereas the basic form has the _url part trimmed and accepts the array of options only. Those options are used to get the URL through the url_for() function immediately. After that, the remaining array elements serves as options in the _to_url function type. Here are some examples of such function pairs:

The url_for() syntax is used also in many different methods, e.g. in the caching methods of the Controller like Controller::expire_page(), Controller::expire_action(), Controller::expire_fragment(), etc.

The url_for() uses the short notation for the controller and action reference, mentioned in the previous section. Such notation is also used in the Controller::render() method to select the template. In that case it denotes the path to the template:

$this->render(`Admin\MyPeople\index`);

Notice, that the notation looks the same all the time and it always use the backslash \ as the separator. This is because the namespaces uses the backlash in the PHP syntax, so the use of the backlash provides coherent API despite of various operating system using various path separators.

In the next chapter you get more into controllers and actions. Besides the url_for() the Controller class is the very important citizen of the Pragwork universe. You will see that almost everything is taking place inside a controller and how the controller is playing with Request and Response objects.