Phrame 3 Documentation

How To Define A Module Configuration

As with earlier Phrame versions, actions, forms and forwards are defined by means of an array, containing key-value pairs that represent the various mapping parameters. Meaning and usage of most of the parameters are similar to the Struts configuration file.

Module configuration parameters

The table below lists all possible module configuration parameters, with the allowed value(s) and default value, if any. Note that Phrame uses constants rather than strings to identify the parameters, which you must use to ensure proper configuration. If you omit a configuration parameter, Phrame will use the default value.

Parameter	Mandatory	Value(s)	Default value
_ACTION_FORMS	No	Array	None
The set of action form definitions for this module configuration, keyed by name. Use this name to link an action form to an action (through the `_NAME` configuration parameter for the action). The parameters for a single action form are described here.
_ACTION_MAPPINGS	Yes	Array	None
The set of action definitions for this module configuration, keyed by name. The action server will use this name to look up the action to which a request refers. The parameters for a single action are described here.
_CONTROLER	No	Array	None
The set of parameters to configure the controller for this application module. Details can be found here.
_GLOBAL_FORWARDS	No	Array	None
The set of forward definitions that can be used with any action defined for this module configuration, keyed by name. Use this name look up a forward in the `execute()` method of your `Action` classes. The parameters for a single forward are described here.
_MESSAGE_RESOURCES	No	Array	None
The set of parameters to configure the message resource bundle used by this module configuration. In contrast to Struts, Phrame only allows for one resource bundle per module. Details can be found here.

Controler parameters

The table below lists possible parameters that are part of the _CONTROLER array.

Parameter	Mandatory	Value(s)	Default value
_INPUT_FORWARD	No	TRUE \| FALSE	FALSE
Set to TRUE if the `_INPUT` parameter of an action definition associated with this module be treated as the name of a global or local action forward. A FALSE value treats them as a context-relative path.
_LOCALE	No	TRUE \| FALSE	FALSE
Set to TRUE if a user's prefered locale should be stored in the user's session, FALSE otherwise.
_PROCESSOR_CLASS	No	String	RequestProcessor
Class name of the `RequestProcessor` descendent that will be used to process requests for this application module. Note that you donot have to specify Phrame's built-in `RequestProcessor` class since this will always be used if you donot specify your own processor. The class definition should be present in the `WEB-INF/classes` directory. You may prefix the name with the path, relative to this root, if the class resides in a subdirectory. The path must not start with a '/'. For example: use `processors/MyProcessor` if the class `MyProcessor` resides in `WEB-INF/classes/processors`.

Message resources parameters

The table below lists possible parameters that are part the _MESSAGE_RESOURCES array.

Parameter	Mandatory	Value(s)	Default value
_NULL	No	TRUE \| FALSE	FALSE
Set to TRUE if the action server should return a NULL when an unknown locale or message key is requested. Set to FALSE if the server should display a message like '??? ll xx...xx ???', where 'll' is the requested locale and 'xx.xx' the requested message key.
_PARAMETER	Yes	String	None
Fully qualified package and resource name of a series of files containing the messages for each of the languages supported by the application module. All files should have the extension '.properties' and should reside your `WEB-INF/classes` directory (or sub directory). The file name of a property file for specific language must include the involved language code, prefixed by an underscore. The file name for the default language doesnot include a language code. Example: Suppose you have property files with messages for the default locale (e.g. 'en') and the 'fr' and 'nl' locales. If the `_PARAMETER` value is set to `resources/MyMessages`, Phrame will be able to load the following property files: `...your application's context path.../WEB-INF/classes/resources/MyMessages.properties` for the default locale `...your application's context path.../WEB-INF/classes/resources/MyMessages_fr.properties` for the 'fr' locale `...your application's context path.../WEB-INF/classes/resources/MyMessages_nl.properties` for the 'nl' locale

Action parameters

The table below lists possible parameters for an individual action. Action definitions are part of the _ACTION_MAPPINGS array.

