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:

1. It tries to solve the problem with YII_DEBUG dynamically (no need to hardcode true|false on your index.php bootstrap file) – check the setOptions function.
2. 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 Yii creating those folders when they are not found? Initializer class may provide the solution: if it doesn’t exist, build it don’t fail on error!)
3. Automatically merges different configuration files that you may have for the different type of applications – check the config function.

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

• Yiinitializr
• Yiinitializr Components
• The Basic Template
• The Intermediate Template
• The Advanced Template

Tweet this!

Every project has different needs, and it’s those needs that set the requirements. Also, lets be realistic, if you were to develop a project where only the frontend UI with a small admin section was needed, Yiinitializr was overkill. In the end, people had to remove unneeded folders, the configuration was unnecessarily complex, a lot of people were not certain where to place the components and there were many other issues.

At 2amigOS! we were slamming our heads down on our keyboards trying to figure out what was the best way to provide a project boilerplate that could fit everyones needs. We soon realized and agreed that composer was the best way to go as a dependency manager (special shout-out thanks to Mr Tobias Schmunk, the guy behind Phundament for his great work and ideas), but we did not want to provide a fixed structure nor a set of extensions, again. Otherwise, we would just be putting a fresh coat of paint on the same problems. We wanted to give the power back to the developer to pick and choose based on their own needs. You know your project the most, so you should be able to set your own desired folder structure. You should be able to select which extensions you want to have pre-installed. And that, my amigos, is how Yiinitializr was born!

Yiinitializr is technically still in beta (?). Why? Because we believe that we need your feedback, yes you, from the Yii community, to make Yiinitializr right for all of us. You’re going to be using it, often (c’mon, you know you will…), so why not have a say in whether it’s enough or not… in what else it should or should not provide.

Okay, okay.. enough talk… now, let’s see how this baby works!

Yiinitializr is extremely easy to use. It is composed of only one page that will ask you three simple things:

1. What template type do you want to use? Basic, Intermediate or Advanced

2. Which extensions do you want pre-installed? Just search and select… really.. that’s all… no kidding… cool, huh?

3. Okay… maybe we misspoke… it’s really 3 steps; not questions. Download your finished project boilerplate!

4. What? Step 4? Maybe we can’t count, but you need to know what to do with the file you just downloaded, right? Well, here’s what you need to do:

Unzip, wherever you want your project to be, then (no, we are not going to tell you how to setup your database configuration. This is just a gentle reminder that you need to do that next…). Ahem… make your database configurations.
Now, run the following commands inside the unzipped project’s root:

// make sure you have the latest version of composer
php composer.phar self-update
// run your installation
php composer.phar install

Now, relax and love it! (or hate us, but keep it to yourself… really, all that negativity focused on us? We’re amigos! Come and share in the enchiladas… click on the docs below the templates to go to that github place and vent there…)

So, now you’re saying, “yeah, man… that is simple, but what are the template differences?”. We thought you’d never ask:

• Basic: The small in scope project. Is your project just a frontend, or maybe a frontend with an admin interface? Well, this is the basic one, and it contains only /app and /www. Yes, you can still choose the extensions you want.
• Intermediate: Your needs are maybe a little more complex than the basic offers, but you don’t want to go crazy. This one is closest to the structure you might be familiar with from YiiBoilerplate, but it’s much much lighter. Intermediate has a good solid structure. It contains: /backend, /common, /console and /frontend, and this structure will work for most of your robust applications. Need more?
• Advanced: Now you’re talking! The advanced structure adds on the /api directory for your web services. Need we say more? Got ideas of world domination? It starts here!

“But I want more details!” Yes, we agree, and this a great point to start the share of some knowledge. We know that once you download any of the template boilerplates you’ll start wondering what’s going on here. What the heck is this way of initializing applications? Check out the yiic.php or the index.php scripts within any of the application’s folder. See what we are doing. There is another surprise extension within, the Yiinitializr components. A set of classes that makes for a really easy way you can configure and install a project.

More documentation and discussion will be coming… we promise. We just wanted to let you play and react a little, first.

Tweet this!

I have been requested to provide a tutorial on how to use the file upload feature of the TbRedactor widget, and even though I am no longer supporting the library due that the work belongs to Clevertech, I feel that I owe that to the Yii developers. So, here is the  tutorial.

How to do it

