Control Flow

'.htaccess' and 'index.php'

The execution of a Pragwork application begins from the 'public/index.php' file. It is required to set URL rewriting for all HTTP requests excluding static assets to access the 'index.php'. URL rewriting is such a common feature nowadays, that you should not encounter any problems with getting it available.

The default Pragwork project comes with Apache '.htaccess' file containing the set of rules turning on URL rewriting. We do not cover '.htaccess' configuration here, but to explain things a bit, if the file is already present under the 'public' directory, then it is used. If it is not found, the request is passed to the 'index.php' file and the whole PHP application starts.

The very simple, basic rewriting rules (based on the RoR default '.htaccess' file) look like this:

DirectorySlash Off

RewriteEngine On

RewriteRule ^$ index.html [QSA]
RewriteRule ^([^.]+)$ $1.html [QSA]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ index.php [QSA,L]

php_flag magic_quotes_gpc off
php_flag register_globals off

The 'index.php' file just starts the application: it loads the Application module and executes its start() function. Sometimes such file is called a bootstrap.

Application Configuration

The application configuration takes place in the 'config/application.php' file. It uses the Configuration object.

The configuration properties are:

Property Name Value Types Default Value Description
environment string 'development' Sets the current environment. The environment named 'test' is required by integrated [`Test`](/en/doc-test) module. The environment having 'production' in its name is recognized as the final production stage. Notice, it does not have to equal to 'production' exactly. It might be 'en_production' as well. In that way you may have many production environments. This is helpful with some localization strategies. If the 'production' phrase is found, the error logging will be performed (instead of displaying the detailed info).
server_path string, null null The optional server path, i.e. the part of the URL appended to the domain name. E.g. a server directory.
http_port null, int null The optional number of the server port for the HTTP protocol. If null the port 80 is used.
ssl_port null, int null The optional number of the server port for the HTTPS protocol. If null - the port 443 is used.
images_path
stylesheets_path
javascripts_path
string '/images'
'/stylesheets'
'/javascripts'
The paths to the static assets. May be relative and points to the current server or absolute (with http://) and pointing any server on the net.
localization true, false, string false Turns on/off the localization or lock it explicitly on a chosen one.
session true, false, string true Turns on/off the session or explicitly sets it on, along with the given name.

The 'config/application.php' file sets also the default time zone. See time zones supported by PHP and adjust it to your needs.

URL Routing

The HTTP request is parsed and the proper controller action is executed. The parsing procedure depends on routing entries defined in the config\routes.php file. That file contains the $ROUTES global variable that contains all routes available in the application. Notice, Pragwork does not have automatic routing, and that means all routes should be specified explicitly.

Typically the entry is an array containing following data:

array(
    '/admin/my-people/:id',
    'controller' => 'Admin\MyPeople',
    'action' => 'update',
    'methods' => 'POST PUT'
)

The first element (0th index) is the URI path. It must start with a slash /. It can contains variables, called path parameters, started with a colon. It means that place in the requested path can contain any value. That value will be available in the controller later. In the example above there is one path parameter called id.

The controller and action elements refer to the proper controller and action fired when the request is parsed. The controller is written in the short notation. It means that only the necessary data a write here (its name and possible namespace). In the short notation (used everywhere in the Pragwork), the string Admin\MyPeople stands for \Controllers\Admin\MyPeopleController class.

The methods element specifies HTTP methods which trigger off the action. Pragwork supports 4 HTTP methods: GET, POST, PUT and DELETE. They should be written always with all uppercase letters, in one string, split with the space character. The order is not important.

There is also an optional element: ssl which can be set to boolean true or false. It turns on/off the SSL for certain route.

Routes are parsed in the order that they are defined. It allows to set the priority of qualifiers. Consider the following example:

array(
    '/admin/my-people/add',
    'controller' => 'Admin\MyPeople',
    'action' => 'add',
    'methods' => 'GET'
),
array(
    '/admin/my-people/:id',
    'controller' => 'Admin\MyPeople',
    'action' => 'show',
    'methods' => 'GET'
)

Both entries share the same HTTP method (GET) so in that order the add action will be fired for the URI /admin/my-people/add and the show will be fired for e.g. /admin/my-people/1. But in case the order is reversed the add action will not be triggered off at all.

The first entry in the $ROUTES array have special meaning. It is always the root entry. Its URI path is always set to / despite of the value entered in the 'config/routes.php' file. Therefore, the Prag tool does not even set the URI path (there is no 0th array element):

# Root
array(
    'controller' => 'Admin\MyPeople',
    'action' => 'index',
    'methods' => 'GET'
)

After the action method is called, the control flow is passed there. Before we discuss the controllers and actions, you should however get to know some common ideas and conventions in the next chapter.