1
2
3
4
5
6
7
8
9
10

use bugs;

db.issues.ensureIndex({ title: 1 }, { unique: true });
db.issues.ensureIndex({ "tasks.title": 1 }, { unique: true, sparse: true });

// add an issue with a task
db.issues.insert({ title: "Issue1", tasks: [ { title: "Task1" } ] });

// add another issue with a task and the same title
db.issues.insert({ title: "Issue2", tasks: [ { title: "Task1" } ] });

When you run the last insert statement, you will receive E11000 duplicate key error index: bugs.issues.$tasks.title_1 dup key: { : "Task1" } This is because you are trying to insert an embedded task in the issues collection with the same title.

Let’s say you wanted to allow a task with the same title embedded in another issue. In order to accomplish this, you need to create a compound index.

1
2
3
4
5
6
7
8
9
10

use bugs;

db.issues.ensureIndex({ title: 1 }, { unique: true });
db.issues.ensureIndex({ title: 1, "tasks.title": 1 }, { unique: true, sparse: true });

// add an issue with a task
db.issues.insert({ title: "Issue1", tasks: [ { title: "Task1" } ] });

// add another issue with a task and the same title
db.issues.insert({ title: "Issue2", tasks: [ { title: "Task1" } ] });

With our compound index, we can now add a task with the same title in different documents.

Single Document Unique Indexes

We’ve covered embedded unique indexes for the collection and over multiple documents. However, what about the scenario for only allowing unique tasks on a single document? Let’s take a look at the following example:

1
2
3
4
5
6
7
8
9
10

use bugs;

db.issues.ensureIndex({ title: 1 }, { unique: true });
db.issues.ensureIndex({ title: 1, "tasks.title": 1 }, { unique: true, sparse: true });

// add an issue with a task
db.issues.insert({ title: "Issue1", tasks: [ { title: "Task1" } ] });

// add another task to the issue with the same title
db.issues.update({ title: "Issue1" }, { $push: { tasks: { title: "Task1" } } });

Would you expect the last update statement to return a unique error or add another task with the same title? As of MongoDB 2.2, the task is added.

There has been an issue open since April of 2010. It’s simply because the original design of unique indexes were document based and not targeted for embedded documents.

Workarounds

There are some workarounds to preventing duplicated data from being added to an embedded collection. It’s important to note the workarounds don’t utilize a unique index, but rather use existing features to prevent duplicate data from being inserted.

One of the workarounds is described by Kyle Banker in the mongodb-user group. Kyle’s workaround specifies a detailed query to only update a document if it does not contain an embedded document value:

1
2
3
4

db.issues.update(
  { title: "Issue1", "tasks.title": { $ne: "Task1" } }, 
  { $push: { tasks: { title: "Task1" } } }
);

The previous update statement will only add a task with the title of “Task1” if the issue doesn’t contain one already. This approach is good for simple scenarios, but when you have multiple fields and potentially multiple levels of embedded documents, the condition becomes quite large.

Another workaround is to use the $addToSet modifier operation. This operation will add a value to an array only when the value doesn’t already exist. The following is an example of adding a task with the same title:

1

db.issues.update({ title: "Issue1" }, { $addToSet: { tasks: { title: "Task1" } } });

The previous statement will add the task to the issue if it doesn’t exist. You can also add many values in a single operation when using the $each qualifier:

1
2
3
4

db.issues.update(
  { title: "Issue1" }, 
  { $addToSet: { tasks: { $each: [{ title: "Task1" }, { title: "Task2" }] } } }
);

The two listed workarounds are targeted at adding unique embedded documents. Without single-document unique indexes, you are unable to enfore uniqueness during the update. This means we could rename the task with the title of “Task1” to “Task2” without causing an error. This is unexpected behavior.

Since the workarounds don’t utilize a unique index, an error is never thrown. This behavior could be beneficial to applications wanting to notify the user of inserting duplicated data. The workarounds are more of a “set it and forget it” update.

The following statements and comments are a summary of the current behavior and expected results:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

use bugs;

db.issues.ensureIndex({ title: 1 }, { unique: true });
db.issues.ensureIndex({ title: 1, "tasks.title": 1 }, { unique: true, sparse: true });

// insert our initial issue with a single task
db.issues.insert({ title: "Issue1", tasks: [ { title: "Task1" } ] });

// the following add or set a duplicate task, however, expected result would be 
// a unique index violation error
db.issues.update({ title: "Issue1" }, { $push: { tasks: { title: "Task1" } } });
db.issues.update({ title: "Issue1" }, { $pushAll: { tasks: [ { title: "Task1" } ] } });
db.issues.update({ title: "Issue1" }, { $set: { tasks: [ { title: "Task1" }, { title: "Task1" } ]} });

// the following do not allow a duplicate task to be added
db.issues.update({ title: "Issue1" }, { $addToSet: { tasks: { title: "Task1" } } });
db.issues.update({ title: "Issue1" }, { $addToSet: { tasks: { $each: [ { title: "Task1" }, { title: "Task1" } ] } } });

// this should throw a unique index violation error and not insert a new issue with duplicate tasks
db.issues.insert({ title: "Issue5", tasks: [ { title: "Task1" }, { title: "Task1" } ] });

Possible Solutions

I haven’t found any proposed solutions to allow unique indexes on embedded documents. After digging into this, I’ve come up with two:

Create a new index creation option for single document