As you know, if you try to use TbRedactor “out of the box” and if you click on the “insert image”, you will see a “popup window” as the following image:

Not bad… but too plain. What about the really cool Fileupload shown on redactorJS site? How do we set it up? The answer is easier that you can imagine. In fact, the only thing that we need to tell the plugin is the URL address that will handle file and image upload processes.

// with a TbActiveForm
echo $form->redactorRow(
    $model,
    'attribute_name',
    array(
       'class'=>'span4',
       'rows'=>5,
       'options'=>array(
          'fileUpload' => $this->createUrl('site/testFileUpload'),
          'imageUpload' => $this->createUrl('site/testImageUpload'),
       )
    )
);
// as a widget
$this->widget('bootstrap.widgets.TbRedactorJs',
    array(
      'model'=>$model,
      'attribute'=>'attribute_name',
      'editorOptions'=>array(
          'fileUpload' => $this->createUrl('site/testFileUpload'),
          'imageUpload' => $this->createUrl('site/testImageUpload'),
          'width'=>'100%',
          'height'=>'400px'
       )
    ));

As soon as we have that setup, the popup window will display differently:

File Upload

Images Upload

But wait a minute, what about if we wish to insert an image that has been previously uploaded? If we look at the redactor’s site we find really cool thumbnail images to choose from. Well, is a bit tricky but not too hard. The only thing that you have to do is to provide a URL where to download the “json” file that will get the uploaded files and their location.

// with a TbActiveForm
echo $form->redactorRow(
    $model,
    'attribute_name',
    array(
       'class'=>'span4',
       'rows'=>5,
       'options'=>array(
          'fileUpload' => $this->createUrl('site/testFileUpload'),
          'imageUpload' => $this->createUrl('site/testImageUpload'),
          'imageGetJson'=> $this->createUrl('site/testImageThumbs')
       )
    )
);
// as a widget
$this->widget('bootstrap.widgets.TbRedactorJs',
    array(
      'model'=>$model,
      'attribute'=>'attribute_name',
      'editorOptions'=>array(
          'fileUpload' => $this->createUrl('site/testFileUpload'),
          'imageUpload' => $this->createUrl('site/testImageUpload'),
          'imageGetJson'=> $this->createUrl('site/testImageThumbs')
          'width'=>'100%',
          'height'=>'400px'
       )
    ));

The following is an example action to return the thumbs and image information:

public function actionTestUpload()
{
   echo json_encode(array(
        array(
           'thumb' => '/images/image1_thumb.png',
           'image' => '/images/image1_big.png',
           'title' => 'Title1', // optional
           'folder' => 'myFolder' // optional
        ),
        array(
           'thumb' => '/images/image2_thumb.png',
           'image' => '/images/image2_big.png',
           'title' => 'Title2', // optional
           'folder' => 'myFolder' // optional
        )
   ));
}

Obviously, the above example has to contain the right resources to work but the result would endup with something similar to the following:

Images Choose Option

Further Reading

• Imperavi Redactor Doc Settings
• Imperavi Redactor Doc Files Upload
• Imperavi Redactor Doc Images Upload

Tweet this!

The following wiki is to explain how to make use of the TbFileUpload widget from YiiBooster. I have received a couple of requests and I thought was worth writing a wiki for it.

Usage

Preparation

First, we need to make sure we have a folder with write permissions, that will be the place where we are going to save our uploaded files.

I normally create a files folder and I allocate it within my www one, that is where I keep my css, js, images files. So, even though you can place it where ever you wish and for the sake of the example, I will use thefiles folder name.

I also assume that you have configured a path alias that references the files folder. On this example, the path alias is frontend.www.files.

Note

• This demo only works if the MyModel class already includes the function getImageUrl($img_type=null). If not, comment the 2 lines inside the data array, where ‘url’ and ‘thumbnail_url’ are defined, to make the demo work
• If the MyModel has a different name, it needs to be replaced 1-2 times inside the upload action
• The url where we are going to upload our files => upload action

Thanks Don Felipe

Setup your model

The way you handle validation on the server is up to you, the configuration I am going to provide now is just an example.

We are going to add one extra attribute to the model picture, which is going to hold any $_FILE type resource uploaded and validated when model is on upload scenario.

