About

DluTwBootstrap is a Zend Framework 2 module consisting primarily of view helpers, which let you easily generate Twitter Bootstrap UI forms from your standard Zend Framework 2 Form objects without getting your hands dirty with Twitter Bootstrap mark-up. Check the on-line demo to see it in action.

Update to Zend Framework 2 RC6

BC breaks

The Select, Radio and MultiCheckbox value options have been moved from attributes into properties (please see Zend Framework 2.0.0rc6 Released for details). The option values for Selects, Radios and MultiCheckboxes should be now defined under value_options key like this:

//Excerpt from an element definition
'options' => array(
    'label'          => 'Element label',
    'value_options'  => array(
        'opt_value1'     => 'Label for Option 1',
        'opt_value2'     => 'Label for Option 2',
        'opt_value3'     => 'Label for Option 3',
    ),
),

New features

The form error messages may be suppressed

The formRowTwb, formFieldsetTwb and formTwb view helpers now accept a boolean parameter $renderErrors. If set to false, the validation error messages for an element (or for the whole fieldset or form) will not be rendered. Note though, that the form element will still be marked as having errors (i.e. red text and outline), only the error messages are not printed. This parameter is optional and defaults to true. (This feature mimicks the ZF2 formRow view helper behaviour.)

The Text input supports prepended and appended icons

The Text input element always supported prepended and appended texts and now you can also prepend / append icons.

The icons to prepend / append are specified in the $displayOptions array:

//In a view script...
//Display options for an element
$myElemDisplayOptions => array(
    'class'       => 'input-medium',
    'prependIcon' => 'icon-heart',
    'appendIcon'  => 'icon-glass',
),
//Display the element
echo $this->formRowTwb($form->get('myElem'), $formType, $myElemDisplayOptions);

You can combine prepended / appended text with icons. The icons are always displayed ‘inside’ (i.e. closer to the input element) and texts are displayed ‘outside’ (i.e. further from the input element).

The Password input supports prepended and appended texts and icons

The Password input now supports prepended / appended text as well as icons. The usage is identical to the Text input.

Have you found a bug?

Should you find a bug in DluTwBootstrap or have a feature request, please use the DluTwBootstrap bugtracker to post a new issue. Thanks for your help!

Links

• DluTwBootstrap module (source repo)
• DluTwBootstrap Demo module (source repo)
• DluTwBootstrap Demo Application (live on-line)
• DluTwBootstrap Demo Application (source repo)
• Other blog posts on DluTwBootstrap module

About

DluTwBootstrap is a Zend Framework 2 module consisting primarily of view helpers, which let you easily generate Twitter Bootstrap UI forms from your standard Zend Framework 2 Form objects without getting your hands dirty with Twitter Bootstrap mark-up. Check the on-line demo to see it in action.

Update to Zend Framework 2 RC5

BC breaks

There is only a single BC break: The FormButton view helper has been refactored and the button label has been moved from attributes to options. Go to the on-line demo, select Horizontal form, and check the Form tab, which shows the correct definition of the button component.

Composer support

DluTwBootstrap can be installed / updated using Composer. Please see the Installation – with Composer paragraph for instructions.

Update to Twitter Bootstrap 2.1.0

The new version of Twitter Bootstrap adds a few new form related features but the general mark-up remains the same. There are three things worth noting though.

Larger font

The default distribution of Twitter Bootstrap 2.1.0 uses a larger font size and line height as compared to the version 2.0.4. It’s 14px/20px vs. 13px/18px. (There are other changes, of course, go to the Bootstrap 2.1.0 released blog post to review them.)

The increased sizes were too much for me, so I used a custom built Twitter Bootstrap 2.1.0 library with the original sizing of 13px/18px. The Twitter Bootstrap library packaged with the DluTwBootstrap module is this customized smaller font version!

If you want to use the default distribution (or another custom build), just replace the public/css/bootstrap.min.css and optionally the public/js/bootstrap.min.js files.

Although Twitter Bootstrap recalculates other dimensions (padding, margins, inputs, etc.) based on the font size / line height in the custom build, the headings (<h1> through <h6>) remain the same and look disproportionatelly big. The DluTwBootstrap module overrides the default Twitter Bootstrap styling as little as possible, so it’s left up to you to provide a style override for these elements, if you deem it necessary.

Twitter Bootstrap 2.1.0 bug

There is a bug in Twitter Bootstrap v2.1.0 causing a thin gray line to be rendered above radio options in error state. To see this bug, go to the on-line demo, select the Horizontal form, submit it (do not enter anything) and check the Radio and Radio Inline elements.

