PPI Framework¶

Download from composer¶

Download the latest version of 2.1, in the current directory

composer create-project -sdev --no-interaction ppi/skeleton-app /var/www/skeleton "^2.1"

Downloading from the website¶

http://www.ppi.io/downloads

Automatic Vagrant Installation¶

The recommended install procedure is to use the pre-built vagrant image that ships with the skeleton app in the ansible directory.

Installing vagrant and ansible¶

Before you can run vagrant you’ll need to install a few system dependencies.

Install vagrant https://docs.vagrantup.com/v2/installation/

Install ansible: http://docs.ansible.com/ansible/intro_installation.html#latest-releases-via-pip

Running vagrant¶

Running the vagrant image - it’s that easy!

vagrant up

Accessing the application¶

If you wish to use the skeletonapp as a hostname, run this command and browse to http://skeletonapp.ppi

sudo sh -c 'echo "192.168.33.99 skeletonapp.ppi" >> /etc/hosts'

Otherwise you can browse straight to the ip address of: http://192.168.33.99

Manual Web Server Configuration¶

Security is crucial to consider. As a result all your app code and configuration is kept hidden away outside of /public/ and is inaccessible via the browser. Therefore we need to create a virtual host in order to route all web requests to the /public/ folder and from there your public assets (css/js/images) are loaded normally. The .htaccess or web server’s rewrite rules kick in which route all non-asset files to /public/index.php.

Apache Configuration¶

We are now creating an Apache virtual host for the application to make http://skeletonapp.ppi serve index.php from the skeletonapp/public directory.

<VirtualHost *:80>
    ServerName    skeletonapp.ppi
    DocumentRoot  "/var/www/skeleton/public"
    SetEnv        PPI_ENV dev
    SetEnv        PPI_DEBUG true

    <Directory "/var/www/skeleton/public">
        AllowOverride All
        Allow from all
        DirectoryIndex index.php
        Options Indexes FollowSymLinks

        RewriteEngine On
        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteRule ^ index.php [L]

    </Directory>
</VirtualHost>

Nginx Virtual Host¶

server {
    listen 80;
    server_name skeletonapp.ppi;
    root /var/www/skeleton/public;
    index index.php;

    location / {
        try_files $uri /index.php$is_args$args;
    }

    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param HTTPS off;
    }
}

Restart your web server. The skeletonapp website can now be accessed using http://skeletonapp.ppi

Requirements¶

To easily check if your system passes all requirements, PPI provides two ways and we recommend you do both.

Why do we have both scripts? Because your CLI environment can have a separate php.ini file from your web environment so this will ensure you’re good to go from both sides.

Requirements checking on the command-line¶

$ ./app/check
                       _
        _____   _____ |_|
      / __  | / __ | / |
      | |__| || |__| || |
      |  ___/ |  ___/ | |
      | |     | |     |_|
      |/      |/

      Framework Version 2

    -- Requirements Check --

* Configuration file used by PHP: /etc/php/cli-php5.4/php.ini
* Mandatory requirements **

OK       PHP version must be at least 5.3.3 (5.4.13--pl0-gentoo installed)
OK       PHP version must not be 5.3.16 as PPI won't work properly with it
OK       Vendor libraries must be installed
OK       app/cache/ directory must be writable
OK       app/logs/ directory must be writable
OK       date.timezone setting must be set
OK       Configured default timezone "Europe/Lisbon" must be supported by your installation of PHP
OK       json_encode() must be available
OK       session_start() must be available
OK       ctype_alpha() must be available
OK       token_get_all() must be available
OK       simplexml_import_dom() must be available
OK       detect_unicode must be disabled in php.ini
OK       xdebug.show_exception_trace must be disabled in php.ini
OK       xdebug.scream must be disabled in php.ini
OK       PCRE extension must be available

Watch out for the green OK markers. If they all light up, congratulations, you’re good to go!

Below is the list of required and optional requirements.

Requirements checking in the browser¶

The check.php script is accessible in your browser at: http://skeletonapp.ppi/check.php

Must have requirements¶

• PHP needs to be a minimum version of PHP 5.3.3
• JSON needs to be enabled
• ctype needs to be enabled
• Your PHP.ini needs to have the date.timezone setting

Optional requirements¶