This approach would allow a user to specify a new creation option in the ensureIndex method. You would be able to only apply this creation option on embedded field paths. An example would be:

1

db.issues.ensureIndex({ "tasks.title": 1 }, { docUnique: true });

The previous statement would add a unique index on a task title for each document. This would then throw a unique index violation error if you tried to add or update a task title to an existing title.

Allow a positional-like operator when defining the path of the index

This would allow a user to define the path to a field using a $ as an identifier representing embedded documents.

1

db.issues.ensureIndex({ "tasks.$.title": 1 }, { unique: true });

The previous statement would add the same type of index as the previous solution, but using a different notation.

Unique Arrays

One last thing to note, and it’s important; this article focuses only on embedded documents. However, the unique index applies more natively to arrays. This means that you can’t apply a unique index so an array can contain unique values. In the following example, you are allowed to have the same values in an array:

1
2
3
4
5

use foo;

db.bookmarks.ensureIndex({ tags: 1 }, { unique: true, sparse: true });
db.bookmarks.insert({ title: "Bookmark1", tags: ["tag1", "tag2", "tag3"] });
db.bookmarks.update({ title: "Bookmark1" }, { $push: { tags: "tag1" } });

The last statement will add “tag1” to the list of tags again. The expected result would be that tags are unique.

I hope I haven’t murdered this too badly. Comments are welcome!

For Mac, the most common browsers are Safari, Firefox, Opera and recently Chrome. On my machine, I have setup the following browsers and versions:

• Safari: 2.04, 3.04, 3.12, 3.21, 4.04
• Firefox: 2.0.0.20, 3.0.17, 3.5.7
• Opera: 9.52, 9.64, 10.01, 10.10
• Chrome: 4.0.249.49 (Latest)

Well, let’s get to it!

First, I setup a folder in my Applications called Browsers (/Applications/Browsers). I will explain later why we place all of our browsers in the Browsers folder. Now, let’s install each browser individually.

Safari

Since I’m running OS X 10.6 with latest updates, Safari version 4.04 is installed. So, in order to install previous versions, I use Multi Safari. Multi Safari provides different versions of Safari with the specified WebKit bundled into the application.

To install, you simply download the files, and extract to our /Applications/Browsers directory. All of the applications are named appropriately and ready to execute. To my knowledge, there isn’t any profile management we need to perform unlike Firefox and Opera.

Firefox

To get started, we need to download the specific versions. During the time of writing, 3.5.7 was the latest version. I was able to download easily from mozilla.com. Next we need to find archived versions. These are located on Mozilla’s FTP server. Once you’ve downloaded the versions you’re interested in, let’s start the installation process.

In order to run multiple instances of Firefox, I’ve found the best way is to create a different profile for each version use that profile when launching the browser. Since I’m only interested in 2.x, 3.0.x and 3.5.x, I like to start with the oldest version first. So, copy the Firefox application over to our /Applications/Browsers directory. Once installed, we need to immediately rename it. I renamed my to Firefox 2.

Next, let’s modify the script to launch Firefox and setup our profile. Open up Terminal and perform the following commands:

cd /Applications/Browsers/Firefox\ 2.app/Contents/MacOS
mv firefox-bin firefox.bin
echo '!#/bin/bash' > firefox-bin
echo '/Applications/Browsers/Firefox\ 2.app/Contents/MacOS/firefox.bin -P firefox2 -no-remote' >> firefox-bin
chmod +x firefox-bin

The previous commands essentially rename firefox-bin to firefox.bin and create a new bash script to execute firefox.bin with a specified profile and to tell Firefox that it’s OK to run more than one instance. You may be asking yourself, why is firefox-bin so important? Well, firefox-bin is the bundle executable (CFBundleExecutable) according to the Info.plist in Firefox 2.app. This means, when you load the application, it executes firefox-bin. You can look at other command line arguments here.

Now, before you run the application, let’s setup our “firefox2” profile. In the same directory, enter command: ./firefox.bin -ProfileManager. This will prompt you with the Firefox profile manager where you will want to create a new profile labeled “firefox2” (which is what we used as the -P argument in firefox-bin). Once you’ve created the profile, exit from the profile manager and try loading the application by double clicking on it through Finder.

These steps can be repeated for each specific version you want to install. Just keep in mind, the rule I follow is to create a new profile for each version being installed. So, for example, Firefox 3.5, I would create a “firefox35” profile and setup my firefox-bin to load it.

A few notes:

• If you installed OS X with the “Case-sensitive, Journaled” file system, multiple Firefox instances do not seem to work. If you find a work-around, please let me know, I had to re-install after having an unsuccessful attempt.
• I like to tell my different versions of Firefox to not update automatically. However, if you forget and it updates, you will simply need to follow the previous steps after the update has been applied.

Opera

I’ve provided a link to the Download for Mac OS X on Opera’s website. This link also contains another link to more archived versions.

The steps taken after downloading your versions are somewhat similar to how we handled Firefox. So, I will use the example of starting with the oldest version I’ve decided to install, 9.52. So, copy the Opera application over to our /Applications/Browsers directory. Once installed, we need to immediately rename it to Opera 9.52.

In order to keep individual profiles of Opera, you need to provide a PrefsSuffix file in the /Applications/Browsers/Opera 9.52.app/Content/Resources directory of the application. This file will tell Opera what suffix needs to be added to the preferences folder created in ~/Library/Preferences. Use the following command to set this up:

echo '9.52' > /Applications/Browsers/Opera\ 9.52.app/Contents/Resources/PrefsSuffix

That’s it! Now you can run the application and you will notice a folder is created in the ~/Library/Preferences/Opera Preferences 9.52. If you intend to install more versions, follow the same instructions that we just used.

Chrome

When writing this article, Google Chrome is in beta. I was able to download the latest version here. Since there’s only one version of Chrome for Mac OS X, I didn’t have to do any profile setup. However, I’m sure when Chrome 5 arrives, I’ll have to figure this out so I can run different versions of Chrome simultaneously.

Browsers Folder + Dock

Ok, all of our browsers are setup and ready to roll. However, remember earlier I said I would explain why we created the /Applications/Browsers folder? Well, because it provides a nice way to be able to load any browser from your dock. The attached screenshot is the Browsers folder dragged to my dock.

I hope this helps my fellow web developers in setting up your environment.

So go ahead and check out Reserved Word Search @ www.reservedwordsearch.com.

Please note, this approach is targeted for MySQL 5.0+.

The approach I take here is a combination of using the TIMESTAMP field data type and a TRIGGER.

IMPORTANT: When using multiple TIMESTAMP fields in a table, there can be only one TIMESTAMP column with CURRENT_TIMESTAMP in DEFAULT or ON UPDATE clause. This is why we need to use a TRIGGER to update one of the fields values.

In our case, we will set the date_modified field to contain the DEFAULT of CURRENT_TIMESTAMP and also set the ON UPDATE clause to CURRENT_TIMESTAMP.

1
2
3
4
5
6

CREATE TABLE `temp` (
  `field_value` VARCHAR(100) NOT NULL,
  `date_created` TIMESTAMP NULL DEFAULT NULL,
  `date_modified` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
)
ENGINE = InnoDB;

If you noticed in the CREATE TABLE snippet above we use the TIMESTAMP features on the date_modified field, but set our date_created field to NULL by default. We do this because our TRIGGER will populate the value before the insert.

1
2
3
4
5
6
7
8

DELIMITER //

CREATE TRIGGER temp_before_insert_created_date BEFORE INSERT ON `temp`
FOR EACH ROW
BEGIN
  SET NEW.date_created = CURRENT_TIMESTAMP;
END//
DELIMITER ;

In our trigger, we simply set the date_created value to the CURRENT_TIMESTAMP.

Now you will be able to insert and update rows in your table without having to specify the date_created or date_modified values.

1
2

INSERT INTO `temp` (field_value) VALUES ('testing');
UPDATE `temp` SET field_value = 'testing1';

Another approach that can be used is by setting the date_created value to NULL when inserting a row. This involves a different CREATE TABLE syntax.

1
2
3
4
5
6

CREATE TABLE `temp` (
  `field_value` VARCHAR(100) NOT NULL,
  `date_created` TIMESTAMP NOT NULL DEFAULT '0000-00-00 00:00:00',
  `date_modified` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
)
ENGINE = InnoDB;

Notice our date_created field is now set to NOT NULL with a default value of 0000-00-00 00:00:00. Here’s an important note from the documentation:

TIMESTAMP columns are NOT NULL by default, cannot contain NULL values, and assigning NULL assigns the current timestamp.

In other words, when we insert and set the value to NULL on a TIMESTAMP field, it will insert the current timestamp.

An example insert/update statement would look like:

1
2

INSERT INTO `temp` (field_value, date_created) VALUES ('testing', NULL);
UPDATE `temp` SET field_value = 'testing1';

This approach allows us to avoid using triggers, however requires you to specify the NULL value when the query is executed.

For more information, please check out GistDoIt! @ www.gistdoit.com.

Zend Framework already contains components like Zend_Locale and Zend_Translate to assist in internationalizing your website. You use the Zend_Locale instance in conjunction with the Zend_Translate to know what current locale is being used and how to translate the content. I’m going to show you how to implement these into your website.

If you haven’t read the first part of this series, I would recommend it as all my examples here will be based on that structure.

To start off, let’s talk about how we are going to allow our website to know what locale to use. What I’ve found to be a common practice to switch locales is based off of the URL. For example, a sample format may look like mysite.com/:locale/controller/action. Locales are usually represented with a language_REGION combination. However, locales in our case are specified by only the language code. You can find a list of language codes here. If you wanted your site to be in Japanese, you would use the language code of ja. An example of the URL might look something like mysite.com/ja/controller/action. On top of specifying the locale in the path of the URL, I’ve also provided a way to determine the locale based off of the TLD in the URL. For example, let’s say our mysite.com also has a Japanese TLD like mysite.jp. When a request comes in and we find a supported TLD, we set the localed based on it.

Enough talk, let’s look at some code.

Let’s start by setting up our Zend_Locale. In the application.ini, we use the Zend_Application_Resource_Locale to setup the locale component and set our default locale. In our case here, I’m setting the default locale to English.

application.ini:

...
# Locale
resources.locale.default = "en"
...

Next, we need to tell our application which locales are supported and also specify our TLD mappings. We do this by specifying front controller parameters in the application.ini.

application.ini:

...
# Front Controller Params
resources.frontController.params.locales[] = "en"
resources.frontController.params.locales[] = "ja"
resources.frontController.params.tldLocales.jp = "ja"
...

