5. Configuring Applications

5.1 Overview

Before you can build an application, you need to lay a solid foundation. There are several setup tasks you need to perform before deploying your PHruts application. These include components in the PHruts configuration file and in the Web Application Deployment Descriptor.

5.2 The PHruts configuration file

The Building Controller Components chapter covered writing the form-bean and action-mapping portions of the PHruts configuration file. These elements usually play an important role in the development of a PHruts application. The other elements in PHruts configuration file tend to be static: you set them once and leave them alone.

These "static" configuration elements are:

5.2.1 Controller Configuration

The <controller> element allows you to configure the ActionService.

This example uses the default values for several controller parameters. If you only want default behavior you can omit the controller section altogether.

<controller processorClass="phruts::action::PHRUTS_RequestProcessor

5.2.2 Message Resources Configuration

PHruts has built in support for internationalization (I18N). You can define one or more <message-resources> elements for your webapp; modules can define their own resource bundles. Different bundles can be used simultaneously in your application, the "key" attribute is used to specify the desired bundle.

Example configuration:

<message-resources parameter="MyWebAppResources"

This would set up a message resource bundle provided in the file under the default key. Missing resource keys would be displayed as "???keyname???".

5.2.3 PlugIn Configuration

PHruts PlugIns are configured using the <plug-in> element within the PHruts configuration file. This element has only one valid attribute, "className", which is the fully qualified name of the PHP class which implements the phruts::action::PHRUTS_PlugIn interface.

For PlugIns that require configuration themselves, the nested <set-property> element is available.

This is an example using the Smarty plugin:

<plug-in className="phruts::plugins::PHRUTS_Smarty">
  <set-property property="template_dir"
  <set-property property="compile_dir"

5.3 Configuring your application for modules

Very little is required in order to start taking advantage of the Struts application module feature. Just go through the following steps:

  1. Prepare a config file for each module.
  2. Inform the controller of your module.
  3. Use actions to refer to your pages.

5.3.1 Module Configuration Files

In PHruts, you have two options: you can list multiple phruts-config files as a comma-delimited list, or you can subdivide a larger application into modules.

With the advent of modules, a given module has its own configuration file. This means each team (each module would presumably be developed by a single team) has their own configuration file, and there should be a lot less contention when trying to modify it.

5.3.2 Informing the Controller

In order to tell the PHruts machinery about your different modules, you specify multiple config initialization parameters, with a slight twist. You'll still use "config" to tell the action service about your "default" module, however, for each additional module, you will list an initialization parameter named "config/module", where module is the name of your module (this gets used when determining which URIs fall under a given module, so choose something meaningful!). For example:


This says I have two modules. One happens to be the "default" module, which has no "/module" in it's name, and one named "module1" (config/module1). I've told the controller it can find their respective configurations under /WEB-INF/conf (which is where I put all my configuration files). Pretty simple!

(My phruts-default.xml would be equivalent to what most folks call phruts-config.xml. I just like the symmetry of having all my PHruts module files being named phruts-<module>.xml)

5.3.3 Switching Modules

Here's an example of switching from one module to another in a global forward:

    <forward name="toModuleB"

You could do the same thing with a local forward declared in an ActionConfig:

    <action ... >
      <forward name="success"

To change to ModuleB, we would use a URI like this:


You can switch back to the "default" module with a URI like this:


5.4 The Web Application Deployment Descriptor

The final step in setting up the application is to configure the application deployment descriptor (stored in file WEB-INF/web.xml).

Add an entry defining the action service itself, along with the appropriate initialization parameters. Such an entry might look like this:

<service pathParam="do">
    <include-path path="/WEB-INF/lib/pear"


Previous: Building Controller Components

This documentation is a modified copy of the Apache Struts 1.1 framework user guide, and so is copyrighted under the ASF license.