ASSEGAI

UPDATED 03 August 2014

Introduction

Assegai is a full-featured MVC framework for PHP. It is free software under the MIT license.

The framework used to rely on the micro-framework Atlatl. This dependency was dropped in version 2.0.

Installation

Note: A full demonstration video is available illustrating points covered in the installation and the getting started sections. Please visit youtube to view the video.

To install Assegai you will first need to install composer. Then create a composer.json file for your project that requires etenil/assegai. An example composer.json file should look as following:

{
    "name": “YOUR_NAME/helloworld”,
    "require": {
        "etenil/assegai": "2.*"
    }
}

Now save and exit the composer.json file and from your project’s root folder (using command line) run the following command:

$ composer install

Once the installation of Assegai is completed, you will have a fully functional MVC framework installed inside your project's folder.

Getting started

There are many possible ways to setup and use the Assegai framework. Following sections demonstrates currently the most simple setup. The recommended setup documentation will follow shortly.

Bootstrapping

You will need to make a bootstrapper or use the default one for your project. The framework comes with an example bootstrapper that you can adapt.

To utilise the default bootstrapper run the following command from within your project’s root folder:

$ cp vendor/etenil/assegai/bootstrapper.example.php index.php

This will copy the already provided example bootstrapper file into the project’s root folder, renaming the file to index.php.

Basic Configuration

Even though Assegai has default configuration options, it will not work unless a configuration file is created, even if empty. You can simply use the file conf.example.php that comes with the framework. To do that from your project root folder use the following command:

$ cp vendor/etenil/assegai/conf.example.php conf.php

Now you have fully configured framework. In order to test the setup the flowing section will demonstrate how to create an application with Assegai.

Hello World app

In this chapter, we'll see how to write a very simple application for assegai, it will simply display the famous "Hello, World" message on an HTML page.

To create application firstly go into the conf.php file in your projects’s root folder and add the application name into the apps array. Feel free to delete or simply rename the currently existing sample app.

Your configuration file should look as following:

<?php
    $conf['apps_path'] = __DIR__ . '/apps';

    $conf['apps'] = [
        'helloworld',   
    ];

Now lets create the actual application. From the project’s root folder type in following command:

$ vendor/etenil/assegai/assegai app helloworld

This will create the file-system tree for your application. The default application tree is like so:

apps
 - helloworld
   |- conf.php
   |- controllers
   |- exceptions
   |- models
   |- views

Now create the file Hello.php within the controllers directory and put the following code:

<?php
    namespace helloworld\controllers;
    
    class Hello extends \assegai\Controller
    {
        function sayHello()
        {
            return "Hello, World!";
        }
    }

Be careful to put the first backslash on \assegai\Controller, otherwise you'll have issues.

We still need to indicate to the framework that this controller needs to be called when visiting the website. This is done by adding the following contents to the application's conf.php file. Note that this conf.php file is different to the general configuration file.

<?php
    $app['route'] = [
        '/' => 'helloworld\controllers\Hello::sayHello',
    ];

Test it

Now, start the PHP internal web server with (or configure the your preferred web server):

php -S localhost:8080 -t ./

And then, when visit your web server with a browser you should see the Hello, World message printed.

Namespacing Convention

Assegai encourages the use of multiple specialised apps that can share models in order to implement websites. The framework relies on the PSR-0 naming standard.

Classes need to be named like so:

app\type\Name

For instance:

myapp\models\DemoCode

You can also use sub-folders for models and controllers and extend the namespace accordingly:

myapp\models\demo\SomeModel

Using a model

Let us now try and modify the exercise by introducing a model. Models are a powerful and convenient way to organise your code, by delegating all data management to a dedicated class.

Create the file models/hello.php that will contain the following code:

namespace hello\models;

class Hello extends \assegai\Model
{
    function hello()
    {
        return 'Hello, Model';
    }
}

We will need to load the model from the controller now. Let's create a new function in controllers/hello.php:

namespace hello\controllers;

