Yiinitializr: The Library

You are viewing revision #1 of this wiki article.
This version may not be up to date with the latest version.
You may want to view the differences to the latest version.

next (#2) »

Introduction

For those who have created a project boilerplate with Yiinitializr site, you will find that is not just a project boilerplate what you just downloaded. Within the boilerplate comes a library named: Yiinitializr (not very original I know). The classes within this tiny library are simple, yet powerful, and will help you build your own project setup, the one that really fits your needs for your Yii application.

The Classes Explained

The Yiinitializr classes will help boost your application installation with ease and also to run Yii applications from its bootstrap files on a much cleaner way that the framework currently proposes. Let's have a look at the following example:
// if installed via composer (pretty neat right?)
require('./../../common/lib/vendor/autoload.php');

Yiinitializr\Helpers\Initializer::create('./../', 'frontend', array(
    // will override frontend configuration file
    __DIR__ .'/../../common/config/main.php', // merged with
    __DIR__ .'/../../common/config/env.php', // merged with
    __DIR__ .'/../../common/config/local.php' // merged with
))->run();

Yiinitializr\Cli namespace

This namespace brings utilities to interact with the terminal or 'cli'. A free beer goes to mr nramenta for them.

Yiinitializr\Cli\Console
The Console class helps you to display information to the console. You probably, think that it as easy as to 'echo' from any of your Command components that are runed by the Yiic command and is true, but this class comes with some magic:
Color
Console::output('this is %rcolored%n and %Bstyled%n');
Prompt
$db_host = Console::prompt('database host', ['default' => 'localhost']);
Selection
$opt = Console::select('Do you love Yii?',
    ['y' => 'yes', 'n' => 'no', 'a' => 'all']
);
Confirm
$sure = Console::confirm('are you sure?');
Work
<?php
Console::stdout('Working ... ');
Console::work(function($socket) { // $socket is optional, defaults to a spinner
    $n = 100;
    for ($i = 1; $i <= $n; $i++) {
        // do whatever it is you need to do
        socket_write($socket, "[$i/$n]\n");
        sleep(1); // sleep is good for you
    }
});
Console::stdout("%g[DONE]%n\n");
Yiinitializr\Cli\Daemon

The Daemon class provides helpers for starting and killing daemonized processes.

<?php
use Yiinitializr\Cli\Daemon;

if (Daemon::isRunning('/path/to/process.pid')) {
    echo "daemon is running.\n";
} else {
    echo "daemon is not running.\n";
}

Yiinitializr\Composer namespace

I should just call this namespace Tobias Schmunk as he was the master guru behind this class, the only thing I did was to read the e-book of Composer and studied every single piece of his fabulous Phundament application boilerplate. To modify the class to become of more general usage out of Phundament has no much credit.

Here, we find the Callback class, a super useful class that will allow you to execute commands prior, post Composer extensions installations or updates. It makes use of the scripts configuration feature and even though for the current templates found at Yiinitializr Site the only thing it does is to call Yiic migrate commands but I am sure that you are already thinking of its possibilities.

Yiinitializr\Helpers namespace

Yiinitializer\Helpers\ArrayX
This class includes cool functions to work with arrays. It contains one cloned from CMap, the mergeArray function, as we require this method in order to combine the different configuration files before the Yii application is even included. A clear example of it you find it on Yiinitializr/config/console, which is the file that where you set the configuration of your console application to run Composer callbacks. It has also
Yiinitializr\Helpers\Config
It reads the configuration file and provides an interface to access the settings. It also, when working with different environments, writes the "env.lock" file. By creating this file, it tells the Initializr helper class to not recreate the env.php configuration file of the environment selected. If anybody wishes to recreate them, in order to make use of other environment configuration file (ie. stage vs local), the coder just needs to delete the "env.lock" file from the Yiinitializr/config folder.
The configuration file
As with Yii, you need to go through a bit of configuration settings if you wish to handle your project structure initializing setup with Yiinitializr. But don't worry, is not going to be too hard, the following is an example configuration file:
\\ where am i?
$dirname = dirname(__FILE__);
\\ where is the application folder?
$app = $dirname . '/../../..';
\\ where is the root?
$root = $app . '/..';

return array(
    // yii configurations
    'yii' => array(
        // where is the path of the yii framework?
        // On this example we have installed yii with composer
        // and as it is used after composer installation, we
        // can safely point to the vendor folder.
        'path' => $app . '/lib/vendor/yiisoft/yii/framework'
    ),
    // yiinitializr specific settings
    'yiinitializr' => array(
        // config folders
        'config' => array(
            // we just need the console settings
            // On this example, and due that I used environments
            // i created a custom console.php app for
            // Yiinitializr\Composer\Callbak class
            'console' => $dirname . '/console.php'
        ),
        // application structure settings
        'app' => array(
            // where is the root?
            'root' => $root,
            // directories setup
            'directories' => array(
                // where are the different configuration files settings?
                'config' => array(
                    // 'key' is the configuration name (see above init example)
                    'main' => $app . '/config',
                    'console' => $app . '/config',
                    'test' => $app . '/config'
                ),
                // where are my runtime folders?
                'runtime' => array(
                    // heads up! only the folder location as "/config" will be
                    // appended
                    $app
                ),
                'assets' => array(
                    // where to write the "assets folders"?
                    $root . '/www'
                )
            ),
            'files' => array(
                // files to merge the main configuration file with
                // initializr will merge it automatically
                'config' => array(
                    'main' => array('env', 'local'),
                    'console' => array('env', 'local'),
                )
            )
        ),
    )
);
Yiinitializr\Helpers\Initializer

This class requires a little bit more attention and I hope you take a bit of time reading its code to truly understand what it does. Improving this class, can make our lives easier with Yii and I explain why:

<li>It tries to solve the problem with YII_DEBUG dynamically (no need to hardcode true|false on your index.php bootstrap file) - check the <a href="https://github.com/2amigos/yiinitializr/blob/master/Helpers/Initializer.php#L134" target="_blank">setOptions function</a>.</li>
<li>It creates all necessary read+write folders like runtime and assets (Yiinitializr works in conjunction with Composer but I am pretty sure some of you are already thinking on why is not <a href="http://www.yiiframework.com" target="_blank">Yii</a> creating those folders when they are not found? Initializer class may provide the solution:<strong> if it doesn't exist, build it don't fail on error!</strong>)</li>
<li>Automatically merges different configuration files that you may have for the different type of applications - check the <a href="https://github.com/2amigos/yiinitializr/blob/master/Helpers/Initializer.php#L62" target="_blank">config function</a>.</li>

Final Notes

We truly hope at 2amigOS! that you find this library as useful as it is for us. We do not expect that this procedure should be implemented at Yii's core but some of the features included in this small library are certainly something to consider on its future releases. Happy Yii coding!

References

<li><a href="http://yiinitializr.2amigos.us/">Yiinitializr</a></li>
<li><a href="https://github.com/2amigos/yiinitializr">Yiinitializr Components</a></li>
<li><a href="https://github.com/tonydspaniard/yiinitializr-basic">The Basic Template</a></li>
<li><a href="https://github.com/tonydspaniard/yiinitializr-intermediate">The Intermediate Template</a></li>
<li><a href="https://github.com/tonydspaniard/yiinitializr-advanced">The Advanced Template</a></li>

> 2amigOS!
web development has never been so fun
www.2amigos.us