aura/system

A full-stack framework system built from Aura library packages.

Aura System

, _(*1)

The Aura System provides a full-stack Aura framework built around Aura library packages., _(*2)

Getting Started

Installation

Install via Composer to a {$PROJECT_PATH} of your choosing:, _(*3)

composer create-project aura/system {$PROJECT_PATH}

This will create the system skeleton and install all of the necessary packages., _(*4)

Once you have installed the Aura system, start the built-in PHP server with an Aura.Framework command:, _(*5)

cd {$PROJECT_PATH}
php package/Aura.Framework/cli/server

You can then open a browser and go to http://0.0.0.0:8000 to see the "Hello World!" demo output., _(*6)

Press Ctrl-C to stop the built-in PHP server., _(*7)

Additionally, you can run a command-line test:, _(*8)

cd {$PROJECT_PATH}
php package/Aura.Framework_Demo/cli/hello

You should see "Hello World!" as the output., _(*9)

Run The Tests

For testing, you need to have PHPUnit 3.7 or later installed., _(*10)

To run the integration tests for the system as a whole, change to the tests directory and issue phpunit:, _(*11)

cd {$PROJECT_PATH}/tests
phpunit

To run the unit tests for a package, change to that package's tests directory and issue phpunit:, _(*12)

cd {$PROJECT_PATH}/package/Aura.Autoload/tests
phpunit

Web Server

To run Aura under Apache or another web server, add a virtual host to your web server configuration, then point its document root to {$PROJECT_PATH}/web., _(*13)

If mod_rewrite or an equivalent module is installed on the server, you will be able to browse without needing index.php in the URL., _(*14)

Remove the Demo Package

When you are satisifed that the installation is working, edit the composer.json file to remove the aura/framework-demo package requirement and then run composer update., _(*15)

System Organization

The system directory structure is pretty straightforward:, _(*16)

{$PROJECT_PATH}/
    config/                     # mode-specific config files
        _mode                   # the config mode to use
        _packages               # load these packages in order
        default.php             # default config
        dev.php                 # shared development server config
        local.php               # local development server config
        prod.php                # production config
        stage.php               # staging config
        test.php                # testing config
    include/                    # application include-path directory
    package/                    # aura-package libraries
    tests/                      # system tests
    tmp/                        # temporary files
    vendor/                     # composer vendors
    web/                        # web server document root
        .htaccess               # mod_rewrite rules
        cache/                  # public cached files
        favicon.ico             # favicon to reduce error_log lines
        index.php               # bootstrap script

Writing A Page Controller

Let's create a package and a page controller, and wire it up for browsing. We will do so in a project-specific way, leaving out the complexities of creating an independent package for distribution., _(*17)

Warning: If you have not removed the Framework_Demo package yet, please do so before continuing. Otherwise, your routes will not work correctly., _(*18)

Create The Controller

Change to the include/ directory and create a location for the example package and a space for our first web page ..., _(*19)

cd {$PROJECT_PATH}/include
mkdir -p Example/Package/Web/Home
cd Example/Package/Web/Home

... then create a file called HomePage.php. Add this code for a bare-bones index action:, _(*20)

view = 'index';
    }
}
?>

Create The View

Next, create a view for the index action in a file called views/index.php and add the following code to it, _(*21)

<?php echo "This is an example home page."; ?>

At this point your include/ directory should look like this:, _(*22)

include/
    Example
        Package/
            Web/
                Home/
                    HomePage.php
                    views/
                        index.php

N.b.: Technically you don't need a directory structure this deep. However, a structure like this makes it easy to add new pages as well as other support libraries without having to change the project organization later., _(*23)

Configure The System

Now we need to wire up the page controller to the autoloader and the routing system. Change to the system config directory:, _(*24)

$ cd {$PROJECT_PATH}/config

Edit the default.php file and add this code at the end of the file:, _(*25)

params['Aura\Router\Map']['attach'][''] = [
    // all routes with the '' path prefix (i.e., no prefix)
    'routes' => [
        // a route named 'home'
        'home' => [
            'path' => '/',
            'values' => [
                'controller' => 'home',
                'action'     => 'index',
            ],
        ],
    ]
];

// map the 'home' controller value to the controller class
$di->params['Aura\Framework\Web\Controller\Factory']['map']['home'] = 'Example\Package\Web\Home\HomePage';
?>

Try It Out

You should now be able to browse to the / URL to see "This is an example home page.", _(*26)