• You need to have the PHP-XML module installed
• You need to have at least version 2.6.21 of libxml
• PHP tokenizer needs to be enabled
• mbstring functions need to be enabled
• iconv needs to be enabled
• POSIX needs to be enabled (only on *nix)
• Intl needs to be installed with ICU 4+
• APC 3.0.17+ (or another opcode cache needs to be installed)
• PHP.ini recommended settings
  • short_open_tag = On
  • magic_quotes_gpc = Off
  • register_globals = Off
  • session.autostart = Off

The public folder¶

The structure above shows you the /public/ folder. Anything outside of /public/ i.e: all your business code will be secure from direct URL access. In your development environment you don’t need a virtualhost file, you can directly access your application like so: http://localhost/skeleton/public/. In your production environment this will be http://www.mysite.com/. All your publicly available asset files should be here, CSS, JS, Images.

The public index.php file¶

The /public/index.php is also known as your bootstrap file, or front controller and is presented below:

<?php

// All relative paths start from the main directory, not from /public/
chdir(dirname(__DIR__));

// Setup autoloading and include PPI
require_once 'app/init.php';

// Set the environment
$env     = getenv('PPI_ENV') ?: 'dev';
$debug   = getenv('PPI_DEBUG') !== '0'  && $env !== 'prod';

// Create our PPI App instance
$app = new PPI\App(array(
    'environment'   => $env,
    'debug'         => $debug
));

// Configure the application
$app->loadConfig($app->getEnvironment().'/app.php');

// Load the application, match the URL and send an HTTP response
$app->boot()->dispatch()->send();

Environments¶

PPI supports the notion of “environments” to make the application behave differently from when you are coding and testing the application in your laptop to when you deploy it to a production server. While in production debug messages won’t be logged, your application won’t stop due to non-fatal PHP errors and we’ll use caching wherever possible. In development you’ll get everything!

<VirtualHost *:80>
       ServerName    prod.skeletonapp.ppi.localhost
       DocumentRoot  "/var/www/skeleton/public"
       SetEnv        PPI_ENV prod
       SetEnv        PPI_DEBUG false
       ...

<VirtualHost *:80>
       ServerName    dev.skeletonapp.ppi.localhost
       DocumentRoot  "/var/www/skeleton/public"
       SetEnv        PPI_ENV dev
       SetEnv        PPI_DEBUG true
       ...

// file: public/index.php

// Set the environment
$env     = getenv('PPI_ENV') ?: 'dev';
$debug   = getenv('PPI_DEBUG') !== '0'  && $env !== 'prod';

// Create our PPI App instance
$app = new PPI\App(array(
    'environment'   => $env,
    'debug'         => $debug
));

$ cd /path/to/skeletonapp/app/config
$ cp -r prod staging
$ vim staging/app.yml

<?php
// ...

// Staging
$app = new PPI\App(array(
    'environment'   => 'staging',
    'debug'         => true
));

$app->loadConfig($app->getEnvironment().'/app.yml');

// ...

The app folder¶

This is where all your apps global items go such as app config, datasource config and modules config and global templates (views). You wont need to touch these out-of-the-box but it allows for greater flexibility in the future if you need it.

The app/config folder¶

Starting with version 2.1 all the application configuration lives inside app/config/<env>/ folders. Each <env> folder holds configuration for a specific environment: dev, prod.

The app.yml file¶

Looking at the example config file below, you can control things here such as the enabled templating engines, the datasource connection and the logger (monolog).

The datasource.yml file¶

The datasource.yml is where you setup your database connection information.

The modules.yml file¶

The example below shows that you can control which modules are active and a list of directories module_paths that PPI will scan for your modules. Pay close attention to the order in which your modules are loaded. If one of your modules relies on resources loaded by another module. Make sure the module loading the resources is loaded before the others that depend upon it.

The app/views folder¶

This folder is your applications global views folder. A global view is one that a multitude of other module views extend from. A good example of this is your website’s template file. The following is an example of /app/views/base.html.php:

<html>
    <body>
        <h1>My website</h1>
        <div class="content">
            <?php $view['slots']->output('_content'); ?>
        </div>
    </body>
</html>

You’ll notice later on in the Templating section to reference and extend a global template file, you will use the following syntax in your modules template.

<?php $view->extend('::base.html.php'); ?>

Now everything from your module template will be applied into your base.html.php files _content section demonstrated above.

The modules folder¶

This is where we get stuck into the real details, we’re going into the /modules/ folder. Click the next section to proceed.

Module Structure¶

Your module starts with Module.php. You can have configuration on your module. Your can have routes which result in controllers getting dispatched. Your controllers can render view templates.