class Demo extends \assegai\Controller
{
    function hello()
    {
        return "Hello, World!";
    }

    function hello_model()
    {
        $hello = $this->model('Hello');
        return $hello->hello();
    }
}

Finally, we need to create a route to this new function in conf.php like so:

$app['route'] = [
    '/' => 'hello\controllers\Demo::hello',
    '/model' => 'Demo::hello_model',
    ];

Now try visiting your installation with the segment /model e.g. http://localhost/index.php/model. You should see the message "Hello, Model" displayed.

Note that we used an implicit namespace route for the '/model' path. This is handy and saves typing.

Views

Now let's try doing the same thing we did before but by using a view instead. We'll fetch the data from our existing model, then feed it into a view and display this.

We will create the view first. Create the file views/hello.phtml with the following code:

<DOCTYPE html>
<html>
    <head>
        <title>Assegai Tutorial</title>
    </head>
    <body>
        <p><?=$vars->message?></p>
    </body>
</html>

Notice the $vars->message variable.

Let's create another function within the controller's body like so:

function hello_view()
{
    $hello = $this->model('Hello');
    return $this->view('hello', array('message' => $hello->hello()));
}

Finally we will create a route to this new function in conf.php:

$app['route'] = [
    '/' => 'Demo::hello',
    '/model' => 'Demo::hello2',
    '/view' => 'Demo::hello_view',
];

Try visiting the url with the segment /view, for instance http://localhost/index.php/view and you should see the view with Hello, Model in place of the message variable.

View helpers

View helpers are convenient functions that return or output some HTML and are used to format and display data within the view. Consider the following:

<?php $h->form->input('text', 'foobar') ?>
=> <input type="text" name="foobar" id="foobar"/>

You might think of implementing this function like this:

function input($type, $name) {
    echo "<input type=\"$type\" name=\"$name\" id=\"$name\"/>";
}

Helpers are not loaded by default; the view must declare the necessary helpers that it uses like this:

<?php $load_helper('form'); ?>

At the moment, Assegai does not provide any helper. You can easily implement your own though.

Helpers are always accessible to all your applications and are declared as part of classes within the helpers_path folder (by default a folder called helpers in the project root).

A helper class must follow the usual convention and be named helpers\SomeName. It's a good idea to package related helpers together. Here's an example:

namespace helpers;

class Form {
    function input($type, $name) {
        echo "<input type=\"$type\" name=\"$name\" id=\"$name\"/>";
    }
}

Routing

Routes are defined on an per-application basis and conflicting routes are overwritten by applications loaded later.

Routes are regex-based. Thus it is easy to wildcard any part of a route and direct to the same handler. Capturing braces within a route are mapped as parameters to the handler. Thus one could use the following:

// Handler for route '/foo/([0-9]+)'
function foo($num)
{
    return $num;
}

Routes can also be defined for a specific HTTP method by prepending the desired method with columns to the route like so:

$app['route'] = [
    'GET:/bar' => 'app\controllers\Foo::bar_get',
    'POST:/bar' => 'app\controllers\Foo::bar_post',
    '/bar' => 'app\controllers\Foo::bar',
];

Note that routes also support implicit namespacing like so:

$app['route'] = [
    '/bar' => 'Foo::bar', // This will be assumed as 'app\controllers\Foo'.
];

In large routing tables, it is convenient to use route groups. They make the table clearer and reduce typing:

$app['route'] = [
    '@/test' => [
        '/foo' => 'Test::testFoo', // This is understood as '/test/foo'.
        '/bar' => 'Test::testBar',
    ],
    '@/real' => [
        '/foo' => 'Real::foo',
        '/bar' => 'Real::bar',
    ],
];

The route table is searched for method-specific routes first, then for other routes if none is found.

URL Prefix

If your website runs from a subfolder, then the routes end up having a constant prefix to them e.g. the site will run in the foo folder and result in a URL like http://host.com/foo/myroute. In this case, set the URL prefix in the configuratio