ysfDimensionsPlugin - 1.0.1

Dimensions for symfony

You are currently browsing
the website for symfony 1

Visit the Symfony2 website


« Back to the Plugins Home

Signin


Forgot your password?
Create an account

Tools

Stats

advanced search
Information Readme Releases Changelog Contribute
Show source | Show as Markdown

ysfDimensionsPlugin

ysfDimensionsPlugin allows you to customize the behavior of your symfony application based on any runtim factors. You can adjust the configuration, template selection, and action behavior based on a combination of dimensions chosen by you. For instance, you can have a different navigation structure based on the country of the user or a cobrand, or a different logo URL based on the current skin. These factors that affect the behavior (in this case, the country of the user and the skin selected) are the dimensions, and you may define as many as you wish.

Dimensions work by adding another level of cascading configuration, as well as by altering the location of the template or altering the name of the action class. All of this is made easy due to the forward thinking flexibility of symfony.

Installation

This is not a standard plugin and installation should not be automated since core files are altered. You must manually install this plugin by following these easy steps:

1. Download the plugin via subversion

This plugin can be downloaded and installed into the plugins directory of your project.

cd path/to/your/project/plugins/
svn export http://svn.symfony-project.org/plugins/ysfDimensionsPlugin

2. Backup Files

The most important part of installing this plugin is backing up your original installation. First find out where symfony is installed (in pear or in your project) and then backup the following files:

cp /your/path/to/symfony/lib/config/sfLoader.class.php /your/path/to/symfony/lib/config/sfLoader.class.php.original
cp /your/path/to/symfony/data/config/constants.php /your/path/to/symfony/data/config/constants.php.original

3. Override Files

Now you can safely replace the core symfony files:

cp /path/to/your/project/plugins/ysfDimensionsPlugin/lib/config/sfLoader.class.php /your/path/to/symfony/lib/config/sfLoader.class.php
cp /path/to/your/project/plugins/ysfDimensionsPlugin/config/constants.php /your/path/to/symfony/data/config/constants.php

Configuration

Now that the sfDimensions hooks are in place, you need to configure your application, by following the steps below:

1. Defining Available Dimensions

First we need to define the different dimensions a page may have and define all available values for each dimension in project/config/dimensions.yml:

dimensions:
    culture:          [fr, it, de](en,)
    theme:            [corporate](classic,)

2. Setting the Current Dimension

Next, you need to edit your project's config.php and add the following changes below the $sf_data_dir/$sf_lib_dir definitions:

/**
 *
 * Logic for determining dimensions
 *
 * Remember this file is called very early on in the symfony bootstrap process
 * so there are no symfony utilities available,
 *
 */

// For now static values
$culture = if(!empty($_REQUEST[? $_REQUEST['culture']('culture']))) : 'en';
$theme = if(!empty($_REQUEST[? $_REQUEST['theme']('theme']))) : 'classic';

// define dimensions
$dimension = array('culture' => $culture, 'theme' => $theme);

// no autoloading available this early in bootstrap, so require absolutely
require_once(dirname(__FILE__).DIRECTORY_SEPARATOR.'..'.DIRECTORY_SEPARATOR.'plugins'.DIRECTORY_SEPARATOR.'ysfDimensionsPlugin'.DIRECTORY_SEPARATOR.'lib'.DIRECTORY_SEPARATOR.'config'.DIRECTORY_SEPARATOR.'sfDimensions.class.php');

// set dimensions
sfDimensions::setDimension($dimension);

For now we're just setting the theme and culture based on a request parameter. You will likely not want to base the dimension off raw user input, but of something else, like the host name or stored user preferences.

Examples

So what's really going on here? We need to vary the site behavior based upon various parameters. Above, we're using the culture of the request as the parameter, but we can use other settings like theme or colo as parameters as well. We can then specify several aspects of the symfony experience by means of these dimensions. For instance, we can specify different site logos depending on the theme, or different servers depending on the culture, or different page content based on the culture (for example, language translations of a page). We can also inherit functionality between settings, so if culture => fr is almost the same as the generic configuration, it can inherit the settings and just specify the changes it needs. We will go more into how this works later, first lets explain the dimension configuration.

dimensions:
    culture:          [fr, it, de](en,)
    theme:            [corporate](classic,)

Our dimensions.yml file describes two levels of dimensions. The first named 'culture' that has four possible values: 'en, fr, it, de', and a second dimension named 'theme' that has two possible values 'classic' and 'corporate'.

Any request can be for any combination of the dimensions culture and theme. Here we have configured eight posssible unique dimensions (en_classic, en_corporate, fr_classic, fr_corporate, it_classic, it_corporate, de_classic, de_corporate). Dimensions function by looking in special directories for configuration or template files. For example, if the current dimension was set as culture => en, theme => classic, then symfony would form the dimension string 'en_classic'. When symfony looks for a configuration or template file it will insert a new order of precedence: first it will load files from 'en_corporate', then 'corporate', and then 'us'. Regardless of the dimension all of these will look in the generic (non dimension-specific) location for settings last. This means that if you don't want to specialize your behavior at all, you can put settings in the same locations in symfony as you did before using the ysfDimensionsPlugin.

There are three parts of the system that are configured by these settings: configuration, templates, and actions. All dimensions-specific files live underneath a dimension-specific directory. For app-level configuration, the directory is in apps//modules/templates//. For module-level configuration, it's in apps//modules//[actions, config, templates, validate]//

Let's talk a little about each of these.

Configuration