├── Module.php
├── resources
│   ├── config
│   │   └── config.yml
│   ├── routes
│   │   ├── laravel.php
│   │   └── symfony.yml
│   └── views
│       └── index
│           └── index.html.php
├── src
│   ├── Controller
│   │   ├── Index.php
│   │   └── Shared.php

The Module.php class¶

Every PPI module looks for a Module.php class file, this is the starting point for your module.

<?php
namespace Application;
use PPI\Framework\Module\AbstractModule;

class Module extends AbstractModule
{
}

Autoloading¶

Registering your namespace can be done using the Zend Framework approach below. You can also skip this and register your module’s namespace to your composer.json file

<?php
namespace Application;
use PPI\Framework\Module\AbstractModule;

class Module extends AbstractModule
{
    public function getAutoloaderConfig()
    {
        return array(
            'Zend\Loader\StandardAutoloader' => array(
                'namespaces' => array(
                    __NAMESPACE__ => __DIR__ . '/src/',
                ),
            ),
        );
    }
}

Init¶

The above code shows you the Module class, and the all important init() method. Why is it important? If you remember from The Skeleton Application section previously, we have defined in our modules.config.php config file an activeModules option, when PPI is booting up the modules defined activeModules it looks for each module’s init() method and calls it.

The init() method is run for every page request, and should not perform anything heavy. It is considered bad practice to utilize these methods for setting up or configuring instances of application resources such as a database connection, application logger, or mailer.

<?php
namespace Application;
use PPI\Framework\Module\AbstractModule;

class Module extends AbstractModule
{
    public function init()
    {
    }
}

Configuration¶

Expanding on from the previous code example, we’re now adding a getConfig() method. This must return a raw PHP array. You may require/include a PHP file directly or use the loadConfig() helper that works for both PHP and YAML files. When using loadConfig() you don’t need to tell the full path, just the filename.

All the modules with getConfig() defined on them will be merged together to create ‘modules config’ and this is merged with your global app’s configuration file at /app/app.config.php. Now from any controller you can get access to this config by doing $this->getConfig(). More examples on this later in the Controllers section.

<?php
class Module extends AbstractModule
{
    /**
     * Returns configuration to merge with application configuration.
     *
     * @return array
     */
    public function getConfig()
    {
        return $this->loadConfig(__DIR__ . '/resources/config/config.yml');
    }
}

Conclusion¶

Lets move onto Services and Routing for our modules on the next pages.

Defining the Service in our Module¶

This is of course optional for your module but if you want to begin doing services then the method is getServiceConfig. This will be called on all modules upon boot() of PPI. Boot should be almost instantaneous and non-blocking, so be sure not to do anything expensive here such as make network connections, as that’ll slow down your boot process.

<?php
namespace MyModule;

use PPI\Framework\Module\AbstractModule;
use MyModule\Factory\UserSearchFactory;
use MyModule\Factory\UserCreateFactory;
use MyModule\Factory\UserImportService;

class Module extends AbstractModule
{

    public function getServiceConfig()
    {
        return ['factories' => [
            'user.search' => UserSearchFactory::class,
            'user.create' => UserCreateFactory::class,
            'user.import' => function ($sm) {
               return new UserImportService($sm->get('Doctrine\ORM\EntityManager'));
            }
        ]];
    }
}

Above you’ll see two types of ways to create a service. One is a Factory class and one is an inline factory closure. It’s recommended to use a Factory class but each to their own.

Creating a Service Factory¶

<?php
namespace MyModule\Factory;

use Zend\ServiceManager\ServiceLocatorInterface;
use Zend\ServiceManager\FactoryInterface;
use MyModule\Service\UserSearchService;