Parameter	Mandatory	Value(s)	Default value
_ACTION_FORWARDS	No	Array	None
The set of local forward definitions for this action, if any, keyed by name. The mapping parameters for a single forward are described here.
_FORWARD	Conditionally	String	None
Context-relative path of the web resource that will process a request for this action rather than instantiating and calling the Action class specified by `_TYPE`. Very usefull for self-contained views that donot require any pre-processing. If this parameter is present, the `_TYPE` parameter is ignored. Omitting both the `_FORWARD` and `_TYPE` parameter will result in an error.
_INPUT	Conditionally	String	None
Context relative path of the input form to which control should be returned if a validation error is encountered. Or, if the `_INPUT_FORWARD` parameter of the controler definition (`_CONTROLER`) is set to TRUE, the name of a global or local forward that will be used to calculate the input path. The parameter is ignored if the `_NAME` parameter is not set. Omitting this parameter will result in an error if the `_VALIDATE` parameter is set to TRUE and a validation error occurs.
_NAME	No	String	None
Key of the action form, if any, associated with the action. The key has to be present in the array matching the `_ACTION_FORMS` parameter.
_PARAMETER	Conditionally	String	None
A general purpose parameter that can be used to pass extra information to an action. Used for instance in dispatcher actions, such as `DispatchAction`. Omitting this parameter for such actions will result in an error. Several conveniant values are available as predefined constant: `_VIEW` e.g. to denote a view to be created by a view factory; `_METHOD` e.g. to select a method in a `DispatchAction` `_SUBMIT` ditto
_SCOPE	No	'session' \| 'request'	'session'
Identifier of the scope within which the form associated with this action is stored and accessed. Either 'request' or 'session'. This parameter is ignored if the `_NAME` parameter is not set. Note that for most forms request scope is sufficient. Use session scope only if your form is shared by multiple requests (e.g. in a wizard like dialog).
_SECURITY_ROLES	No	String	None
A comma-separated list of security role names used to authorise access to this action. Note Phrame does not yet use this parameter.
_TYPE	Conditionally	String	None
Class name of the `Action` descendent that will process this action. Be aware that you cannot specify Phrame's `Action` class since this is a virtual class only indicating the minimum set of methods to be supported by an action (in PHP5 this is called an interface). The class definition has to be present in the `WEB-INF/classes` directory. You may prefix the name with the path, relative to this root, if the class resides in a subdirectory. The path must not start with a '/'. For example: use `actions/MyAction` if the class `MyAction` resides in `WEB-INF/classes/actions`. If the `_FORWARD` parameter is present, the `_TYPE` parameter is ignored. Omitting both the `_TYPE` and `_FORWARD` parameter will result in an error.
_UNKNOWN	No	TRUE \| FALSE	FALSE
Set to TRUE if the action is the default action for this module. This action will be called if the request does not refer to an action. If you mark multiple actions with the `_UNKOWN` parameter set to TRUE, only the first action will be regarded as the default.
_VALIDATE	No	TRUE \| FALSE	FALSE
Set to TRUE if the `validate()` method of the `ActionForm` associated with this action should be called. This parameter is ignored if the `_NAME` parameter is not set.

Action form parameters

The table below lists possible parameters for an individual action form. Action form definitions are part of the _ACTION_FORMS array.

Parameter	Mandatory	Value(s)	Default value
_TYPE	Conditionally	String	None
Class name of the `ActionForm` class or descendent used with one or more actions. You may specify one of Phrame's built-in form classes, such as `ActionForm` or `DynaActionForm` if it satifies your needs (e.g. when you donot need specific form validation). The class definition has to be be present in the `WEB-INF/classes` directory. You may prefix the name with the path, relative to this root, if the class resides in a subdirectory. The path must not start with a '/'. For example: use `forms/MyForm` if the class `MyForm` resides in `WEB-INF/classes/forms`.

Global and action forward parameters

The table below lists all possible parameters for an individual forward. Global forward definitions are part of the _GLOBAL_FORWARDS array. Action forwards are part of the _ACTION_FORWARDS array in an action definition.

Parameter	Mandatory	Value(s)	Default value
_CONTEXT_RELATIVE	No	TRUE \| FALSE	FALSE
Set to TRUE if the `_PATH` value should be interpreted as context-relative rather than module-relative if it starts with a '/' character.
_PATH	Yes	String	None
Module-relative or context-relative URI to which control should be forwarded, or an absolute or relative URI to which control should be redirected. Note that an absolute URI is only allowed if the `_REDIRECT` parameter is set to TRUE. Note that the usage of absolute path is not yet implemented in Phrame.
_REDIRECT	No	TRUE \| FALSE	FALSE
Set to TRUE if the action server should redirect to the associated path, otherwise FALSE.

Configuring multiple module configurations (pre 3.1 versions)

Phrame 3 offers the possibility to use separate mappings for particular parts of your web application. This (Struts) functionality is virtually indispensable when building complex web applications with a large team of developers, sometimes dealing with hundreds of PHP scripts.

Using separate module configurations enables you to split up the application into separate application modules, which can be developed and tested by separate teams without interfering with each other.

You have to define the module configurations in the configuration of your action server through the _CONFIGS configuration option. As with Struts, one of the module configurations (named by a zero-length string) serves as default configuration. The server will use this configuration if a request does not refer to a module. The code snippet below shows an example.

$serverOptions = array(

  _CONFIGS => array(
    ''       => 'WEB-INF/configs/default-config.xml'
    ,'addon' => 'WEB-INF/configs/addon-config.xml'
  )
  ,_DIGESTER_CLASS
             => 'util/XMLConfigDigester'

  ...
  other configuration parameters go here
  ...

);

Using this module configuration, the action server will load the module configuration WEB-INF/configs/phrame-addon-config.php whenever a request contains a _MODULE parameter with the value addon. If no _MODULE parameter is present, it will load the module configuration WEB-INF/configs/phrame-default-config.php.

If your application is not split up into modules, you only have to configure the default (unnamed) module configuration and define the corresponding mappings array. In this case you may also omit the _MODULE parameter from your client requests.

Configuring multiple module configurations (version 3.1 and later)

You have to define the module configurations in the initialization parameters of your action server. The server and its initialization parameters are defined in the configuration of the Phrame container, much like in a Java Web Deployment Descriptor. The code snippet below shows an example.

$containerConfig = array(

  _SERVERS => array(

    // Configuration of the (default) action server
    '' => array(

      // The server's initialization parameters
      ,_INIT_PARAMS => array(
        _CONFIGS => array (
          ''       => '/WEB-INF/config/default-conf.xml'
          ,'addon' => '/WEB-INF/config/addon-conf.xml'
        )
        ,_DIGESTER_CLASS => 'util/XMLConfigDigester'
      )

      // The server's module & action mapping
      ,_SERVER_MAPPING => array(
        _MODULE_PARAM  => 'theModule'
        ,_ACTION_PARAM => 'theAction'
      )
    )
  )

  ...
  other container configuration parameters go here
  ...

);