If you notice from the configuration above, I’ve added English and Japanese as my supported locales and I also mapped the jp TLD to use the ja language code. More on how we use those later.

Before I show the rest of the configuration needed, let me explain how the process works.

In order for your application to recognize when a locale is specified in the URL, you need to create special routes to parse out the locale. The approach I took was to override the existing Zend_Application_Resource_Router and implement the ability to automatically add locale routes to the application when enabled.

The process in which I added routes to my application was done previously in my Bootstrap.php with the _initRoutes() method. I’ve removed that code and moved the routes to be configured in the application.ini. Now that the routes are specified in the application.ini, it allows us to easily add/edit/remove routes from our application. There is also a benefit to doing this in regards to caching, which I will explain in a future article.

First, let’s take a look at how we will load the custom router application resource and override the existing application resource.

application.ini

...
# Custom Resource Plugins
pluginPaths.My_Application_Resource = APPLICATION_PATH "/../lib/My/Application/Resource/"
...

Now the application is setup to load custom application resources for the namespace specified. Since I am overriding the Zend_Application_Resource_Router, let’s look at My_Application_Resource_Router:

My/Application/Resource/Router.php:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

<?php
class My_Application_Resource_Router extends Zend_Application_Resource_Router
{
    public $_explicitType = 'router';

    protected $_front;
    protected $_locale;

    /**
     * Retrieve router object
     *
     * @return Zend_Controller_Router_Rewrite
     */
    public function getRouter()
    {
        $options = $this->getOptions();

        if (!isset($options['locale']['enabled']) ||
            !$options['locale']['enabled']) {
            return parent::getRouter();
        }

        $bootstrap = $this->getBootstrap();

        if (!$this->_front) {
            $bootstrap->bootstrap('FrontController');
            $this->_front = $bootstrap->getContainer()->frontcontroller;
        }

        if (!$this->_locale) {
            $bootstrap->bootstrap('Locale');
            $this->_locale = $bootstrap->getContainer()->locale;
        }

        $defaultLocale = array_keys($this->_locale->getDefault());
        $defaultLocale = $defaultLocale[0];

        $locales = $this->_front->getParam('locales');
        $requiredLocalesRegex = '^(' . join('|', $locales) . ')$';

        $routes = $options['routes'];
        foreach ($routes as $key => $value) {
            // First let's add the default locale to this routes defaults.
            $defaults = isset($value['defaults'])
                ? $value['defaults']
                : array();

            // Always default all routes to the Zend_Locale default
            $value['defaults'] = array_merge(array( 'locale' => $defaultLocale ), $defaults);

            $routes[$key] = $value;

            // Get our route and make sure to remove the first forward slash
            // since it's not needed.
            $routeString = $value['route'];
            $routeString = ltrim($routeString, '/\\');

            // Modify our normal route to have the locale parameter.
            if (!isset($value['type']) ||
                $value['type'] === 'Zend_Controller_Router_Route') {
                $value['route'] = ':locale/' . $routeString;

                $value['reqs']['locale'] = $requiredLocalesRegex;

                $routes['locale_' . $key] = $value;
            } else if ($value['type'] === 'Zend_Controller_Router_Route_Regex') {
                $value['route'] = '(' . join('|', $locales) . ')\/' . $routeString;

                // Since we added the local regex match, we need to bump the existing
                // match numbers plus one.
                $map = isset($value['map']) ? $value['map'] : array();
                foreach ($map as $index => $word) {
                    unset($map[$index++]);
                    $map[$index] = $word;
                }

                // Add our locale map
                $map[1] = 'locale';
                ksort($map);

                $value['map'] = $map;

                $routes['locale_' . $key] = $value;
            } else if ($value['type'] === 'Zend_Controller_Router_Route_Static') {
                foreach ($locales as $locale) {
                    $value['route'] = $locale . '/' . $routeString;
                    $value['defaults']['locale'] = $locale;
                    $routes['locale_' . $locale . '_' . $key] = $value;
                }
            }
        }

        $options['routes'] = $routes;
        $this->setOptions($options);

        return parent::getRouter();
    }
}

In order for this custom application resource to override the existing one, the key is public $_explicitType = 'router';. Now when routes are setup in the application.ini for the router resource it won’t use the Zend_Application_Resource_Router, but rather My_Application_Resource_Router.

This application resource sets up the Zend_Controller_Router_Rewrite by parsing the specified options parsed from the application.ini. Notice this custom application resource extends from the original Zend_Application_Resource_Router which allows us to have the application resource perform the default actions if the locale option is not enabled in the configuration. By default, the custom router application resource will perform the default actions to the routes. You need to explicitly specify in the application.ini that the router is locale aware.

My_Application_Resource_Router simply takes in the specified routes from the application.ini and adds locale routes automatically so you don’t have to chain/duplicate routes in the configuration.

Let’s look at our application.ini to see how we are setting up the router to be locale aware and adding a route.

application.ini:

...
# Router/Routes
resources.router.locale.enabled = true
resources.router.routes.action_index.route = ":action/*"
resources.router.routes.action_index.defaults.controller = "index"
resources.router.routes.action_index.defaults.action = "index"
...

In the previous configuration snippet, we enable our router application resource to be locale aware and add a basic Zend_Controller_Router_Route which is the same as specified previously in our Bootstrap.php. When the router application resource is finished adding the routes to the router, there will be two:

1. :action/*
2. :locale/:action/*

Currently the My_Application_Resource_Router supports Zend_Controller_Router_Route, Zend_Controller_Router_Route_Regex and Zend_Controller_Router_Static routes. When these routes are specified and the router application resource is locale aware, it will automatically create routes for the supported locales.

We’ve covered a lot already, but there are still a few more steps involved. We are almost finished, I promise!

At this point, we have specified our default and supported locales and setup our routes using our custom router application resource. Now we need to do one more thing and that is to determine which locale to load and create our Zend_Translate instance.

In order for us to determine which locale, if any, has been specified in the request, we use a controller plugin to parse the request and set the correct locale and setup our translation component.

First, we need to enable the controller plugin in our application.ini.

application.ini:

...
# Front Controller Plugins
resources.frontController.plugins.I18n = "My_Controller_Plugin_I18n"
...

Next, let’s look at the controller plugin source:

My/Controller/Plugin/I18n.php:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

<?php
class My_Controller_Plugin_I18n extends Zend_Controller_Plugin_Abstract
{
    /**
    * Sets the application locale and translation based on the locale param, if
    * one is not provided it defaults to english
    *
    * @param Zend_Controller_Request_Abstract $request
    */
    public function routeShutdown(Zend_Controller_Request_Abstract $request)
    {
        $frontController = Zend_Controller_Front::getInstance();
        $params = $request->getParams();
        $registry = Zend_Registry::getInstance();

        // Steps setting the locale.
        // 1. Defaults to English (Done in config)
        // 2. TLD in host header
        // 3. Locale params specified in request
        $locale = $registry->get('Zend_Locale');

        // Check host header TLD.
        $tld = preg_replace('/^.*\./', '', $request->getHeader('Host'));

        // Provide a list of tld's and their corresponding default languages
        $tldLocales = $frontController->getParam('tldLocales');

        if (array_key_exists($tld, $tldLocales)) {
            // The TLD in the request matches one of our specified TLD -> Locales
            $locale->setLocale($tldLocales[$tld]);
        } else if (isset($params['locale'])) {
            // There is a locale specified in the request params.
            $locale->setLocale($params['locale']);
        }

        // Now that our locale is set, let's check which language has been selected
        // and try to load a translation file for it. If the language is the default,
        // then we do not need to load a translation.
        $language = $locale->getLanguage();
        if ($language !== $locale->getDefault()) {
            $i18nFile = APPLICATION_PATH . '/data/i18n/source-' . $language . '.mo';
            try {
                $translate =
                    new Zend_Translate('gettext', $i18nFile, $locale, array('disableNotices' => true));

                Zend_Registry::set('Zend_Translate', $translate);
                Zend_Form::setDefaultTranslator($translate);
            } catch (Zend_Translate_Exception $e) {
                // Since there was an error when trying to load the translation catalog,
                // let's not load a translation object which essentially defaults to
                // locale default.
            }
        }

        // Now that we have our locale setup, let's check to see if we are loading
        // a language that is not the default, and update our base URL on the front
        // controller to the specified language.
        $defaultLanguage = array_keys($locale->getDefault());
        $defaultLanguage = $defaultLanguage[0];

        $path = '/' . ltrim($request->getPathInfo(), '/\\');

        // If the language is in the path, then we will want to set the baseUrl
        // to the specified language.
        if (preg_match('/^\/' . $language . '\/?/', $path)) {
            $frontController->setBaseUrl($frontController->getBaseUrl() . '/' . $language);
        }

        setcookie('Zend_Locale', $language, null, '/', $request->getHttpHost());
    }
}

To start, notice this plugin listens on the routeShutdown() method. We use this because our request has gone through our router and the request is now setup and ready to be processed. In the routeShutdown() method, we first load our Zend_Locale instance from the registry where it was set up in our application.ini. Next, we need to determine which locale, if any, needs to be set. By default, we’ve set our locale to use English (en) in our application.ini. We will parse out the TLD from the host and see if it maps to one of our specified TLD locales. If that doesn’t exist, then we will look in the request to see if the locale param was set. If both of the checks can’t find a specified locale, we then simply use the default.

Since our locale is now setup, we need to load a translation file. In my example provided, I use gettext translation files. I place these files in the app/data/i18n folder. The file naming scheme looks like source-{locale}.mo. Another example would be if we had a Japanese translation file, it would look something like source-ja.mo. The plugin will try to load the translation file based on the locale language specified and add it to our Zend_Registry and tell our Zend_Form it’s default translator.

Finally, our plugin uses the specified locale language to determine if we need to update our base URL in the front controller. We want to set the base URL to the specified locale which allows other components like Zend_Navigation to persist the locale in the links produced.

There you have it! You’re site is now internationalized and ready for it’s content to be translated.

But wait, that’s not all! I’ve also provided a view helper which produces a locale switcher. This view helper simply creates elements that contain images of the specified locale and shows the enabled/disabled locale while allowing you to click on the image and switch the current locale.

app/views/helpers/LocaleSwitcher.php:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

