Redirector does what it says on the tin and redirects the user to another page. I mostly use this when coming back from filling a form in, so that the user is then redirected to another page. In admin systems, this is usually a list page. On front end websites, this is usually a thank you page. Though for log-in forms, I tend to try and return the user to where they were going!

It's used in a controller action method like this:

$urlOptions = array('controller'=>'index', 'action'=>'index');
$this->_helper->redirector->gotoRoute($urlOptions);

gotoRoute() takes the same set of parameters are the url() view helper which is not a surprise as they both proxy through to the Front Controller's router object. It's handy though as one you know one, you know the other :)

If you are using the default route, then you can use gotoSimple(). For example to redirect to the news controller's list action, you would do:

$this->_helper->redirector->gotoSimple('list', 'news');

The gotoSimple() method signature is:

gotoSimple($action, $controller = null, $module = null, array $params = array());

As you can see, it provides defaults for the controller and module and params parameters so you only need to set them if you need to. This works well for admin system as I tend to be redirecting within the same controller (from the edit or delete action to index, usually).

You can also use the Redirector with an absolute URL, by using the gotoUrl() method:

$url = 'http://www.akrabat.com';
$this->_helper->redirector->gotoUrl($url);

I tend to use this one much less frequently - so infrequently, that I can't think of a use-case off the top of my head :)

By default, Redirector sets a 302 status code, however you can also set a 301 if you want to:

$this->_helpers->redirector->setCode(301);

There are a few other options that can be set like setExit() and setUseAbsoluteUri(), but to be honest, I don't think I've ever used them!

I find that I use Redirector fairly frequently as its gotoRoute() uses the same parameters as url() which makes it easy to remember how to use it. Like url(), it also benefits from remembering which route was used to get you to the current page and reuses that when creating the next one which is handy.

FlashMessenger is a helper that allows you to store messages between requests. The most common use I have for it is for a "saved" message after doing an edit of an item that then redirects back to a list.

This is how it's used:

Storing a message

Storing to the FlashMessenger is easy. This is my typical usage within an action controller:

$this->_helper->flashMessenger->addMessage('Task saved');
$this->_helper->redirector('index');

This code adds the message "Task saved" to the FlashMessenger and then redirects the user the index action, which in this case is a list of tasks. As should be obvious from the name of the method, you can add multiple messages and they will all be stored for retrieval after the next redirect.

The FlashMessenger will store the message that you've added for one hop, or number of requests. This means that the message will be available for retrieval on the next request, but unavailable on the request afterwards. This is very useful and it means that if someone refreshes the task list by hitting F5, then the "Task saved" message does not reappear.

Retrieving the stored messages

Retrieving the stored messages is similarly simple:

$this->view->messages = $this->_helper->flashMessenger->getMessages();

This will create an array of messages in your view object which you can then loop over in your view script:

<?php if (count($this->messages)) : ?>
<ul id="messages">
<?php foreach ($this->messages as $message) : ?>
    <li><?php echo $this->escape($message); ?></li>
<?php endforeach; ?>
</div>
<?php endif; ?>

and that's all there is to the FlashMessenger.

As an experiment, I have written it directly in HTML, rather than PDF as before and cover the login form along with the login controller code required to authenticate a user using a database table. For good measure, I've included logging out and a view helper to show how to access the logged in user's details.

The full source code is also available, if you don't want to type it in :)

I hope you find it useful.

It uses the application.ini key of resources.db.table_prefix as I couldn't think of a better one :) and then uses that for the schema_version table's name and also makes it available in your change objects.

For example, if application.ini contains resources.db.table_prefix = "myapp", then the manager will create the table myapp_schema_version to store the current version of the schema. In your change classes, you can then do this:

001-Users.php:

 class Users extends Akrabat_Db_Schema_AbstractChange 
 {
     function up()
     {
         $tableName = $this->_tablePrefix . 'users';
         $sql = "
             CREATE TABLE IF NOT EXISTS $tableName (
               id int(11) NOT NULL AUTO_INCREMENT,
               username varchar(50) NOT NULL,
               password varchar(75) NOT NULL,
               role varchar(200) NOT NULL DEFAULT 'user',
               PRIMARY KEY (id)
             ) ENGINE=InnoDB DEFAULT CHARSET=utf8;";
         $this->_db->query($sql);

         $data = array();
         $data['username'] = 'admin';
         $data['password'] = sha1('password');
         $data['role'] = 'admin';
         $this->_db->insert($tableName, $data);
     }

     function down()
     {
         $tableName = $this->_tablePrefix . 'users';
         $sql= "DROP TABLE IF EXISTS $tableName";
         $this->_db->query($sql);
     }

 }

which will create a table called myapp_users. Note that you are responsible for using the prefix property as the change classes cannot enforce what you do within the up() and down() methods. It also follows that you'll have to ensure that your models also use the correct prefix.