class UserSearchFactory implements FactoryInterface
{
    public function createService(ServiceLocatorInterface $sm)
    {
        $config = $sm->get('config');
        if(!isset($config['usersearch']['search_key']) {
            throw new \RuntimeException('Missing user search configuration');
        }

        return new UserSearchService(
            $config['usersearch']['search_key'],
            $sm->get('Doctrine\ORM\EntityManager')
        );
    }

}

Using services in our Controllers¶

To use the services in our Controllers, we just need to call $this->getService('service.name')

<?php
public function searchUsersAction(Request $request, $lat, $long)
{
    $userSearchService = $this->getService('user.search');
    $users = $userSearchService->getUsersFromLatLong($lat, $long);

    return $this->render('MyModule:search:searchUsers.twig', compact('users'));
}

Using Symfony Router¶

<?php
// Module.php
class Module extends AbstractModule
{
    // ....
    public function getRoutes()
    {
        return $this->loadSymfonyRoutes(__DIR__ . '/routes/symfonyroutes.yml');
    }
}

# resources/config/symfonyroutes.yml
BlogModule_Index:
    pattern:  /blog
    defaults: { _controller: "BlogModule:Blog:index"}

Using Aura Router¶

<?php
// Module.php
class Module extends AbstractModule
{
    // ....
    public function getRoutes()
    {
        return $this->loadAuraRoutes(__DIR__ . '/resources/config/auraroutes.php');
    }
}

<?php
// resources/config/auraroutes.php
$router
    ->add('BlogModule_Index', '/blog')
    ->addValues(array(
        'controller' => 'BlogModule\Controller\Index',
        'action' => 'indexAction'
    ));

// add a named route using symfony controller name syntax
$router->add('BlogModule_View', '/blog/view/{id}')
    ->addTokens(array(
        'id' => '\d+'
    ))
    ->addValues(array(
        'controller' => 'BlogModule:Index:view'
    ));

return $router;

Using FastRoute Router¶

<?php
// Module.php
class Module extends AbstractModule
{
    public function getRoutes()
    {
        return $this->loadFastRouteRoutes(__DIR__ . '/resources/routes/fastroutes.php');
    }
}

<?php
// resources/config/fastroutes.php
/**
 * @var \FastRoute\RouteCollector $r
 */
$r->addRoute('GET', '/blog', 'BlogModule\Controller\Index');

Defaults¶

This is the important part, The syntax is Module:Controller:action. So if you specify Application:Blog:show then this will execute the following class path: /modules/Application/Controller/Blog->showAction(). Notice how the method has a suffix of Action, this is so you can have lots of methods on your controller but only the ones ending in Action() will be executable from a route.

Example controller¶

Review the following route that we’ll be matching.

Blog_Show:
    pattern: /blog/{blogId}
    defaults: { _controller: "Application:Blog:show"}

So lets presume the route is /blog/show/{blogId}, and look at what your controller would look like. Here is an example blog controller, based on some of the routes provided above.

<?php
namespace Application\Controller;

use Application\Controller\Shared as BaseController;

class Blog extends BaseController
{

    public function showAction(Request $request, $blogId)
    {
        $bs = $this->getBlogStorage();

        if(!$bs->existsByID($blogId)) {
            $this->setFlash('error', 'Invalid Blog ID');
            return $this->redirectToRoute('Blog_Index');
        }

        // Get the blog post for this ID
        $blogPost = $bs->getByID($blogId);

        // Render our main blog page, passing in our $blogPost article to be rendered
        $this->render('Application:blog:show.html.php', compact('blogPost'));
    }

}

Generating urls using routes¶

Here we are still executing the same route, but making up some urls using route names

<?php
namespace Application\Controller;

use Application\Controller\Shared as BaseController;

class Blog extends BaseController
{
    public function showAction(Request $request, $blogId)
    {

        // pattern: /about
        $aboutUrl = $this->generateUrl('About_Page');

        // pattern: /blog/show/{blogId}
        $blogPostUrl = $this->generateUrl('Blog_Post', array('id' => $blogId);

    }
}

Redirecting to routes¶

An extremely handy way to send your users around your application is redirect them to a specific route.

<?php
namespace Application\Controller;

use Application\Controller\Shared as BaseController;

class Blog extends BaseController
{
    public function showAction(Request $request, $blogId)
    {

        // Send user to /login, if they are not logged in
        if(!$this->isLoggedIn()) {
            return $this->redirectToRoute('User_Login');
        }

        // go to /user/profile/{username}
        return $this->redirectToRoute('User_Profile', array('username' => 'ppi_user'));

    }
}

Working with POST values¶

<?php
namespace Application\Controller;

use Application\Controller\Shared as BaseController;

class Blog extends BaseController
{