This bug has already been fixed in Twitter Bootstrap master and the fix should appear in 2.1.1 release (see Issue #4526 for details).

jQuery update

Together with Twitter Bootstrap update, the jQuery library distributed with DluTwBootstrap has been updated too to version 1.8.0. You might want to update the references in your layouts.

Links

• DluTwBootstrap module (source repo)
• DluTwBootstrap Demo module (source repo)
• DluTwBootstrap Demo Application (live on-line)
• DluTwBootstrap Demo Application (source repo)
• Other blog posts on DluTwBootstrap module

About

DluTwBootstrap is a Zend Framework 2 module consisting primarily of view helpers, which let you easily generate Twitter Bootstrap UI forms from your standard Zend Framework 2 Form objects without getting your hands dirty with Twitter Bootstrap mark-up.

Reworked from scratch

The module has been updated to reflect the changes in Zend Framework 2 RC3. There are numerous BC breaks, so please refactor your projects. The Zend Framework 2 API should be changing much less now as we are approaching the stable release, so the DluTwBootstrap module should be now also more stable and should not be that picky about the ZF2 version.

Yes, the much asked for echo $form; is here (well, not exactly that but a one-liner nonetheless).

The module has been not only updated to the latest ZF2 release, but also reworked from gound up so it is much cleaner and consistent now.

First go to on-line demo

As always, you should first visit the on-line demo here:

http://apps.zfdaily.com/dlutwbootstrap-demo

The on-line demo shows everything the module can do side-by-side with the source used to produce the demo output. The demo application is your primary reference.

Components

• DluTwBootstrap module – a ZF2 module containing view helpers, classes and styles which enable your applications to render Twitter Bootstrap UI (forms).
• DluTwBootstrap Demo module – a ZF2 module demonstrating capabilities of the DluTwBootstrap module. Install and enable this module in your app to check that you have installed DluTwBootstrap correctly.
• DluTwBootstrap Demo Application (on-line) – a simple ZF2 application integrating both the modules. You should not need the app’s source, but it’s here for your reference.

Installation

The installation steps are described in README.md files in the root of each package. Go to the respective repositories mentioned above to review them.

Usage

First of all: Yes, the much asked for echo $form; is here (well, not exactly that but a one-liner nonetheless). Although Zend Framework 2 itself does not support form display with a single command I decided to implement this feature with the following disclaimer:

The one-liner should be used only either for a quick form preview or in situations when there are no special requirements for form presentation. If you need anything else, use the manually controlled form output DluTwBootstrap offers.

So you can have it both ways. Either a dead simple fully automated form display on one line or a more laborous fully controlled form output. Your call.

The simplest case

1. Create a standard Zend\Form\Form object
2. Pass your form object to view
3. Prepare your form: $form->prepare();
4. Output the form: echo $this->formTwb($form);

This procedure would output a horizontal Twitter Bootstrap form. The horizontal form type is considered default in DluTwBootstrap. Pass second argument to the formTwb() helper to control which form type will be displayed. Use the provided constants:

echo $this->formTwb($form, \DluTwBootstrap\Form\FormUtil::FORM_TYPE_VERTICAL);

There is also the third optional parameter to formTwb() which contains the display options. You can use it to change the most common display aspects of the form (e.g. the size of input fields) and still use the simple one line form output. The display options also control which fields will be marked as required (more on that later). Please go to the on-line demo to see how the $displayOptions parameter is used.

The not so simple case

If you need more control over your form presentation, your best friend is the formRowTwb() view helper. It’s used like this:

echo $this->formTwb()->openTag($form, $formType);
echo $this->formRowTwb($form->get('myElement'), $formType, $elementDisplayOptions);
echo $this->formTwb()->closeTag();

This sequence of commands would output a single form element together with label, hint, description, possible validation errors and any required Twitter Bootstrap mark-up. The formRowTwb() helper can render any supported form element (inputs, checkboxes, buttons, etc.).

This is the optimal level of control. You can insert anything special between form elements yet you still do not have to think about Twitter Bootstrap markup. Just output any number of formRowTwb() interspersed with your custom display code, wrap everything in opening/closing tags and you are done.

As for the level of control, you can go in both directions from here. You can output whole fieldsets using

echo $this->formFieldsetTwb($fieldset, $formType, $fieldsetDisplayOptions);

or you can dig deeper and manually control the individual parts of the formRow using the appropriate view helpers for label, element, description, errors, etc. In this case though you are the one who is responsible for proper Twitter Bootstrap mark-up and your forms may not render correctly if you mess things up.

What is obvious

DluTwBootstrap module mimicks the original Zend Framework view helpers where possible. If there is the formRow() view helper in ZF2, DluTwBootstrap has formRowTwb(). Just add Twb suffix.

What is not so obvious

There are two DluTwBootstrap view helpers you should know about which do not have a ZF2 counter part: formFieldsetTwb() which we’ve already talked about (outputs whole fieldsets) and formActionsTwb(). The formActionsTwb() view helper outputs form buttons with correct Twitter Bootstrap mark-up around. See the on-line demo for details.

DluTwBootstrap can optionally highlight required fields. This is something you won’t find in Twitter Bootstrap itself, but I think it’s useful to indicate to the user which fields are mandatory. (I do not want to start a philosophical debate on this, although your opinion is welcome. This feature is optional, so if you think form fields should be never visually marked as required, just ignore it.)

If you want to visually mark a field as required, use the $displayOptions array parameter and set 'required' => true. (See the on-line demo for details.) There are three places where you can specify the element as ‘required’. Their meaning differs though:

• ‘required’ attribute of the element object – just adds the HTML5 ‘required’ attribute to the tag. Makes the form/element semantically correct.
• ‘required’ option of the input filter – forces the user to actually fill out the field otherwise the form won’t validate
• ‘required’ option of the DluTwBootstrap display options – visually marks the element as required/mandatory

Supported elements

All basic elements are supported by DluTwBootstrap. The TODO list contains all HTML5 elements (date, color, etc.), captcha, image and collections. If you need any of them on your form now, you can add markup for them manually in your view script.

DluTwBootstrap benefits

There are two important aspects worth noting: DluTwBootstrap does not force you into a specific form output mode. You can select the required level of control as you wish from fully automated output in one line of code to fully controlled output of the individual atomic form parts. You can also combine these two aproaches at will.

The other strong point of DluTwBootstrap is its clean separation of presentation specifics from the form definition. The form definition (i.e. the form object) contains no information used solely to control output of Twitter Bootstrap markup (e.g. a Twitter Bootstrap CSS class). The user controllable Twitter Bootstrap specifics are contained in the $displayOptions parameter optionaly passed to the Twb view helpers. If you decide to abandon Twitter Bootstrap and use another CSS template system, your form objects are perfectly ok, do not contain any Twitter Bootstrap specific artifacts and do not need any refactoring. Your changes would be kept exclusively inside your view scripts.

BC breaks

There are too many BC to mention them individually. The view helpers are renamed and removed, the parameters changed, the form objects should be defined as per ZF2 RC3 API (which is different – e.g. options instead of attributes), etc. Please check the on-line demo, review the demo form output and examine the source. DluTwBootstrap is easy to use and the best way to learn it is by example.

Links

• DluTwBootstrap module (source repo)
• DluTwBootstrap Demo module (source repo)
• DluTwBootstrap Demo Application (live on-line)
• DluTwBootstrap Demo Application (source repo)
• New Zend\Form features explained (the best explanation of Zend\Form functionality I know of)

Controllers are services

Controllers are services just like any other service you might define. The important difference is they are instantiated not by you at some point in your user code, but automatically as a part of the MVC workflow. How can we do, say, a constructor injection then, when it is not our code which instantiates the controller? This might seem like a problem but it’s quite easy in fact.

DI

Prior to the introduction of the ServiceManager, we had DI to do the dirty work of object instantiation and wiring. As controllers were instantiated by MVC using DI, it was rather easy to instruct the DI instance manager to inject whatever was necessary and voilà we had a fully configured controller with dependencies injected – almost like magic. But there ain’t no such thing as a free magic and this magic cost speed. When the ServiceManager (i.e. a Service Locator) came it eliminated the speed penalty of DI by not doing anything too clever and time consuming (e.g. introspection) and it took over the DI’s responsibilities throughout the ZF2.

(I won’t go into detail about the DI way of configuring controllers, because the ServiceManager is a preferred way to do things in ZF2 now. It’s still possible to use DI for this nonetheless. Drop me a line if you are interested in the DI method and I will post some code to demonstrate this.)

ServiceManager

Controllers are services, remember? The MVC workflow retrieves the controller instances from the ServiceManager. But do not rush to trace and debug your app to check it’s ServiceManager ($application->getServiceManager()) and see with your own eyes the controller instances there. You won’t find them there. It’s not this ServiceManager. The controller instances are managed by a separate dedicated scoped ServiceManager instance. So we can use neither the service_manager key in a config file nor the getServiceConfig() method in the Module class to configure our controller instances. We are thus back to our initial question: How do we do a constructor injection on a controller?

The dedicated ServiceManager instance used exclusively for controllers can be configured in two places: controllers key in a config file (please note the recent change from singular controller to plural controllers!) and getControllerConfig() method in the Module class. Both of these are expected to return an array with the ServiceManager configuration.

The controller classes which do not have any dependencies are set-up under the invokables subkey as a 'controllerServiceName' => 'Fully\Qualified\Controller\Classname' pairs. Please note the recent subkey name change from classes to invokables. Other thant that this is nothing new as you must be doing this already otherwise your controllers would not work:

/* module.config.php */
<?php
return array(
    'controllers' => array(
        'invokables'    => array(
            //Suppose one of our routes specifies
            //a controller named 'myController'
            'myController'    => 'MyModule\Controller\MyController',
        ),
    ),
);

The easiest method to create controller instances which do have dependencies is to use a factory. You can either write a proper factory implementing the Zend\ServiceManager\FactoryInterface:

/* MyModule/src/MyModule/ControllerFactory/MyControllerFact.php */
namespace MyModule/ControllerFactory;
use \Zend\ServiceManager\FactoryInterface;
use \Zend\ServiceManager\ServiceLocatorInterface;

class MyControllerFact implements FactoryInterface
{
    public function createService(ServiceLocatorInterface $serviceLocator) {
        /* @var $serviceLocator \Zend\Mvc\Controller\ControllerManager */
        $sm   = $serviceLocator->getServiceLocator();
        $depA = $sm->get('depA');
        $depB = $sm->get('depB');
        $controller = new \MyModule\Controller\MyController($depA, $depB);
        return $controller;
    }
}

And then simply put the reference to this factory under the factories subkey into the configuration file:

/* module.config.php */
<?php
return array(
    'controllers' => array(
        'factories'    => array(
            //Suppose one of our routes specifies
            //a controller named 'myController'
            'myController'    => 'MyModule\ControllerFactory\MyControllerFact',
        ),
    ),
);

Or you can use a closure and define the factory as a part of the configuration. Be careful though not to do this in the configuration file (please see the note Configuration and PHP on the ServiceManager Quick Start page for reasons). The proper place for this is the getControllerConfig() method:

/* MyModule/Module.php */
<?php
namespace MyModule;
use \Zend\Mvc\Controller\ControllerManager;

class Module
{
    public function getControllerConfig() {
        return array(
            'factories' => array(
                //Suppose one of our routes specifies
                //a controller named 'myController'
                'myController'    => function(ControllerManager $cm) {
                    $sm   = $cm->getServiceLocator();
                    $depA = $sm->get('depA');
                    $depB = $sm->get('depB');
                    $controller = new \MyModule\Controller\MyController($depA,
                                                                        $depB);
                    return $controller;
                },
            ),
        );

    //The getConfig() and getAutoloaderConfig() methods are omitted for brevity
}

Both ways you have the application’s ServiceManager instance available in your factory method (via the getServiceLocator() method) so it’s easy to pull any collaborators you might need to instantiate your controllers.

ServiceManager plugin fixes

This shape of things is a result of a recent ServiceManager rework. Please read Evan’s comments on the pull request #1695 to get a quick overview of the ServiceManager plugin configuration. The features described in this post are just a subset of the possibilities offered by various ZF2 ServiceManagers.

Conclusion

The ServiceManager (and DI) and its systematic utilization in ZF2 is a major improvement over ZF1. There is no similar facility in ZF1 (AFAIK) which would help you inject dependencies into controllers, you are on your own there. (It can be done though. If anyone is interested, I will happily share my ZF1 solution using an action helper, but it’s way more cumbersome than the elegant ServiceManager approach of ZF2.)

So there you have it. It’s so easy to configure your controllers in ZF2 now, that you really have no more excuses. Say ‘NO!’ to all news and singletons and do things the right way. You will thank yourself later.

Picture by Ali Hussein

DluTwBootstrap module

The Form component has been completely rewritten in ZF2 beta4. The DluTwBootstrap module has been updated to support the new Form component(s).
DluTwBootstrap repo

DluTwBootstrap Demo module

The demo part of the DluTwBootstrap module has been separated into its own module. This way it’s easy to quickly disable the demo when not needed yet keep it unobtrusively in your project should you need to check anything or experiment. (Just comment the demo module out in config/application.config.php.)
DluTwBootstrap Demo repo

DluTwBootstrap Demo Application

There is also a new application comprising both the forementioned modules. This application is running on-line for you to quickly see the DluTwBootstrap module in action without the need to install any modules yourself. You can thus decide in seconds if the DluTwBootstrap module is a good fit for your project.
DluTwBootstrap Demo Application LIVE

The source code of the application is also available, but generaly you should not need it as it contains nothing more than the two DluTwBootstrap modules. It might come in handy though as a reference if you are having troubles wiring the modules into your project.
DluTwBootstrap Demo Application repo

ZF2 version

IMPORTANT: The README.md in DluTwBootstrap module states the supported ZF2 version (please see the DluTwBootstrap repo overview and scroll down to ‘Supported versions’). As ZF2 is in beta the code base changes very quickly even in scope of a single version designation (i.e. Beta 4). If the DluTwBootstrap module does not seem to work, check the version of your ZF2 library and update to the version and commit specified in README.md.

Stay tuned

Two things are comming:

• A proper tutorial for Forms with DluTwBootstrap
• Support for Navigation elements (menus, buttons, tabs, etc.)

Keep an eye on this blog.

The task

We want to be able to configure the PHP ini settings in our ZF2 application, integrate the process naturally into the application workflow and use the existing configuration infrastructure (i.e. merging of configuration files, global / local overrides, etc.). Let’s build a ZF2 module for this!

The module

We should rather say ‘a mini-module’ as it really needs just a single file – Module.php. Let’s call this module PhpSettings. Here is its Module class:

<?php
namespace PhpSettings;

use Zend\EventManager\Event;

class Module
{
    /**
     * Configure PHP ini settings on the bootstrap event
     * @param Event $e
     */
    public function onBootstrap(Event $e) {
        $app         = $e->getParam('application');
        $config      = $app->getConfiguration();
        $phpSettings = $config['phpSettings'];
        if($phpSettings) {
            foreach($phpSettings as $key => $value) {
                ini_set($key, $value);
            }
        }
    }

    /* The getAutoloaderConfig() and getConfig() methods are left out here
       for brevity, as they are completely standard.
     */
}

The public method onBootstrap() is automatically recognized as a bootstrap event listener (a new feature in Beta4 – in Beta3 we had to register the listener in the init() method manually). It retrieves the configuration and iterates over its phpSettings entries passing them to the standard PHP ini_set() function.

Do not forget to enable your new module in your /config/application.config.php.

Configuration

The only thing left is to let our module know what directives we want to set. Just place phpSettings key into a configuration file and put all required PHP ini directives as its subkeys. You can find the list of all available PHP ini directives in the PHP docs.

You should follow the global/local concept of ZF2 configuration. NOTE: The naming of the default global / local configuration files changed in Beta4 – the ‘config’ part of the file name has been omitted. Watch out for this if your good old config files in the autoload directory stopped working after migration to Beta4.

Place your global environment agnostic options into global configuration files (e.g. /config/autoload/module.DluPhpSettings.global.php). These files will be included in your VCS. Here is an example of a global configuration:

<?php
/**
 * My Global Configuration
 * /config/autoload/module.DluPhpSettings.global.php
 *
 * You can use this file for overridding configuration values from modules, etc.  
 * You would place values in here that are agnostic to the environment and not 
 * sensitive to security. 
 *
 * @NOTE: In practice, this file will typically be INCLUDED in your source 
 * control, so do not include passwords or other sensitive information in this 
 * file.
 */

return array(
    'phpSettings'   => array(
        'display_startup_errors'        => false,
        'display_errors'                => false,
        'max_execution_time'            => 60,
        'date.timezone'                 => 'Europe/London',
        'mbstring.internal_encoding'    => 'UTF-8',
    ),
);

Your environment specific or sensitive information should go into local configuration files (e.g. /config/autoload/module.DluPhpSettings.local.php). Values in these files override the global configuration and they are excluded from the version control by default (if you are using the Zend Skeleton Application).

Here is an example of a local configuration present on a developer’s machine. It overrides some values from the global configuration:

<?php
/**
 * My Local Configuration (Development)
 * /config/autoload/module.DluPhpSettings.local.php
 *
 * This configuration override file is for overriding environment-specific and
 * security-sensitive configuration information.
 *
 * @NOTE: This file is ignored from Git by default with the .gitignore included
 * in ZendSkeletonApplication. This is a good practice, as it prevents sensitive
 * credentials from accidentally being comitted into version control.
 */

return array(
    'phpSettings'   => array(
        'display_startup_errors'        => true,
        'display_errors'                => true,
        'max_execution_time'            => 600,
    ),
);

Conclusion

We have created an ultra simple module which cleanly sets the PHP environment for our application. If you do not feel like coding even the single class needed for this module, you can download the DluPhpSettings module from my git repository.

How do YOU configure your PHP environment in your ZF2 applications? Let me know.

I was hit by this bug on my very first encounter with Zend Framework 2 when I tried to get the Zend Skeleton Application up and running. I had the application set-up on my localhost on the Apache web server in a vhost ‘subdirectory’ (i.e. alias) called zf2skeleton. I was trying to access it like this: http://localhost/zf2skeleton but I was only getting the following error:

The requested controller could not be mapped to an existing controller class.

After some unsuccessful tracing through the ZF2 MVC code I resorted to Rob Allen’s excellent Getting Started with ZF2 tutorial and followed it to the letter. That included setting up a dedicated vhost (i.e. no vhost subdirectory). And voilà, the Skeleton application worked! But wait, I do not want to create a new Apache vhost for every little ZF2 project I am going to play with. What’s wrong?

The bug

The problem is, that ZF2 is getting the baseUrl wrong. Instead of my actual baseUrl /zf2skeleton the Zend\Http\PhpEnvironment\Request::detectBaseUrl() method returns an empty string. There is an issue for this in the bugtracker here: baseUrl incorrect when installation is within a user’s document directory. Obviously not all users experience this incorrect behaviour, so it is likely it is related to a specific platform / webserver (I am on Windows / ZendServer / Apache). Anyway until this bug is removed, all those who are affected have to prime the ZF2 with a correct baseUrl manually.

Easy hack

If you want to go the quick and dirty road, you just need to squeeze one line of code into your /public/index.php:

$application = new Zend\Mvc\Application;
//Insert the following line with correct baseUrl
$application->getRequest()->setBaseUrl('/my-base-url');
$bootstrap->bootstrap($application);
$application->run()->send();

This will get the job done but you might feel uneasy about hacking the index.php in such a way. Although this modification is perfectly ok for experimenting with ZF2, it’s obviously inadequate for anything more.

DluBaseUrl module

There are probably many ways to accomplish the simple task of manually setting the baseUrl ‘the right way’. Using a custom ZF2 module may seem like an overkill but you shall see it is a good fit here.

Download or clone the DluBaseUrl module, install and enable it as usual. (The installation is described in detail on the module’s git repository overview page.)

Beside not having to touch the /public/index.php file the main benefit in using the DluBaseUrl module is its inherent relation to the application configuration – you can very easily get your fingers on the merged configuration in module’s bootstrap. Since the value of baseUrl is directly implied by the local environment, we should configure it in a local configuration file. ZF2 has a facility for this: put a config file with .local.config.php suffix into your /config/autoload directory. (There is a template config file shipped with DluBaseUrl module.) Configure your local baseUrl path in this config file and you are done.

By using this module you are also getting the benefit of an easy deactivation when the bug in ZF2 is removed. Just disable the DluBaseUrl module in your /config/application.config.php.

Modules are very powerful tool in ZF2. You can do great things with them, but you can also do very little things with them. Since they are designed to load and bootstrap quick, you do not have to worry about any negative impact on performance.

Your mileage may vary

As this bug is probably related to a specific platform, you might have not experienced it. I would be curious to know who encountered it and in what environment. Please drop me a line below saying if you are running ok out of the box or if you had to hack it somehow. If you have been hit by this bug, do not forget to vote for it.

DluTwBootstrap supports almost everything Twitter Bootstrap offers for forms.

Wait! Do not reinvent the wheel

Before I set out to write my own module I first looked for an available one and indeed there were two. Unfortunately neither of them suited my needs. But maybe they will be a better fit for you so here are the links:

• Twitter Bootstrap by Gabriel Habryn
• Twitter Bootstrap Form Decorators by Mike Willbanks

DluTwBootstrap — what can it do for you?

DluTwBootstrap supports almost everything Twitter Bootstrap offers for forms.

Form types

All four Twitter Bootstrap form types are supported:

• Horizontal
• Vertical
• Inline
• Search

Controls

All ZF2 form elements except Captcha and Image are supported:

• Button
• Checkbox
• File
• Hash
• Hidden
• MultiCheckbox
• Multiselect
• Password
• Radio
• Reset
• Select
• Submit
• Text
• Textarea

Element descriptions

Various descriptive and help texts are supported depending on the type of the element:

• Label
• Description
• Inline help
• Placeholder text

Error state and required elements

Elements with validation errors are rendered in red and the validation errors are clearly visible.

The required elements stand out.

Extras

The MultiCheckbox and Radio elements can be optionally rendered inline.

The Text element can optionally have a prepended or appended pieces of text.

If the form has a legend set, it is displayed as a form heading.

Get, install, check

First you need to get the DluTwBootstrap module, install it in your ZF2 application and check the demo page to see that everything is working correctly.

Please see the repository overview page with detailed installation instructions.

Twitter Bootstrap libraries

Enabling the DluTwBootstrap module in your ./config/application.config.php WILL NOT automatically provide the Twitter Bootstrap environment for your project. You either have to already have the Twitter Bootstrap functioning or you can follow instructions supplied with DluTwBootstrap to manually enable it for your project. All necessary libraries and scripts are packaged with the module as well as an example layout template, so it is pretty easy.

Demo forms

There are demo forms included with the module. Go to the URL
http://<your-machine>/tw-bootstrap-demo/form
to see them in action. Check the source code to see how the forms are constructed.

Basic usage

The DluTwBootstrap module is basically just a set of forms, elements and decorators extending the original ZF2 classes. The usage is very simple. Just extend one of the supplied form classes and go about the rest of your form as usual and you are done.

use DluTwBootstrap\Form\Horizontal;
class MyForm extends Horizontal
{
    public function init() {
        //Add your form controls in any standard ZF2 way
        //...
    }
}

By extending one of the supplied form classes (Horizontal, Vertical, Inline, Search) you are configuring the form plugin loader with custom prefix paths to load the supplied elements and decorators before the standard ones. As this is the standard way to extend the form functionality in ZF, you are still able to use any standard way to add elements to the form: addElement(), createElement() or configuration.

Advanced usage

There are a few Twitter Bootstrap form features not addressed by any standard ZF2 form means:

• Inline help text
• Placeholder text
• Inline Radio and MultiCheckbox elements
• Prepend and Append texts for the Text element
• Indented action buttons

All these are accessible either via setter methods (e.g. setInlineHelp(), setPlaceholderText()) or using configuration. The indented action buttons require a specific display group.

Please see the repository overview page for detailed instructions on basic as well as advanced usage.

All this in vain (sort of)

This is all very nice, but it won’t last! The ZF2 Form package is getting a major overhaul and some very basic concepts are going to change (e.g. we likely lose the decorators in favour of the view helpers). See the RFC – Forms to learn more. When the new Form package arrives in one of the future betas this module will need massive refactoring (and probably your form classes too). But until then we can easily generate nice looking Twitter Bootstrap forms using the DluTwBootstrap module.

Fatal error: Uncaught exception ‘Zend_Application_Bootstrap_Exception’ with message ‘Circular resource dependency detected’ in…

Damn. Two of my resources are trying to bootstrap each other!

Depending on the complexity of your Bootstrap you might be in for a rather long investigation of your resources and their dependencies. If you are initializing only a few resources you will probably identify the culprits straight away but if your Bootstrap is a bit longer the offending resources might be difficult to find and untangle. Let’s build a simple tool for Zend Framework 1 applications which will make the troubleshooting easier.

What is circular dependency in Bootstrap?

Imagine situation when resource A needs to bootstrap resource B and resource B needs to bootstrap A. Like this:

The resources may also depend on each other via an intermediary (or more):

The bootstrapping mechanism of Zend Framework detects these dependencies and halts the execution with the forementioned fatal error (otherwise we would end up in an infinite loop). Unfortunately the error itself is of little help when troubleshooting as we only get the names of two resources taking part in the loop and they are in a pretty messy format on top of that. Try to decipher the names of the two resources from the complete error message:

Fatal error: Uncaught exception ‘Zend_Application_Bootstrap_Exception’ with message ‘Circular resource dependency detected’ in C:\WebDev\Libraries\ZF\v1.11.11\library\Zend\Application\Bootstrap\BootstrapAbstract.php:662 Stack trace: #0 C:\WebDev\Libraries\ZF\v1.11.11\library\Zend\Application\Bootstrap\BootstrapAbstract.php(629): Zend_Application_Bootstrap_BootstrapAbstract->_executeResource(‘resourceC’) #1 C:\WebDev\PhpStorm\SandBoxMVC-ZF1\application\Bootstrap.php(46): Zend_Application_Bootstrap_BootstrapAbstract->_bootstrap(‘resourceC’) #2 C:\WebDev\Libraries\ZF\v1.11.11\library\Zend\Application\Bootstrap\BootstrapAbstract.php(669): Bootstrap->_initResourceD() #3 C:\WebDev\Libraries\ZF\v1.11.11\library\Zend\Application\Bootstrap\BootstrapAbstract.php(629): Zend_Application_Bootstrap_BootstrapAbstract->_executeResource(‘resourceD’) #4 C:\WebDev\PhpStorm\SandBoxMVC-ZF1\application\Bootstrap.php(53): Zend_Application_Bootstrap_BootstrapAbstract->_bootstrap(‘resourceD’) #5 C:\WebDev\Libraries\ZF\v1.11.11\library\Zend\Applic in C:\WebDev\Libraries\ZF\v1.11.11\library\Zend\Application\Bootstrap\BootstrapAbstract.php on line 662

You are right, it’s resourceC and resourceD, but have you had fun extracting these out? And more importantly, can you be sure that it is only these two resources which form the dependency circle? (Hint: you cannot.) What we need is a clearer view of resource dependencies.

Extend the original ZF Bootstrap

We will tap into the bootstrap process to display resource names as they are being initialized. To do this we need to extend the Zend_Application_Bootstrap_Bootstrap class and override the _executeResource() method. We will then save our new bootstrap class in a library and use it as a base class for the actual Bootstrap class of our application.

class Dlu_Wal_Bootstrap extends Zend_Application_Bootstrap_Bootstrap {

    /**
     * Turns Bootstrap Debug logging on/off
     * Redefine in descendant
     * @var boolean
     */
    protected $_logging		= false;

    /**
     * Current indentation level
     * @var integer
     * @see _executeResource()
     */
    protected $_indent		= 0;

    /**
     * Resource counter
     * Counts resources as they are being bootstrapped
     * @var int
     */
    protected $_rscCounter  = 0;

    /* ****************************** METHODS ************************** */

    /**
     * Execute a resource with optional logging
     * Echoes the resource name and proxies to the overloaded method
     * @param  string $resource
     */
    protected function _executeResource($resource) {
        $resource   = strtolower($resource);
        if($this->_logging && !in_array($resource, $this->_run)) {
            $this->_rscCounter++;
            $line   = sprintf('#%03d %s %s', $this->_rscCounter,
                              str_repeat(' ', $this->_indent * 3),
                              $resource);
            //NOTE! Wrap the $line variable in html pre tag!
            echo "$line";
            $startLogged	= true;
            $this->_indent++;
        } else {
            $startLogged	= false;
        }
        parent::_executeResource($resource);
        if($startLogged) {
            $this->_indent--;
        }
    }
}

Please note the line 39 and the preceding comment if you are going to copy and paste this piece of code. (It is safer to download the code instead.)

Use the modified Bootstrap

Base your application’s Bootstrap class on Dlu_Wal_Bootstrap, turn on logging (line 7) and you are done:

class Bootstrap extends Dlu_Wal_Bootstrap
{
    /**
     * Turns Bootstrap Debug logging on/off
     * @var boolean
     */
    protected $_logging		= true;

    //Define your resource methods
    //...
}

Now it is much easier to see the dependencies between the resources:

#001  resourcea
#002     resourceb
#003  resourcec
#004     resourcee
#005        resourced
#006           resourcec

Fatal error: Uncaught exception 'Zend_Application_Bootstrap_Exception' with message 'Circular resource dependency detected' in

The notation is pretty much self explanatory. If a resource initializes other resources, they are indented. As we can see the resource C needs the resource E which needs resource D which needs resource C again:

Now you know that your problem of circular dependency is limited to resources C, E and D and you have to untangle these somehow.

Breaking the vicious circle

Well, putting the resources and their dependencies straight is a different story and actually a bit off-topic. Anyway here are two hints:

Split the resource

There is very likely a ‘hidden’ resource in one (or more) of your resources. In other words some of your resources are trying to do too much and their responsibilities are not clearly focused. Split the resource into two and extract the hidden responsibility and you will eliminate the circular dependency. By doing this you will also improve the overall design. This is the clear and propper solution as you are tackling the root cause of your circular dependency problem. If your ‘circle’ is formed by more than two resources though, it might be quite difficult to extract the hidden resource(s).

The Bootstrap is as close to the dependency injection container as you can get in Zend Framework 1. Initializing another resource from a resource method is akin to the constructor injection. Spliting the resource is thus similar to the solution Miško Hevery suggests for circular dependency between objects in his blog post Circular Dependency in constructors and Dependency Injection. Although it is based on Java you will find more details about this approach there and it is definitely worth reading.

Use ‘setter injection’

Do not initialize one of your resources completely in the relevant resource method, leaving out the dependency forming the circle. You will get a partialy initialized resource but you will be able to use it as a dependency in another resource. You will finish the initialization of the partialy initialized resource later (e.g. in a new resource method), when all of the resources in the circle have been (at least partialy) initialized.

But that’s cheating! We have left the circular dependency intact! You are right. We have not eliminated the circle at all but we have built some resources in two phases instead. This is similar to setter injection. You might think this approach has a slightly fishy odour. It has. The devil is in the word ‘partialy’. Your resource method produced an incomplete or not functioning resource. The resource will be ok only after the second phase of its initialization. What if anyone uses the resource in the critical time space after it has been created but before it has been completely initialized? It is up to you to secure this hole and not enable usage of the partialy initialized resource. As we are talking Zend Framework 1 Bootstrap, it should not be too difficult.

Back to the tool

The resource logging tool is very simple. It just keeps track of the number of initialized resources and indentation level corresponding to the hierarchy structure of the resource dependencies and prints the correctly indented resource name together with its number to the screen. There is only one thing you should be aware of: The log contains only resources being actually initialized (not merely used). If resource A calls bootstrap('b') but the resource B has already been initialized, it will not be logged.

The good and the bad

This resource logging tool is very simple to implement and use. Just base your Bootstrap class on our modified base class and keep the logging switched off. If you ever get the 'Circular resource dependency detected' error, flip the switch (the $_logging property) and you instantly see the troublemakers.

You might not like the crude screen logging. Of course there are better ways to output diagnostic information (Zend_Log and namely Zend_Log_Writer_Firebug), but remember, we are dealing with Bootstrap and we likely do not have any more sophisticated resources available yet. You might also ask about the performance impact with the logging switched off. I consider this negligible (there are certainly other way more significant bottlenecks in the app) and do not bother to change the Bootstrap base class for production.

Summary

We have built a quick and dirty logging tool which helps in discovering dependencies between Bootstrap resources. We have also suggested possible solutions to the circular dependencies in Bootstrap.

The code mentioned in this article forms a part of my Web App Library, which can be downloaded complete with a Bootstrap example here: https://bitbucket.org/dlu/web-app-library/downloads