<?php
class Default_View_Helper_LocaleSwitcher extends Zend_View_Helper_Abstract
{
    public function localeSwitcher()
    {
        $output = array();
        $frontController = Zend_Controller_Front::getInstance();

        $locales = $frontController->getParam('locales');
        $request = $frontController->getRequest();
        $baseUrl = $request->getBaseUrl();
        $path = '/' . trim($request->getPathInfo(), '/\\');

        if (count($locales) > 0) {
            $locale = Zend_Registry::get('Zend_Locale');
            $localeLanguage = $locale->getLanguage();
            $defaultLocaleLanguage = array_keys($locale->getDefault());
            $defaultLocaleLanguage = $defaultLocaleLanguage[0];

            array_push($output, '<ul id="locale_switcher">');

            foreach ($locales as $language) {
                $imageSrc  = 'img/i18n_';
                $imageSrc .= $language . '_' . ($localeLanguage == $language ? 'on' : 'off');
                $imageSrc .= '.gif';

                $urlLanguage = $defaultLocaleLanguage == $language
                    ? ''
                    : '/' . $language;

                if (strlen($baseUrl) === 0) {
                    $localeUrl = $urlLanguage . $path;
                } else {
                    $localeUrl = preg_replace('/^' . preg_quote($baseUrl, '/') . '\/?/',
                        $urlLanguage . '/', $path);
                }

                array_push($output, '<li>');
                array_push($output, '<a href="' . $localeUrl . '">');
                array_push($output, '<img src="' . $this->view->assetUrl($imageSrc) . '" alt="' . $language . '" />');
                array_push($output, '</a>');
                array_push($output, '</li>');
            }

            array_push($output, '</ul>');
        }

        return join('', $output);
    }
}

I’ve included an updated Zend Framework Best Practices zip file which contains all of the files/directory structure we’ve discussed so far in the series.

The original gist of this process can be found here: http://gist.github.com/189194.

That’s it for now. Until next time!

This series will cover many areas of a website including directory structure, bootstrapping, caching, navigation, ACL & authorization and I18N.

Disclaimer: I don’t want this series to be taken as the “only way” to use Zend Framework in your application. In fact, it would be greatly appreciated if others are able to point out areas where my approach is not the most efficient and provide ways to fix it.

Ok, let’s start…

I would first like to discuss the directory structure of a Zend Framework application. This is always a hot topic in #zftalk. There are two documents out on the ZF wiki which discuss a directory structure to choose. First, there was Choosing Your Application’s Directory Layout which has now been deprecated by Zend Framework Default Project Structure by Wil Sinclair. The latter of the two is very close to what was adopted by Zend_Tool.

This is really a personal preference, but I wanted to share my directory structure. It is very similar to latest proposed version, only I use the more “classical (unix/linux)” style.

Here’s an example of my initial directory structure and basic files needed:

project/
    app/
        configs/
            application.ini
        controllers/
            helpers/
            ErrorController.php
            IndexController.php
        data/
            cache/
            i18n/
            sessions/
        forms/
        layouts/
            scripts/
                layout.phtml
        models/
        views/
            helpers/
                AssetUrl.php
            scripts/
                error/
                    error.phtml
                index/
                    index.phtml
        Bootstrap.php
    lib/
        My/
            Application.php
        Zend/
    www/
        css/
            reset.css
        img/
        js/
        .htaccess
        index.

Now that you can visually see the directory structure, let’s go through setting up our application.

The .htaccess file is used with Apache and mod_rewrite to either load the file requested or pass the request to the index.php file.

.htaccess:

SetEnv APPLICATION_ENV development
 
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} \.(js|css|gif|jpg|png|swf)$ [OR]
RewriteCond %{REQUEST_FILENAME} -s [OR]
RewriteCond %{REQUEST_FILENAME} -l [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^.*$ - [NC,L]
RewriteRule ^.*$ index.php [NC,L]

If you notice on the first line, we set an environment variable, APPLICATION_ENV, to the value of development. This is used in the index.php to tell our bootstrap what environment we should setup for. The value can be any environment name, however, you need to make sure you configuration recognizes it. Some standard names are development, staging, beta and production. Please note though, on shared hosting plans, the SetEnv directive will probably not work since mod_env won’t be installed. If this is the case, then you will need to set the environment in the index.php file.

Our rewrite conditions simply say, if the request isn’t an asset and/or found on the file system, then redirect the request to our index.php.

The index.php file is used to initialize our application and setup the environment.

index.php:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

<?php
    // Define path to application directory
    if (!defined('APPLICATION_PATH'))
        define('APPLICATION_PATH', realpath(dirname(__FILE__) . '/../app'));

    // Define application environment
    if (!defined('APPLICATION_ENV'))
        define('APPLICATION_ENV',
            (getenv('APPLICATION_ENV') ? getenv('APPLICATION_ENV') : 'production'));

    // Add our lib folder to the include paths
    set_include_path(implode(PATH_SEPARATOR, array(
            realpath(APPLICATION_PATH . '/../lib'),
            get_include_path()
    )));

    /** My_Application */
    require_once 'My/Application.php';

    // Create application, bootstrap, and run
    $application = new My_Application(
        APPLICATION_ENV,
        array(
            'configFile' => APPLICATION_PATH . '/configs/application.ini'
        )
    );
    $application->bootstrap()->run();

Our index.php does a few things before we bootstrap our application. First, you will notice it defines a constant for our application path. Then, it does the same thing for our application environment constant. Please note, that if the SetEnv does not work or the APPLICATION_ENV isn’t defined, then it will default to production. You can change that value to whatever environment you’d like to default to.

Once our constants are setup, we then add our lib directory to the include path.

Now it’s time to bootstrap our application. If you notice, we are using a custom class called My_Application which extends Zend_Application. This class is used to bootstrap our application while caching our application.ini configuration. We cache our configuration because parsing an INI file is very slow in PHP. This allows us to cache the already parsed INI as a Zend_Config object.

My/Application.php

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

<?php
    require_once 'Zend/Application.php';
    class My_Application extends Zend_Application
    {
        /**
         * Flag used when determining if we should cache our configuration.
         */
        protected $_cacheConfig = false;

        /**
         * Our default options which will use File caching
         */
        protected $_cacheOptions = array(
            'frontendType' => 'File',
            'backendType' => 'File',
            'frontendOptions' => array(),
            'backendOptions' => array()
        );

        /**
         * Constructor
         *
         * Initialize application. Potentially initializes include_paths, PHP
         * settings, and bootstrap class.
         *
         * When $options is an array with a key of configFile, this will tell the
         * class to cache the configuration using the default options or cacheOptions
         * passed in.
         *
         * @param  string                   $environment
         * @param  string|array|Zend_Config $options String path to configuration file, or array/Zend_Config of configuration options
         * @throws Zend_Application_Exception When invalid options are provided
         * @return void
         */
        public function __construct($environment, $options = null)
        {
            if (is_array($options) && isset($options['configFile'])) {
                $this->_cacheConfig = true;

                // First, let's check to see if there are any cache options
                if (isset($options['cacheOptions']))
                    $this->_cacheOptions =
                        array_merge($this->_cacheOptions, $options['cacheOptions']);

                $options = $options['configFile'];
            }
            parent::__construct($environment, $options);
        }

        /**
         * Load configuration file of options.
         *
         * Optionally will cache the configuration.
         *
         * @param  string $file
         * @throws Zend_Application_Exception When invalid configuration file is provided
         * @return array
         */
        protected function _loadConfig($file)
        {
            if (!$this->_cacheConfig)
                return parent::_loadConfig($file);

            require_once 'Zend/Cache.php';
            $cache = Zend_Cache::factory(
                $this->_cacheOptions['frontendType'],
                $this->_cacheOptions['backendType'],
                array_merge(array( // Frontend Default Options
                    'master_file' => $file,
                    'automatic_serialization' => true
                ), $this->_cacheOptions['frontendOptions']),
                array_merge(array( // Backend Default Options
                    'cache_dir' => APPLICATION_PATH . '/data/cache'
                ), $this->_cacheOptions['backendOptions'])
            );

            $config = $cache->load('Zend_Application_Config');
            if (!$config) {
                $config = parent::_loadConfig($file);
                $cache->save($config, 'Zend_Application_Config');
            }

            return $config;
        }
    }

application.ini:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

[production]

# Debug output
phpSettings.display_startup_errors = 0
phpSettings.display_errors = 0

# PHP Date Settings
phpSettings.date.timezone = "UTC"

# Include path
includePaths.library = APPLICATION_PATH "/../lib"

# Autoloader Namespaces
autoloaderNamespaces[] = "My_"

# Bootstrap
bootstrap.path = APPLICATION_PATH "/Bootstrap.php"
bootstrap.class = "Bootstrap"

# Front Controller
resources.frontController.controllerDirectory = APPLICATION_PATH "/controllers"

# Front Controller Params
resources.frontController.params.env = APPLICATION_ENV
resources.frontController.params.cdnEnabled = "true"
resources.frontController.params.cdnHost = "http://static.site.com"

# Layout
resources.layout.layout = "layout"
resources.layout.layoutPath = APPLICATION_PATH "/layouts/scripts"

# Views
resources.view.encoding = "UTF-8"
resources.view.basePath = APPLICATION_PATH "/views/scripts"

# Database
resources.db.adapter = "mysqli"
resources.db.params.host = "localhost"
resources.db.params.username = "user"
resources.db.params.password = "password"
resources.db.params.dbname = "dbname"
resources.db.isDefaultTableAdapter = true

# Session
resources.session.save_path = APPLICATION_PATH "/data/sessions"
resources.session.gc_maxlifetime = 18000
resources.session.remember_me_seconds = 18000

# Navigation
resources.navigation.storage.registry.key = "Zend_Navigation"
resources.navigation.pages.welcome.label = "Welcome"
resources.navigation.pages.welcome.uri = "/"

[development : production]

# Debug output
phpSettings.display_startup_errors = 1
phpSettings.display_errors = 1

# Front Controller Params
resources.frontController.params.cdnEnabled = "false"

# Database
resources.db.params.dbname = "dbname"

A couple of notes about the configuration file:

• Automatically set dates to UTC
• Automatically load classes that start with My_ from our lib directory
• Pass our environment to the front controller parameters
• Set our sessions to expire after 4 hours (when used)
• Automatically store our navigation in the registry with key Zend_Navigation
• The resources.frontController.params.cdnEnabled setting will be explained in greater detail when I discuss caching and CDN fronting your assets

Since our application configuration has been loaded and cached, it’s time to run our bootstrap.

Our Bootstrap.php extends from the Zend_Application_Bootstrap_Bootstrap class. Whenever you want to initialize resources, you need to create a protected function in our bootstrap prefixed like protected function _init{Resource}() { ... }.

Bootstrap.php:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

<?php
    class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
    {
        /**
         * Automatically load classes that are part of the default module.
         */
        protected function _initModuleAutoloader()
        {
            new Zend_Application_Module_Autoloader(array(
                'namespace' => 'Default',
                'basePath' => APPLICATION_PATH
            ));
        }

        /**
         * Initialize our routes.
         */
        protected function _initRoutes()
        {
            $this->bootstrap('frontcontroller');
            $front = $this->getResource('frontcontroller');

            $router = $front->getRouter();
            $router->addRoute('index-action', new Zend_Controller_Router_Route(
                ':action/*',
                array(
                    'controller' => 'index',
                    'action' => 'index'
                )
            ));

            return $router;
        }

        /**
         * Get our database adapter and add it to our registry for easy access
         * throughout the application.
         */
        protected function _initDbAdapter()
        {
            $this->bootstrap('db');
            $db = $this->getPluginResource('db');

            Zend_Registry::set('db', $db->getDbAdapter());
        }

        /**
         * Initialize our view and add it to the ViewRenderer action helper.
         */
        protected function _initView()
        {
            // Initialize view
            $view = new Zend_View();

            // Add it to the ViewRenderer
            $viewRenderer =
                Zend_Controller_Action_HelperBroker::getStaticHelper('ViewRenderer');
            $viewRenderer->setView($view);

            // Return it, so that it can be stored by the bootstrap
            return $view;
        }

        /**
         * Here we will initialize any view helpers.    This will also setup basic
         * head information for the view/layout.
         */
        protected function _initViewHelpers()
        {
            $this->bootstrap(array('frontcontroller', 'view'));
            $frontController = $this->getResource('frontcontroller');
            $view = $this->getResource('view');

            // Add helper paths.
            $view->addHelperPath(APPLICATION_PATH . '/views/helpers', 'Default_View_Helper');

            // Setup our AssetUrl View Helper
            if ((bool) $frontController->getParam('cdnEnabled'))
                $view->getHelper('AssetUrl')->setBaseUrl($frontController->getParam('cdnHost'));

            // Set our DOCTYPE
            $view->doctype('XHTML1_STRICT');

            // Set our TITLE
            $view->headTitle()->setSeparator(' - ')->append('Site');

            // Add any META elements
            $view->headMeta()->appendHttpEquiv('Content-Type', 'text/html; charset=UTF-8');
            $view->headMeta()->appendHttpEquiv('Content-Style-Type', 'text/css');
            $view->headMeta()->appendHttpEquiv('imagetoolbar', 'no');

            // Add our favicon
            $view->headLink()->headLink(array(
                'rel' => 'favicon',
                'type' => 'image/ico',
                'href' => $view->baseUrl('favicon.ico')
            ));

            // Add Stylesheet's
            $view->headLink()
                ->appendStylesheet($view->assetUrl('css/reset.css'));

            // Add JavaScript's
            $view->headScript()
                ->appendFile('http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js');
        }
    }

A few things to take note in our Bootstrap.php:

• We setup a default route that allows the user to load an action like IndexController:testAction() through the URL like mysite.com/test. This allows us to not have to prefix the action with the controller like mysite.com/index/test. However, since the default route is there, that would still work and any other :controller/:action routes
• We store our DB adapter in the registry so we can access it throughout our application
• When we initialize our view helpers, we add the views/helpers directory to our helper path(s) and we setup some head information for our view/layout
• The AssetUrl view helper will be explained in greater detail when I discuss caching & CDN fronting your assets

Now we are at a point where our application has been setup and is ready to process the request.

We’ve covered a lot so far. There are a few things I didn’t talk about, for example, how the ErrorController.php and error.phtml look, AssetUrl.php, or what the layout.phtml looks like. However, I have included a Zend Framework Best Practices - Base Directory Structure/Files zip file containing the file structure and base files I’ve discussed here.

Update: I found two issues with the application.ini and AssetUrl.php files. They are now fixed and the post reflects the changes.

To back my comment, take a look at the jQuery plugins repository. It is chock-full of useful plugins that use the jQuery framework. Granted, there are a good amount of plugins for the Prototype framework, but where’s the wiki/community site for them? Or is there a site, but I just have not come across it yet?

Here’s a great start to a few of the notable plugins for Prototype that I’ve found are:

script.aculo.us - The most famous plugin/add-on using the Prototype framework. This adds animation, drag & drop, AJAX controls, DOM utilities and unit testing

Prototype Window Class (PWC) - A great class that allows you to add floating/modal skinnable windows to your page.

TableKit (Dexagogo) - Dexagogo provides many scripts based on the Prototype framework. The most notable is the TableKit. This provides an easy way to add sorting, column resizing, row striping and inline cell editing.

LivePipe Projects - Ryan Johnson also has a few scripts that use the Prototype framework. His Control Suite and Prototype.Tidbits are great add-ons and definitely worth looking into.

LightWindow 2.0 - I am really impressed with this plugin. This is the cats meow when it comes to any type of lightbox. I really like the Flash Paper example.

When it comes down to it, maybe I shouldn’t be basing the community involvement by just a plugins repository, but jQuery’s repository shows me how many different people are writing plugins and how often. It’s provides me a central location to possibly come up with new ideas for plugins or just a way for me to find something so I don’t have to recreate the wheel.

I’ve also noticed more and more articles being published on “How to do X with jQuery”. I try to keep up with my blogroll and feeds as much as I can, and I see an overabundance of jQuery focused articles.

Am I the only one who notices this? Please, let me know if I am wrong with this observation.

Update: John Resig (creator of jQuery) posted a great article on the jQuery and open source community today.