    public function postAction()
    {

        $this->getPost()->set('myKey', 'myValue');

        var_dump($this->getPost()->get('myKey')); // string('myValue')

        var_dump($this->getPost()->has('myKey')); // bool(true)

        var_dump($this->getPost()->remove('myKey'));
        var_dump($this->getPost()->has('myKey')); // bool(false)

        // To get all the post values
        $postValues = $this->post();

    }
}

Working with QueryString parameters¶

<?php
namespace Application\Controller;

use Application\Controller\Shared as BaseController;

class Blog extends BaseController
{
    // The URL is /blog/?action=show&id=453221
    public function queryStringAction()
    {

        var_dump($this->getQueryString()->get('action')); // string('show')
        var_dump($this->getQueryString()->has('id')); // bool(true)

        // Get all the query string values
        $allValues = $this->queryString();

    }
}

Working with server variables¶

<?php
namespace Application\Controller;

use Application\Controller\Shared as BaseController;

class Blog extends BaseController
{
    public function serverAction()
    {

        $this->getServer()->set('myKey', 'myValue');

        var_dump($this->getServer()->get('myKey')); // string('myValue')

        var_dump($this->getServer()->has('myKey')); // bool(true)

        var_dump($this->getServer()->remove('myKey'));
        var_dump($this->getServer()->has('myKey')); // bool(false)

        // Get all server values
        $allServerValues =  $this->server();

    }
}

Working with cookies¶

<?php
namespace Application\Controller;

use Application\Controller\Shared as BaseController;

class Blog extends BaseController
{