symfony makes great use of configuration files to set up your web site. These files live in various config/ directories. The settings largely end up in the sfConfig object where you can fetch them from your application.

We handle the settings.yml, app.yml, module.yml, view.yml, security.yml, mailer.yml, cache.yml, i18n.yml, and validate/*.yml as well.

You should put the dimension-specific files in a dimension-specific subdirectory. For instance, we would put the 'app.yml' for the dimension 'culture => en, theme => corporate' in apps/myapp/config/en_corporate/app.yml, and module.yml in apps/myapp/modules/mymodule/config/en_corporate/module.yml.

As with all of these settings, configurations are searched for in the order specified by the original dimensions.yml file. Any setting not specified in one file will cause us to look in the subsequent files down the list. The order is determined by applying a cartesian iteration, thus culture => en, theme => corporate ends up as a dimension 'en_corporate'. The search order will be from most specific to generic: 'en_corporate', 'corporate', 'en', generic. If multiple configuration files are found in multiple paths, they will be merged with the most specific values having precedence.

Let's try this. Let's create a setting 'site' that we'll echo for a new 'test' action. Put this into apps/myapp/modules/mymodule/templates/testSuccess.php (the generic location):

<h1>mymodule:test</h1>
<p>We are in the test template now.  Site setting is <?php echo $site ?>.</p>

Now add the action:

apps/myapp/modules/mymodule/actions/actions.class.php

<?php
class mymoduleActions extends sfAction
{
  public function executeTest()
  {
    $this->site = sfConfig::get('app_site');
  }
}
?>

Now we just need to establish the setting itself. This is an app-level setting (app_) so it belongs in the app.yml file. Let's create a base value. Create apps/myapp/config/app.yml:

all:
  site: base

Now clear the cache (for now you'll need to do this whenever you add new action code) and load the page at http://example.com/mymodule/test (change the hostname for your box). You'll see the base setting. Now hit http://example.com/mymodule/test?culture=fr. The setting is still base even though you're in the fr culture. Let's make a fr-specific setting. Create apps/myapp/config/fr/app.yml:

all:
  site: fr

Now clear your configuration cache (symfony cc) and reload the last page. What about a theme? Try this URL: http://example.com/mymodule/test?culture=fr&theme=corporate. It still says fr because the fr_corporate site inherits the fr settings. Let's override this value again. Create apps/myapp/config/fr_corporate/app.yml:

all:
  site: fr_corporate

Clear the cache, and reload. There you go. If you go back to the previous URLs pages you'll see that they each show the appropriate value, overriding the base where necessary.

Here are the configuration files that are specialized to handle dimension-specific configuration.

The application configuration files that can be overridden are:

app.yml
factories.yml
filters.yml
settings.yml
cache.yml
security.yml
view.yml

The module level configuration files that can be overridden are:

cache.yml
module.yml
security.yml
view.yml

For each one, symfony will load all of the dimension-specific configuration files given the specialization path specified by dimensions.yml (e.g. en_corporate, corporate, en, generic) with the earlier files' settings overriding the later ones. Otherwise, the configurations work just as they did before the dimension-specific specialization. See the symfony book for more information about these files.

Templates

Dimension-specific templates are placed in the templates// directory. They are searched for in the order specified by the dimensions.yml file, and the first found of the appropriate name is used.

Let's add some dimension-specific templates for our new action. apps/myapp/modules/mymodule/templates/fr/testSuccess.php:

<h1>mymodule:test for fr</h1>
<p>We are in the test/france template now.  Site setting is <?php echo $site ?>.</p>

apps/myapp/modules/mymodule/templates/fr_corporate/templates/testSuccess.php:

<h1>mymodule:test for fr/corporate</h1>
<p>We are in the test/france/corporate template now.  Site setting is <?php echo $site ?>.</p>

Now try the URLs from above, for base, fr, and fr_corporate settings. You should see all three templates, each showing the setting from the previous section as well.

Actions (not yet implemented)

Dimension-specific actions are placed in the actions// directory. Since actions are specified in classes and classes need to have unique names, you need to append the standard class names with the dimension. So mymoduleActions for the en_corporate configuration would be mymoduleActions_en_corporate. This class would go in the actions/en_corporate/actions.class.php file. The same is true for individual action classes as well. fooAction_en_corporate class would go in the actions/en_corporate/actions/fooAction.class.php file. Actions can inherit functionality from other actions and don't need to 'require' them. You could have mymoduleActions_en_corporate extends mymoduleActions if you want to share some behavior between all sites but override a specific action for 'en_corporate' dimension.

For example, let's just override the action for the all sites with the dimension 'fr_corporate'.

apps/myapp/modules/mymodule/actions/fr_corporate/actions.class.php:

<?php
class mymoduleActions_fr_corporate extends mymoduleActions
{
  public function executeTest()
  {
    parent::executeTest();
    $this->site = 'override('.$this->site.')';
  }
}
?>

You'll need to clear the cache. Now reload the 'fr_corporate' url from above and you will see that we've overridden the site value on this page, while inheriting the behavior of the base action.

Performance

Installing the ysfDimensionsPlugin adds little overhead to your project. The only overhead comes from looking for the same configuration files in multiple places. This is minimized significantly as the configuration files are still compiled and cached.

Todo

  • add lookup sequences, to determine order of dimension lookup via cartesian expression
  • add action overriding / extensions / chaining
  • apc caching + performance tweaks
  • more documentation with examples
  • more unit tests, full functional test
  • cleaner integration into symfony core
  • dimension validation via dimensions.yml
  • better caching for each dimensions (only overridden files)