class MyModel extends CActiveRecord {
// ... more code here
/**
* This is the attribute holding the uploaded picture
* @var CUploadedFile
*/
public $picture;
// ... more code
/**
* @return array validation rules for model attributes.
*/
public function rules()
{
  return array(
    // ... more rules here
    array('picture', 'length', 'max' => 255, 'tooLong' => '{attribute} is too long (max {max} chars).', 'on' => 'upload'),
    array('picture', 'file', 'types' => 'jpg,jpeg,gif,png', 'maxSize' => 1024 * 1024 * 2, 'tooLarge' => 'Size should be less then 2MB !!!', 'on' => 'upload'),
    // ... more rules here
  );
}

Configuring the Widget

To render the widget on your view is quite straightforward, the are a couple of things very important to configure:

• the url where we are going to upload our files
• the file types we are going to accept and their maximum size

Now, lets render it:

<?php $this->widget('bootstrap.widgets.TbFileUpload', array(
    'url' => $this->createUrl("my/upload"),
    'model' => $model,
    'attribute' =>'picture', // see the attribute?
    'multiple' => true,
    'options' => array(
    'maxFileSize' => 2000000,
    'acceptFileTypes' => 'js:/(\.|\/)(gif|jpe?g|png)$/i',
))); ?>

Handling Upload

Everything is ready now but the controller. We have to configure the action that will handle the upload process. Here you go, the upload action of our controller -very, very basic – and not fully tested:

class myController extends CController {
   // ... more code here</code></code>/**
   * Handles resource upload
   * @throws CHttpException
   */
   public function actionUpload()
   {
      header('Vary: Accept');
      if (isset($_SERVER['HTTP_ACCEPT']) &&
      (strpos($_SERVER['HTTP_ACCEPT'], 'application/json') !== false))
      {
         header('Content-type: application/json');
      } else {
         header('Content-type: text/plain');
      }
      $data = array();
      $model = new MyModel('upload');
      $model-&gt;picture = CUploadedFile::getInstance($model, 'picture');
      if ($model->picture !== null && $model->validate(array('picture')))
      {
         $model->picture->saveAs(
            Yii::getPathOfAlias('frontend.www.files').'/'.$model->picture->name);
         $model>file_name = $model->picture->name;
         // save picture name
         if( $model->save())
         {
            // return data to the fileuploader
            $data[] = array(
            'name' => $model->picture->name,
            'type' => $model->picture->type,
            'size' => $model->picture->size,
            // we need to return the place where our image has been saved
            'url' => $model->getImageUrl(), // Should we add a helper method?
            // we need to provide a thumbnail url to display on the list
            // after upload. Again, the helper method now getting thumbnail.
            'thumbnail_url' => $model->getImageUrl(MyModel::IMG_THUMBNAIL),
            // we need to include the action that is going to delete the picture
            // if we want to after loading
            'delete_url' => $this->createUrl('my/delete',
            array('id' => $model->id, 'method' => 'uploader')),
               'delete_type' => 'POST');
         } else {
               $data[] = array('error' => 'Unable to save model after saving picture');
         }
      } else {
         if ($model->hasErrors('picture'))
         {
            $data[] = array('error', $model->getErrors('picture'));
         } else {
            throw new CHttpException(500, "Could not upload file ". CHtml::errorSummary($model));
         }
      }
      // JQuery File Upload expects JSON data
      echo json_encode($data);
   }
   // .... more code here
} // end of controller

Resources

• http://blueimp.github.com/jQuery-File-Upload/

Tweet this!

So, I am not longer working for that great company nor I am longer available for a freelance work on a personal basis, from now on, everything should be contracted throughout my very own company: 2amigOS! Consulting Corporation LLC. I know the name is quite long, but we wanted to have 2amigOS! so badly, that it was the only way to get it. Hope you don’t mind

I’ve got a great partner, and we have great people working with us. The company was made with one and only purpose: to be happy. And we will do whatever we want and what we like in order to pursue that goal, for us and for our customers of course! Check out our philosophy:

Taking our shared love for internet technology one-step further (and singing the whole way), an idea and work philosophy was born: 2amigOS! We believe in honesty, simplicity in design and intuitiveness in use for building new applications or helping you with yours. We provide code reviews, application development services, data analysis and database architectural design. We are also strong supporters of the open-source community, and with that in mind we contribute to them, as often as possible while building ourselves a heavy arsenal of tools and libraries to get any project launched… This is not about work, and it is not about the money. It’s about creating great things together, yourself included… it’s about having fun realizing our dreams. In the end, we are just a couple of nerds that love building incredible things… 

Who knew development could be so much fun? We did!

How that it sounds? Great right? Our specialties are Code Review, Web Development, Data Analysis & Design, Managed Hosting, and Training. More than enough… for now.

If you are a programmer and wish to be part of this, let me know, send me your github account or CV and you never know, we could be working together and having some fun with one of our customers’ projects.

And if you are a want to become one of our customers and/or believe that we can help you achieve the development of your project/idea? Please, let us know too, we will be very honest with you and tell you straight whether we are your team of people or not.

Cheers and thanks all for visiting my blog! I promise to keep it updated from now on (I have more time now )

Tweet this!

It all started with the amazing extension of Chris to allow Yii programmers to include the beauty of Bootstrap into our Yii applications.

I was in charge to create a Yii project startup for Clevertech and I thought that Yii-Bootstrap should be standard for it, and that was the reason it was included in YiiBoilerplate. It was an excellent decision.

Then, CEO Kuty Shalev, told me to provide solutions for the common challenges that Yii developers confront in our projects at Clevertech, we wanted to do things fast. That was the reason I started to create a widget library that, with the support and help of colleague programmers, was growing and growing everyday.

The goal was to maintain the beauty of Twitter Bootstrap, so the widgets were built on top of the development version of Chris’ Yii-Bootstrap extension. The results were highly acceptable, and we agree to share this with the community so to help and improve it for the benefit of everybody.

I truly hope it helps you build beautiful applications and to easy some of the challenges you face. Would be great to have your support to improve, as by helping the community, you will help Yii, and that will always be good for all us.

Overview

YiiBooster is a collection of widgets that will ease the task of developing Yii applications, as well as, giving your application a little boost. Basically, YiiBooster tackles the most common challenges that Yii developers face while trying to enhance their applications.

Widget List

YiiBooster has a huge collection of widgets, it includes all Yii-Bootstrap widgets plus many more:

• Buttons
• Button groups
• Button dropdowns
• Boxes
• Navigational tabs, pills, and lists
• Navbar
• Breadcrumbs
• Labels and badges
• Typographic components
• Thumbnails
• Alerts
• Progress bars
• Tables and Grids
• Forms
• JQuery UI Bootstrap Theme
• JSON Grid
• Extended Grid
• Extended Summaries
• Grid/Chart Switcher
• Bootstrap Editable Widgets
• Image Column
• Inline Editing Columns
• Calculated Sums
• Picker Columns
• Modals
• Tabs
• Tooltips
• Popovers
• Collapse
• Carousel
• Typeahead
• and many more…

For more information on how to get started with the library plus tons of examples per widget, please visitYiiBooster Site.

Important

Even though the library was built on top of Yii-Bootstrap and we have kept the configuration of YiiBooster and the naming conventions in honor of Chris, it is not compatible with it. We have made lots of changes plus many enhancements.

This is also true for the JQuery plugins within. We had to modify them to work with the widgets and provide the expected functionality.

Resources and Download

• YiiBooster Site
• YiiBooster Github repository
• YiiBooster Zipball
• YiiBoilerplate Github repository
• YiiBoilerplate Zipball
• Yii-Bootstrap
• Yii-Editable

well-built beautifully designed web applications
www.clevertech.biz

Tweet this!

We at Clevertech use this folder structure setup for our own projects when developing BackboneJS applications.

Overview

YiiBackboneBoilerplate, aims to provide Yii Backbone developers with an application folder to ease the startup of their projects. It uses the flexibility of our YiiBoilerplate with a twist for BackboneJS applications.

What is BackboneJS?

Backbone.js gives structure to web applications by providing models with key-value binding and custom events, collections with a rich API of enumerable functions, views with declarative event handling, and connects it all to your existing API over a RESTful JSON interface.

You may be thinking that Yii is too powerful to be used just as a RESTful service. That for this purpose it could be done with NodeJS or any of the other libraries available, but it is the power of Yii and for the sake of application scalability that we decided to use it.

BackboneJS + Yii

We love to work at Clevertech with Yii, in fact, it is one of the biggest assets of our company nowadays. Nevertheless, we are very aware of the new trends, and we had the opportunity to work with BackboneJS. So we decided that it could be good to provide a project startup for our developers, and allow us to get the best out of both worlds.

Backbone Overall Folder Structure

This document will be focused mainly in the folder structure that we set for the Backbone application. Please, read YiiBoilerplate’s README for a deeper explanation of the main Yii folder structure setup.

Below the directory structure we are using:

/
backend/
    ...
common/
    ...
console/
    ...
frontend/
    ...
    www/
        app/
            css/
            img/
            js/
                boilerplate/
                collections/
                libs/
                models/
                views/
                app.js
                controller.js
                main.js
                router.js
                vent.js
            templates/
tests/
    ...

Backbone Application Directories

In the js directory, we have:

• boilerplate: we have created a set of elements for you to create a model, collection, module and/or view. Please, note that the basic application skeleton that we have setup for you is based onBackbone.Marionette, and the views are different from normal Backbone views.
• collections: this is were we place the Backbone collections for our application.
• libs: holds the main libraries. We included the ones we thought would be the most useful.
• models: this is were we place the Backbone models for our application.
• views: and this is where we place the backbone views.

A special note regarding the templates directory. This folder is normally within the js folder, but we thought that it would be better to separate UI design from the business logic of the javascript files.

The runpostdeploy script

This section is actually extracted from YiiBoilerplate, but it is worth repeating the procedure.

The project has a very handy script that automatically creates the required and folders that are not shared for a Yii application, the runtime and assets folders, extracts the configuration settings specified for a specific environment then copies them to the ****-env.php*** files, and then runs migrations when not on private environments –we believe that migrations should be always run manually by developers on their machines.

To use this, from the application’s root folder, simply run:

./runpostdeploy environmentType migrations

• environmentType (required): can be “any” of the ones you configure on the environments folders (i.e../runpostdeploy private to use ****-private.php*** configurations)
• migrations (optional): could be “migrate“” or “no-migrate“.
  • migrate: will run migrations
  • no-migrate: will not run migrations (on private we won’t run them anyway)

Final Notes

We would like to inform that this is just a startup boilerplate for your own projects. It is not intended by any means to be used ‘AS IS’, but rather as a base to scale to more complicated structures.

Neverteless, we have included a couple of goodies that we hope to improve with the help of the community.

Resources and Download

• YiiBackboneBoilerplate Github repository
• YiiBackboneBoilerplate Zipball

====

well-built beautifully designed web applications
www.clevertech.biz

Tweet this!

I had to develop a module for a client at Clevertech that was quite interesting and not any developed for Yii yet. The module was to take care of the bulk mail services of the client and it supposed to work with nearly new Amazon Simple Email Service, which make the task even more interesting. The end result was YiiSES and to tell you the truth I was very happy with it.

Nevertheless, an image is worth thousand words, check the following thumbnails:

Features List

• Campaign Management
• Campaign Stats
  • How many opened / failed / successful
• Amazon SES Usage Stats
• Subscriber Management
• Google track vars
• And much more

I think is much better if you check it out by yourself. The whole project is Open Source and is freely available under Creative Commons Attribution-ShareAlike 3.0 Unported License, you can get is source code at Clevertech’s github profile: https://github.com/clevertech/YiiSES, we would love to hear your feedback, specially me.

YiiSES Overview

YiiSES is a ‘nearly’ ready to use module that provides our Yii applications with a powerful mail marketing tool.

The system makes use of Amazon Simple Email Service (Amazon SES), chosen for its highly reduced price, scalability and features. A developer can easily register and use its service at no charge. The only issue is that the developer will only be able to send to verified email addresses only.

This module has been ported to Open Source from one of the projects at Clevertech and we are very happy with its results so far.

Install

Even though there was some good effort to make it easy to install, its configuration is a bit tricky. We hope this will change with a bit of help from the community.

Within the code you will find two types of configurations, one to be used with YiiBoilerplate project structure (default), and the other when we install the module on a Yii’s default application structure.

The following instructions are to install the module on a Yii’s default application structure.

Configuration

• Create your web application ./yiic webapp <folder>
• Create your modules folder under protected and unpack the module there
• Place commands\CampaignCommand.php on your commands directory and ses\migrations.. on the migrations directory.
• Configure your config\main.php and config\console.php configuration files (make sure your db is setup correctly -migrations will only work on mySQL db):

// console.php
    …
    // urlManager must be the same configuration as on main.php
    'urlManager' => array(
        // remember to have your .htaccess setup correctly
        'urlFormat' => 'path',
        'showScriptName' => false,
        'urlSuffix' => '/',
        'rules'=>array(
            '<controller:\w+>/<id:\d+>'=>'<controller>/view',
            '<controller:\w+>/<action:\w+>/<id:\d+>'=>'<controller>/<action>',
            '<controller:\w+>/<action:\w+>'=>'<controller>/<action>',
        ),
    ),
    // request is required to create appropriate urls within the emails
    // when processed with the CampaignCommand.php
    'request' => array(
    )
    …
    // main.php
    …
    'modules' => array(
        'ses'=>array(
            'password'=>'clevertech',
        ),
    ),
    …
    // urlManager must be the same configuration as on main.php
    'urlManager' => array(
        // remember to have your .htaccess setup correctly
        'urlFormat' => 'path',
        'showScriptName' => false,
        'urlSuffix' => '/',
        'rules'=>array(
            '<controller:\w+>/<id:\d+>'=>'<controller>/view',
            '<controller:\w+>/<action:\w+>/<id:\d+>'=>'<controller>/<action>',
            '<controller:\w+>/<action:\w+>'=>'<controller>/<action>',
        ),
    ),
    …
    'params'=> array(
        'ses.aws.key'=>'',
    …

• Setup required parameters on your configuration files (must be shared among console.php and main.php):
  • ses.aws.key: Your Amazon SES API Key
  • ses.aws.secret: Your Amazon SES Secret
  • ses.aws.verifiedEmail: You are required to verify at least one email address on Amazon SES console in order to send emails
  • ses.aws.test.email: Email where to send test emails. If your account is not in production, then this email should be also verified on Amazon SES console.
  • ses.emailonacid.key: If you wish to preview and test your emails on EmailOnAcid service, you have to configure your API key here.
  • ses.emailonacid.pwd: Your password to access EmailOnAcid service for testing and previewing your emails.
  • ses.files.path: Set this parameter in order to make use of the image upload capabilities ofRedactorJS, our chosen WYSIWYG editor for the module.
  • ses.files.url: Required to display the thumbnail gallery of RedactorJS.
  • ses.panel.login.url: The Route to the control panel. This parameter is required at the unsubscribe form. If somebody tries to remove an email from a registered user, then it will be presented with the link created from this route, to inform that he should log into its panel in order to unsubscribe.
  • ses.from.name: Your application name. Will be included in the Emails From Name (ie.”My Application ” )
• Make sure your paths are correctly set:
  • CampaignCommand.php::init() - line 74
  • CampaignCommand.php::sendEmail() - line 376
  • models\Email.php::formatHTMLMessage() - line 136
  • models\Template.php::getView - line 65
• Run migrations ./yiic migrate from your command line prompt.

The User table and Model

One important part of the configuration is how you deal with the subscribers. The module works by default with the assumptions that your application has a User model with id, email, and username, subscribedattributes.

The module comes with a single field for campaign that configures whether to send to subscribers or not but you can easily change that behavior to match different fields or subscription option from your registered members -but this is something that I won’t explain here .

Requirements

The following requirements are all included already within the module:
- EPHPThumb - SES Component
- YiiBootstrap
- HighCharts
- RedactorJS

Contribute

• YiiSES Github repository

Tweet this!

I have the great opportunity to work with Clevertech, and I was in charge of creating a boilerplate that the company could use in order to have a Yii project structure in a matter of seconds. You can think that we could use Yii’s default webapp command but there some project requirements just don’t fit.

We use this folder structure setup on Clevertech for our own projects, we believe that can suit most of project requirements from Simple to Enterprise.

Overview

YiiBoilerplate, aims to provide Yii developers an application folder structure with sufficient flexibility to satisfy from simple to enterprise application’s development needs.

It may look a little bit too complex at first sight but, at Clevertech, we understand that needs may vary along the development life cycle of a product in order to fulfill customer’s requirements and that commonly forces developers to modify the initial folder structure, thus making very hard for a new developer to jump in and ‘understand’ where is all located.

In order to avoid such time consuming tasks, easy the life of our beloved developers and increase productivity, we make use of this folder structure template for our projects.

Overall Structure

Below the directory structure we are using:

/
backend/
    components/
    config/
        environments/
            main-private.php *
            main-prod.php
            params-private.php *
            params-prod.php
    main-env.php *
    main-local.php *
    main.php
    params-env.php *
    params-local.php *
    params.php
    test.php
controllers/
    SiteController.php
    ...
extensions/
        behaviors/
        validators/
    lib/
    models/
        FormModel.php
        ...
    modules/
    runtime/ *
    views/
        layouts/
        site/
    widgets/
    www/
        assets/ *
        css/
        images/
        js/
        themes/
        index.php
        .htaccess
common/
    components/
    config/
        environments/
            params-private.php *
            params-prod.php
        params-env.php *
        params-local.php *
        params.php
    data/
    extensions/
        behaviors/
        validators/
    lib/
        Behat/
        Pear/
        Yii/
        Zend/
    messages/
    models/
    widgets/
console/
    commands/
    components/
    config/
        environments/
    lib/
    migrations/
    models/
    runtime/ *
    yiic.php
frontend/
    components/
    config/
        environments/
            main-private.php *
            main-prod.php
            params-private.php *
            params-prod.php
        main-env.php *
        main-local.php
        main.php
        params-env.php *
        params-local.php *
        params.php
        test.php
    controllers/
    extensions/
        behaviors/
        validators/
    lib/
    models/
    modules/
    runtime/ *
    views/
        layouts/
        site/
    www/
        assets/ *
        css/
        files/
        images/
            js/
            less/
        index.php
        robots.txt
        .htaccess
tests/
    bootstrap/
        FeatureContext.php
        YiiContext.php
    features/
        Startup.feature
    behat.yml
INSTALL.md
README.md
runbehat
runpostdeploy
yiic
yiic.bat

When working in a team development environment, using any of the VCS (Version Control System) available (i.e. Git, SVN), the files and folders marked with an asterisk should not be included in the revision system.

Top Level Directories

At the top-most level, we have:

• backend: the backend application which will be mainly used by site administrators to manage the whole system (avoiding admin modules at frontend application to avoid confusion)
• console: the console application that is compound of the console commands required for the system.
• frontend: the frontend application that is the main interface for end users. On a website development, this would be what the site users would see.
• common: the directory whose content is shared among all the above applications.
• test: the folder where we include all of our BDD system tests.

The whole application is divided into three applications: backend, fronted and console. Following the directory structure of the yii project site, with some twist on its configuration. The common folder is to store all files (extensions, components, behaviors, models, etc… ) that are shared among the mentioned applications.

When developing a large project with a long development cycle, we constantly need to adjust the database structure. For this reason, we also use the DB migration feature to keep track of database changes. We store all DB migrations under the migrations directory in console.

Application Directories

The directory structure of each application is very similar. For example backend and frontend both share the same directory structure with a slight variation at the www folder of the frontend and the inclusion of bootstrap theme and extensions for thebackend, to easy the task to create Administrative panels.

The shared folder structure is this one:

• components: contains components (i.e. helpers, application components) that are only used by this application
• config: contains application specific configuration files.
• controllers: contains controller classes
• extensions: Yii extensions that are only used by this application
• lib: third-party libraries that are only used by this application
• models: contains model classes that are specific for this application
• modules: contains modules that are only used by this application
• views: stores controller actions view scripts
• widgets: stores Yii widgets only used by this application.
• www: the web root for this application.

We have created extensions and widgets folders, that could had been obviously included in the components folder, in order to clearly differentiate the types of components that could exist into a Yii application and easy the task to find them. So, for example, developers won’t search for a widget that renders a jQuery UI plugin within a folder that has application wide components, or helpers, or extensions, or…

The directory structure for console application differs from the others as it doesn’t require controllers, views, widgets, and www. It has a commands directory to store all console command class files.

The Common Directory

The common directory contains the files that are shared among applications. For example, every application may need to access the database using ActiveRecord. Therefore, we can store the AR model classes under the common directory. Similarly, if some helper or widget classes are used in more than one application, we should also put them under common to avoid duplication of code.

To facilitate the maintenance of code, we organize the common directory in a structure similar to that of an application. For example, we have components, models, lib, etc.

- source: Yii Framework Site

Application Configurations

Applications of the same system usually share some common configurations, such as DB connection configuration, application parameters, etc. In order to eliminate duplication of code, we should extract these common configurations and store them in a central place. In our setting, we put them under the config directory in common.

How to configure the application

The configuration for this boilerplate is not that complicated as it seems at first sight. As mentioned before, if our system has bothbackend and frontend applications and they both share the same DB configuration. We just need to configure one of the files on theconfig sub-directory under the common folder.

The files within the config folder of each application and common folder requires a bit of explanation. When working in a team environment, different developers may have different development environments. These environments are also often different from the production environment. This is why the configuration folders on each application contains a list of files that try to avoid interference among the different environments.

As you can see, the config folders include a set of files:

• environments/params-private.php: This is to have the application parameters required for the developer on its development environment.
• environments/params-prod.php: This is to have the application parameters required for the application on production
• environments/main-private.php: The application configuration settings required for the developer on its development environment.
• environments/main-prod.php: The application configuration settings required for the application on production
• main-env.php: This file will be override with the environment specific application configuration selected by the runpostDeployscript (as we are going to explain after)
• main-local.php: This is the application configuration options for the developer*
• params-env.php: This will be override with the environment specific parameters selected by the runpostdeploy script
• params-local.php: The application parameters for the developer*
• params.php: The application parameters
• test.php: Test application configuration options

The configuration tree override in the following way:

local settings > environment specific > main configuration file

That means that local settings override environment specific and its result override main configuration file. And this is true for all configurations folders being the common configuration folder settings predominant over the application specific one:

common shared params > application params common shared config > application config

There is a slight difference between the *-private.php and the *-local.php files. The first ones are automatically read with the runpostdeploy script and it could be settings that developers sitting on same machines in internal networks, and the latest is the programmer’s configurations.

The base configuration should be put under version control, like regular source code, so that it can be shared by every developer. The local configuration should not be put under version control and should only exist in each developer’s working directory.

The runpostdeploy script

The project has a very useful script that automatically creates the required and not shared folders for a Yii application: the runtimeand assets folders, extracts the configuration settings specified for a specific environment and copies them to the *-env.php files and runs migrations when not on private environments -we believe that migrations should be always run manually by developers on their machines.

From the application’s root folder, to run the script simply do:

./runpostdeploy environmentType migrations 

• environmentType (required): can be “any” of the ones you configure on the environments folders (i.e../runpostdeploy private to use *-private.php configurations)
• migrations (optional): could be “migrate“” or “no-migrate“.
  • migrate: will run migrations
  • no-migrate: will not run migrations (on private wont run them anyway)

well-built beautifully designed web applications
www.clevertech.biz

Tweet this!

ENexmo Library allows Yii programmers to use the Restful API offered by Mobile Messaging provider Nexmo.

ENexmo is a cloud-based SMS API that lets you send and receive high volume of messages at wholesale rates.

Requires

• Nexmo API credentials
• EHttpClient Extension
• Yii Framework

Quick Start

Once you have created your Nexmo account and include ENexmo library and EHttpClient on the extension folder is as easy as this:

/* import extensions before any call */
Yii::import('ext.httpclient.*');
Yii::import('ext.nexmo.*');
/* to send a message */
$nexmo_sms = new ENexmoSms('YOURAPIKEY','YOURAPISECRET');
$response = $nexmo_sms->sendTextMessage('RECIPIENTSNUMBER','SENDERID','Howdy testing! Please, search on http://www.google.com.');
/* responses are on JSON or XML. Defaults to JSON, but you can change that */
/* we use CHtml::encode for demo purposes only, to check for responses */
echo CHtml::encode($response);
/* to make requests for account */
$nexmo_account = new ENexmoAccount('key','secret');
$nexmo_account->format = ENexmoBase::FORMAT_JSON;
/* to search for a message */
echo CHtml::encode($nexmo_account->searchMessage('09AFDA98'));
//echo CHtml::encode($nexmo_account->searchMessagesByIds(array('09AFCC5B','09AFDA98')));
//echo CHtml::encode($nexmo_account->searchMessagesByDateAndRecipient('2012-03-20','34607040932'));
//echo CHtml::encode($nexmo_account->balance);
//echo CHtml::encode($nexmo_account->ownNumbers);
//echo CHtml::encode($nexmo_account->getSmsPricing('ES'));

Please check Nexmo API Documentation Nexmo API Documentation

Tweet this!