    public function cookieAction()
    {

        $this->getCookie()->set('myKey', 'myValue');

        var_dump($this->getCookie()->get('myKey')); // string('myValue')

        var_dump($this->getCookie()->has('myKey')); // bool(true)

        var_dump($this->getCookie()->remove('myKey'));
        var_dump($this->getCookie()->has('myKey')); // bool(false)

        // Get all the cookies
        $cookies = $this->cookies();

    }
}

Working with session values¶

<?php
namespace Application\Controller;

use Application\Controller\Shared as BaseController;

class Blog extends BaseController
{
    public function sessionAction()
    {
        $this->getSession()->set('myKey', 'myValue');

        var_dump($this->getSession()->get('myKey')); // string('myValue')
        var_dump($this->getSession()->has('myKey')); // bool(true)
        var_dump($this->getSession()->remove('myKey'));
        var_dump($this->getSession()->has('myKey')); // bool(false)

        // Get all the session values
        $allSessionValues = $this->session();

    }
}

Working with the config¶

Using the getConfig() method we can obtain the config array. This config array is the result of ALL the configs returned from all the modules, merged with your application’s global config.

<?php
namespace Application\Controller;

use Application\Controller\Shared as BaseController;

class Blog extends BaseController
{
    public function configAction()
    {
        $config = $this->getConfig();

        switch($config['mailer']) {

            case 'swift':
                break;

            case 'sendgrid':
                break;

            case 'mailchimp':
                break;

        }
    }
}

Working with the is() method¶

The is() method is a very expressive way of coding and has a variety of options you can send to it. The method always returns a boolean as you are saying “is this the case?”

<?php
namespace Application\Controller;

use Application\Controller\Shared as BaseController;

class Blog extends BaseController
{
    public function isAction()
    {
        if($this->is('ajax')) {}
        if($this->is('post') {}
        if($this->is('patch') {}
        if($this->is('put') {}
        if($this->is('delete') {}

        // ssl, https, secure: are all the same thing
        if($this->is('ssl') {}
        if($this->is('https') {}
        if($this->is('secure') {}

    }
}

Getting the users IP or UserAgent¶

Getting the user’s IP address or user agent is very trivial.

<?php
namespace Application\Controller;

use Application\Controller\Shared as BaseController;

class Blog extends BaseController
{
    public function userAction()
    {
        $userIP = $this->getIP();
        $userAgent = $this->getUserAgent();
    }
}

Working with flash messages¶

A flash message is a notification that the user will see on the next page that is rendered. It’s basically a setting stored in the session so when the user hits the next designated page it will display the message, and then disappear from the session. Flash messages in PPI have different types. These types can be 'error', 'warning', 'success', this will determine the color or styling applied to it. For a success message you’ll see a positive green message and for an error you’ll see a negative red message.

Review the following action, it is used to delete a blog item and you’ll see a different flash message depending on the scenario.

<?php
namespace Application\Controller;

use Application\Controller\Shared as BaseController;

class Blog extends BaseController
{
    public function deleteAction()
    {
        $blogID = $this->getPost()->get('blogID');

        if(empty($blogID)) {
            $this->setFlash('error', 'Invalid BlogID Specified');
            return $this->redirectToRoute('Blog_Index');
        }

        $bs = $this->getBlogStorage();

        if(!$bs->existsByID($blogID)) {
            $this->setFlash('error', 'This blog ID does not exist');
            return $this->redirectToRoute('Blog_Index');
        }

        $bs->deleteByID($blogID);
        $this->setFlash('success', 'Your blog post has been deleted');
        return $this->redirectToRoute('Blog_Index');
    }
}

Getting the current environment¶

You may want to perform different scenarios based on the site’s environment. This is a configuration value defined in your global application config. The getEnv() method is how it’s obtained.

<?php
namespace Application\Controller;

use Application\Controller\Shared as BaseController;

class Blog extends BaseController
{
    public function envAction()
    {

        $env = $this->getEnv();
        switch($env) {
            case 'development':
                break;

            case 'staging':
                break;

            case 'production':
            default:
                break;

        }
    }
}

Base Templates¶

What are base templates?

Why do we need base templates? well you don’t want to have to repeat HTML over and over again and perform repetitive steps for every different type of page you have. There’s usually some commonalities between the templates and this commonality is your base template. The part that’s usually different is the content page of your webpage, such as a users profile or a blog post.

So lets see an example of what we call a base template, or somethings referred to as a master template. This is all the HTML structure of your webpage including headers and footers, and the part that’ll change will be everything inside the page-content section.

Where are they stored?

Base templates are stored in the ./app/views/ directory. You can have as many base templates as you like in there.

This file is ./app/views/base.html.php

Example base template:

<!DOCTYPE html>
<html>
    <head>
        <title>Welcome to Symfony!</title>
    </head>
    <body>
        <div id="header">...</div>
        <div id="page-content">
            <?php $view['slots']->output('_content'); ?>
        </div>
        <div id="footer">...</div>
    </body>
</html>

Lets recap a little, you see that slots helper outputting something called _content? Well this is actually injecting the resulting output of the CHILD template belonging to this base template. Yes that means we have child templates that extend parent/base templates. This is where things get interesting! Keep on reading.

Extending Base Templates¶

On our first line we extend the base template we want. You can extend literally any template you like by specifying its Module:folder:file.format.engine naming syntax. If you miss out the Module and folder sections, such as ::base.html.php then it’s going to take the global route of ./app/views/.

<?php $view->extend('::base.html.php'); ?>
<div class="user-registration-page">
    <h1>Register for our site</h1>
    <form>...</form>
</div>

The resulting output¶

If you remember that the extend call is really just populating a slots section named _content then the injected content into the parent template looks like this.

<!DOCTYPE html>
<html>
    <head>
        <title>Welcome to Symfony!</title>
    </head>
    <body>
        <div id="header">...</div>
        <div id="page-content">

            <div class="user-registration-page">
                <h1>Register for our site</h1>
                <form>...</form>
            </div>

        </div>
        <div id="footer">...</div>
    </body>
</html>

Example scenario¶

Consider the following scenario. We have the route Blog_Show which executes the action Application:Blog:show. We then load up a template named Application:blog:show.html.php which is designed to show the user their blog post.

Blog_Show:
    pattern: /blog/{id}
    defaults: { _controller: "Application:Blog:show"}

<?php
namespace Application\Controller;

use Application\Controller\Shared as BaseController;

class Blog extends BaseController {

    public function showAction() {

        $blogID = $this->getRouteParam('id');
        $bs     = $this->getBlogStorage();

        if(!$bs->existsByID($blogID)) {
            $this->setFlash('error', 'Invalid Blog ID');
            return $this->redirectToRoute('Blog_Index');
        }

        // Get the blog post for this ID
        $blogPost = $bs->getByID($blogID);

        // Render our blog post page, passing in our $blogPost article to be rendered
        $this->render('Application:blog:show.html.php', compact('blogPost'));
    }
}

<?php $view->extend('::base.html.php'); ?>

<div class="blog-post-page">
    <h1><?=$blogPost->getTitle();?></h1>
    <p class="created-by"><?=$blogPost->getCreatedBy();?></p>
    <p class="content"><?=$blogPost->getContent();?></p>
</div>

Using the slots helper¶

We have a bunch of template helpers available to you, the helpers are stored in the $view variable, such as $view['slots'] or $view['assets']. So what is the purpose of using slots? Well they’re really for segmenting the templates up into named sections and this allows the child templates to specify content that the parent is going to inject for them.

Review this example it shows a few examples of using the slots helper for various different reasons.

<!DOCTYPE html>
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <title><?php $view['slots']->output('title', 'PPI Skeleton Application') ?></title>
    </head>
    <body>
        <div id="page-content">
            <?php $view['slots']->output('_content') ?>
        </div>
    </body>
</html>

<?php $view->extend('::base.html.php'); ?>

<div class="blog-post-page">
    <h1><?=$blogPost->getTitle();?></h1>
    <p class="created-by"><?=$blogPost->getCreatedBy();?></p>
    <p class="content"><?=$blogPost->getContent();?></p>
</div>

<?php $view['slots']->start('title'); ?>
Welcome to the blog page
<?php $view['slots']->stop(); ?>

Using the assets helper¶

So why do we need an assets helper? Well one main purpose for it is to include asset files from your project’s ./public/ folder such as images, css files, javascript files. This is useful because we’re never hard-coding any baseurl’s anywhere so it will work on any environment you host it on.

Review this example it shows a few examples of using the slots helper for various different reasons such as including CSS and JS files.

<?php $view->extend('::base.html.php'); ?>

<div class="blog-post-page">

    <h1><?=$blogPost->getTitle();?></h1>

    <img src="<?=$view['assets']->getUrl('images/blog.png');?>" alt="The Blog Image">

    <p class="created-by"><?=$blogPost->getCreatedBy();?></p>
    <p class="content"><?=$blogPost->getContent();?></p>

    <?php $view['slots']->start('include_js'); ?>
    <script type="text/javascript" src="<?=$view['assets']->getUrl('js/blog.js');?>"></script>
    <?php $view['slots']->stop(); ?>

    <?php $view['slots']->start('include_css'); ?>
    <link href="<?=$view['assets']->getUrl('css/blog.css');?>" rel="stylesheet">
    <?php $view['slots']->stop(); ?>

</div>

What’s going on?

By asking for images/blog.png we’re basically asking for www.mysite.com/images/blog.png, pretty straight forward right? Our include_css and include_js slots blocks are custom HTML that’s loading up CSS/JS files just for this particular page load. This is great because you can split your application up onto smaller CSS/JS files and only load the required assets for your particular page, rather than having to bundle all your CSS into the one file.

Using the router helper¶

What is a router helper? The router help is a nice PHP class with routing related methods on it that you can use while you’re building PHP templates for your application.

What’s it useful for? The most common use for this is to perform a technique commonly known as reverse routing. Basically this is the process of taking a route key and turning that into a URL, rather than the standard process of having a URL and that translate into a route to become dispatched.

Why is reverse routing needed? Lets take the Blog_Show route we made earlier in the routing section. The syntax of that URI would be like: /blog/show/{title}, so rather than having numerous HTML links all manually referring to /blog/show/my-title we always refer to its route key instead, that way if we ever want to change the URI to something like /blog/post/{title} the templating layer of your application won’t care because that change has been centrally maintained in your module’s routes file.

Here are some examples of reverse routing using the routes helper

<a href="<?=$view['router']->generate('About_Page');?>">About Page</a>

<p>User List</p>
<ul>
<?php foreach($users as $user): ?>
    <li><a href="<?=$view['router']->generate('User_Profile', array('id' => $user->getID())); ?>"><?=$view->escape($user->getName());?></a></li>
<?php endforeach; ?>
</ul>

The output would be something like this

<a href="/about">About Page</a>

<p>User List</p>
<ul>
    <li><a href="/user/profile?id=23">PPI User</a></li>
    <li><a href="/user/profile?id=87675">Another PPI User</a></li>
</ul>

A Simple Example: A User¶

The easiest way to understand how the DataSource component works is to see it in action. In this section, you’ll configure your database, create a Product storage class, persist it to the database and fetch it back out.

Configuring the Database¶

Before you begin, you’ll need to configure your database connection information. By convention, this information is usually configured in the app/datasource.config.php file:

<?php

$connections = array();

$connections['main'] = array(
    'type'   => 'pdo_mysql', // This can be any pdo driver. i.e: pdo_sqlite
    'host'   => 'localhost',
    'dbname' => 'database',
    'user'   => 'database_user',
    'pass'   => 'database_password'
);

return $connections; // Very important you must return the connections variable from this script

Creating the Storage Class¶

After configuring the database connection information, we need to have a storage class, which is the one that’s going to be talking to the DataSource component when there’s a need to persist information.

<?php
namespace UserModule\Storage;

use UserModule\Storage\Base as BaseStorage;
use UserModule\Entity\User as UserEntity;

// Note here, we extend from
// a BaseStorage class
class User extends BaseStorage
{

    protected $_meta = array(
        'conn'    => 'main', // the connection.
        'table'   => 'user',
        'primary' => 'id',
        'fetchMode' => \PDO::FETCH_ASSOC
    );

    /**
     * Create a user record
     *
     * @param  array $userData
     * @return mixed
     */
    public function create(array $userData)
    {
        return $this->insert($userData);
    }

    /**
     * Get a user entity by its ID
     *
     * @param $userID
     * @return mixed
     * @throws \Exception
     */
    public function getByID($userID)
    {
        $row = $this->find($userID);
        if ($row === false) {
            throw new \Exception('Unable to obtain user row for id: ' . $userID);
        }

        return new UserEntity($row);
    }

    /**
     * Delete a user by their ID
     *
     * @param  integer $userID
     * @return mixed
     */
    public function deleteByID($userID)
    {
        return $this->delete(array($this->getPrimaryKey() => $userID));
    }

    /**
     * Count all the records
     *
     * @return mixed
     */
    public function countAll()
    {
        $row = $this->_conn->createQueryBuilder()
            ->select('count(id) as total')
            ->from($this->getTableName(), 'u')
            ->execute()
            ->fetch($this->getFetchMode());

        return $row['total'];
    }

    /**
     * Get entity objects from all users rows
     *
     * @return array
     */
    public function getAll()
    {
        $entities = array();
        $rows = $this->fetchAll();
        foreach ($rows as $row) {
            $entities[] = new UserEntity($row);
        }

        return $entities;
    }

}

First of all, we can see the class extends a BaseController class, which is a Shared Storage class, where we can place reusable code for all of our storage classes.

<?php

namespace UserModule\Storage;
use PPI\DataSource\ActiveQuery;
class Base extends ActiveQuery
{
    public function sharedFunction()
    {
        // code here...
    }
}

As you can see, the storage class is pretty explanatory by itself, you have a set of functions that perform specific tasks on the database; please note the use of the Doctrine DBAL Query Builder. Let’s see how it works:

public function getByUsername($username)
{

    $row = $this->createQueryBuilder()
        ->select('u.*')
        ->from($this->getTableName(), 'u')
        ->andWhere('u.username = :username')
        ->setParameter(':username', $username)
        ->execute()
        ->fetch($this->getFetchMode());

    if ($row === false) {
        throw new \Exception('Unable to find user record by username: ' . $username);
    }

    return new UserEntity($row);

}

Entities¶

The previous function returns an object called UserEntity, you may be wondering, what is that, right? well, an Entity is just an object representing a record in a table. Now, let’s see how does an Entity class looks like:

<?php

namespace UserModule\Entity;

class User
{

    protected $_id = null;
    protected $_username = null;
    protected $_firstname = null;
    protected $_lastname = null;
    protected $_email = null;

    public function __construct(array $data)
    {
        foreach ($data as $key => $value) {
            if (property_exists($this, '_' . $key)) {
                $this->{'_' . $key} = $value;
            }
        }

    }

    public function getID()
    {
        return $this->_id;
    }

    public function getFirstName()
    {
        return $this->_firstname;
    }

    public function getLastName()
    {
        return $this->_lastname;
    }

    public function getFullName()
    {
        return $this->getFirstName() . ' ' . $this->getLastName();
    }

    public function getEmail()
    {
        return $this->_email;
    }

    public function setUsername($username)
    {
        $this->_username = $username;
    }

    public function getUsername()
    {
        return $this->_username;
    }

}

<?php
namespace UserModule\Controller;

use UserModule\Controller\Shared as SharedController;

class Profile extends SharedController
{

    public function createAction()
    {

        // Assuming we're getting the info
        // from a submitted form through POST
        $post     = $this->post();

        // Instantiate the storage service
        $storage  = $this->getService('user.storage');

        // @todo You've got to add some codes here
        // To check for missing fields, or fields being empty.

        // Prepare user array for insertion
        $user     = array(
            'email'      => $post['userEmail'],
            'firstname'  => $post['userFirstName'],
            'lastname'   => $post['userLastName'],
            'username'   => $post['userName']
        );

        // Create the user
        $newUserID = $storage->create($user);

        // Successful registration. \o/
        $this->setFlash('success', 'User created');
        return $this->redirectToRoute('User_Thankyou_Page');

    }

}