I have also made a change to the provider (Akrabat_Tool_DatabaseSchemaProvider) so that it loads the correct application.ini file based on the data in the project's profile. This shouldn't affect anyone using Akrabat_Db_Schema_Manager, except that we no longer define APPLICATION_ENV and APPLICATION_PATH for you.

Enjoy!

I was going to write up a little about it as I'm one of the volunteers on the team. However, Pádraic beat me to it and I don't think I could have written it any better, so go and read his write-up instead!

The CR Team at the moment is:

• Rob Allen (Akrabat)
• Pádraic Brady (PadraicB)
• Steven Brown
• Shaun Farrell (farrelley)
• Pieter Kokx (kokx)
• Dolf Schimmel (Freeaqingme)
• Ben Scholzen (DASPRiD)

(alphabetical order has always suited me!)

We all accept email and can be found on irc in #zftalk.dev (freenode). Most are on Twitter too. Feel free to contact any of us about anything to do with contributing to Zend Framework and we'll find someone to help you!

Those of you with long memories may remember that I created a proposal along these lines back in 2006. Nearly four years later, I read it again and implemented the core section. One of the comments, by Wil, asked why it's worth bothering with a DDL to create tables, columns, indexes etc. as sooner or later you'll hit a wall and need to use SQL anyway. He has a point. My original idea was that as I routinely use MySQL and MS SQL Server, it would be handy to have cross-database code. Thinking about it however, there's not that much that isn't cross-database and I could just as easily write the specific SQL for those situations.

If you remove the DDL bit, then the rest is quite easy, so I wrote it and put it up on github into a project I've egotistically called Akrabat.

Migration files

It is intended that any time you want to make a change to your database schema (add columns, tables, indexes, etc), then you create a new migration file. A migration file is stored in ./scripts/migrations and is named like this 001-CreateUsersTable.php. The number defines the order that the migrations should be performed as any given migration will make assumptions about the state of the database before it is run.

The migration file contains a class that extends Akrabat_Db_Schema_AbstractChange and must contain two methods: up() and down(). It follows that up() is called when implementing the changes in this migration and down() is called to put the database back where it was if the change is backed out.

001-CreateUsersTable.php:

class CreateUsersTable extends Akrabat_Db_Schema_AbstractChange 
{
    function up()
    {
        $sql = "CREATE TABLE IF NOT EXISTS users (
                  id int(11) NOT NULL AUTO_INCREMENT,
                  username varchar(50) NOT NULL,
                  password varchar(75) NOT NULL,
                  roles varchar(200) NOT NULL DEFAULT 'user',
                  PRIMARY KEY (id)
                )";
        $this->_db->query($sql);
    
        $data = array();
        $data['username'] = 'admin';
        $data['password'] = sha1('password');
        $data['roles'] = 'user,admin';
        $this->_db->insert('users', $data);
        
    }
    
    function down()
    {
        $sql = "DROP TABLE IF EXISTS users";
        $this->_db->query($sql);
    }
}

As you can see, this code will create a database table called users and then insert the first user. The backing out code (down()) just drops the table. As you can see, easy enough and uses Zend_Db_Adater so the database calls should be familiar.

For this to work, we need to store the current version of the schema within the database. This is done using a table called schema_version which contains just one column, version, and one row holding the current version number. Akrabat_Db_Schema_Manager will create this table if it does not exist.

Akrabat_Db_Schema_Manager

This is the class that does the work. It's based on the skeleton on the proposal and the code is here. There are two public methods in Akrabat_Db_Schema_Manager :

• getCurrentSchemaVersion()
• updateTo($version)<

In order to operate, Akrabat_Db_Schema_Manager needs the directory holding the migration files and a database adapter, so these are passed in via the constructor. The operation of updateTo() is fairly simple:

1. Find and order migration files from current version to target version
2. Iterate over migration files and call up() or down() as appropriate
3. Update the current version number in the database

Obviously, getCurrentSchemaVersion() simply queries the database for the current version number.

Command line

To actually run the schema manager, we hook into Zend_Tool so we can use the zf command line tool. This means that we need a provider, Akrabat_Tool_DatabaseSchemaProvider. A provider is used by Zend_Tool to provide functionality for zf. We create a public method for each operation we want to be available at the command line:

• updateTo($version, $env='development', $dir='./scripts/migrations')
• update($env='development', $dir='./scripts/migrations')
• current($env='development', $dir='./scripts/migrations')

The update() method is simply an alias to updateTo() that ensures that you update to the latest migration script that you have.

They are used like this:

$ zf current database-schema
Current schema version is 0

$ zf update database-schema
Schema updated to version 2

$ zf current database-schema
Current schema version is 2

The update-to operation allows you to roll-back also:

$ zf current database-schema
Current schema version is 2

$ zf update-to database-schema 1
Schema updated to version 1

$ zf current database-schema
Current schema version is 1

It turns out that adding a new provider to Zend_Tool requires a little bit of work. Ralph Schindler is the man who writes it all and Cal Evans is the ZF command line guru that writes it up in a way I can understand. A quick search of his blog helped me work this out. Thanks Cal!

These are the steps that you need to do:

1. At the command line, run zf --setup storage-directory
   This creates a folder for storing Zend_Tool configuration files. Make a note of which directory it has created.
2. Run zf --setup config-file
   This creates zf.ini in your storage directory.
3. Edit zf.ini and change the php.include_path path so that it includes the full path to Akrabat/library in addition to the path to Zend Framework.For my installation, I have placed both Zend Framework and the Akrabat library in /usr/local/include, so I have:

   php.include_path = "/usr/local/include/zend-framework/library:/usr/local/include/Akrabat/library/"
   

4. Finally, we need to tell Zend_Tool about our new provider. This is done using the basicloader.classes key in zf.ini. So add:

   basicloader.classes.0 = "Akrabat_Tool_DatabaseSchemaProvider"
   

Once you've done that (and installed Akrabat into /usr/local/include or wherever), then you should now be able to run $ zf ? database-schema and get a result:

Everything is now in place. All you need to do is create a script/migrations directory and populate it with migration scripts and you're good to go!

If you come across any bugs, please report any bugs you find (preferably with the fix!)

Update: Table prefixes are now supported.

Consider Zend Framework's default error controller:

   public function errorAction()
    {
        $errors = $this->_getParam('error_handler');
        
        switch ($errors->type) {
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ROUTE:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:
        
                // 404 error -- controller or action not found
                $this->getResponse()->setHttpResponseCode(404);
                $this->view->message = 'Page not found';
                break;
            default:
                // application error
                $this->getResponse()->setHttpResponseCode(500);
                $this->view->message = 'Application error';
                break;
        }
        
        // Log exception, if logger available
        if ($log = $this->getLog()) {
            $log->crit($this->view->message, $errors->exception);
        }
        
        // conditionally display exceptions
        if ($this->getInvokeArg('displayExceptions') == true) {
            $this->view->exception = $errors->exception;
        }
        
        $this->view->request   = $errors->request;
    }

The error handler in ZF will catch any exceptions and route them to the error action in the error controller. This then sets the correct HTTP response code, logs the error and optionally displays it if a config setting is set.

Obviously on our production boxes, we don't display the exceptions, but we do on our local development machines.

IIS has the concept of custom error pages that it displays when the app returns a 4xx or 5xx status code:

There is also some settings for this page:

By default this is set so that if you access the site using the localhost domain, then you'll get the ZF error page and if you access the site remotely then you'll get the IIS custom page and won't see the error.

If, like me, you are developing with your IIS in a VM and using the host OS's browser and developer tools, then you need to change the setting to "Detailed":

Now you can see your exceptions and it doesn't look like PHP has crashed :)

As a result, I have updated my Zend Framework tutorial so that it is completely current. The main change I made was to remove the _init methods in the Bootstrap as they are no longer needed. I also take advantage of the new features of the zf tool to enable layouts and create forms. It's a shame that it gets the class name of the form wrong though!

If you need to know whether a view helper exists before you call it, one way is to write a simple view helper to tell you:

class App_View_Helper_HelperExists extends Zend_View_Helper_Abstract
{
    function helperExists($name) {
        return (bool)$this->view->getPluginLoader('helper')->load($name, false);
    }
}

You can then use it in a view scripts like this:

<?php if ($this->helperExists('doMagic')) { echo $this->doMagic(); } ?>

As Jeremy mentions in the comments, this code came out of a discussion on the PHPNW IRC channel #phpnw

In my case, I wanted to create a resource for CouchDb that checked that the database was created and if not, create it.

Creating your own plugin is easy enough. The obvious place is library/App/Application/Resource and a typical resource would look like this:

class App_Application_Resource_Couchdb extends Zend_Application_Resource_ResourceAbstract
{
    /**
     * Defined by Zend_Application_Resource_Resource
     *
     * @return Phly_Couch|null
     */
    public function init()
    {
         // do stuff here to init CouchDB
        $options = $this->getOptions(); 
        // $options contains everything under 'resources.couchdb' in application.ini
    }
}

You then need to tell Zend_Application about your new plugins. This is done with this line in application.ini:

pluginPaths.App_Application_Resource_ = "App/Application/Resource"

You can now have as many resource plugins as you like within the App_Application_Resource_ class-space.

Also, Matthew Weier O'Phinney has also written an article on Zend_Application which you should read too.