Phrame 3 Documentation

How To Configure An Action Server

A Phrame action server is configured through an array that you have to pass to the server's constructor method. The array contains one or more key-value pairs representing the configuration parameters. The meaning and usage of some of the parameters is similar to the Web Application Deployment Descriptor used with Java web applications.

Specific remarks for version 3.1 and later

From Phrame version 3.1 onwards most of an action server's configuration parameters have been moved to the configuration of the Phrame container, much like in a Java Web Deployment Descriptor.

Also multiple action servers can be running in one container, hence the container configuration might contain multiple action server configurations. See How To Configure The Phrame Container for more details

The code snippet below shows an example of an action server configuration in a 3.1 style container configuration.

$containerConfig = array(

  // Action server configurations
  _SERVERS => array(

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

      // Below is the actual configuration of the 
      // server. All possible parameters are shown.
      _INIT_PARAMS => array(
        _CONFIGS => array(
          ''       => '/WEB-INF/conf/default-conf.xml'
          ,'addon' => '/WEB-INF/conf/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
  ...

);

Configuration parameters

Listed below are all possible configuration parameters, with their 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
_ALLOW_SESSION_ RESTARTING	No	TRUE \| FALSE	FALSE
(pre 3.1 versions only) Set to TRUE to activate the session restarting mechanism. When active, the action server restarts the PHP session each time an `Action`, `ActionForm` etc. class is loaded, to avoid an 'incomplete' object' error. If you set this option to FALSE, all the classes used in your application have to be included BEFORE calling the server's `process()` method.
_CONFIGS	Yes	Array	None
(all versions) Fill with the names and matching URIs (relative to your web application's context) of the configuration files for the application modules supported by the action server. Each URI has to start with a '/'. A zero-length name denotes the default module configuration, which is used if the request does not refer to a named module. You can specify as many modules as you need, but only the default module is mandatory.
_CONTEXT	No	String	Directory of bootstrap script
(pre 3.1 versions only) Set to the path (relative to the web server's document root) to the root of the web application served by the action server. The path has to start with a '/'.
_DEFAULT_LOCALE	No	String	None
(pre 3.1 versions only) Set to the language code of the default language to use by the action server. The language code has to be supported by the HTTP standard; Phrame only uses the first two characters. The locale will be available in a constant named `PHRAME_DEFAULT_LOCALE`. Note that the value will not be validated.
_DIGESTER_CLASS	No	String	ArrayConfigDigester
(all versions) Set to the name of the digester class to parse module configurations. Currently only one type of digester is supported: ArrayConfigDigester. This digester enables you to specify the configuration in the internal Phrame Mapping Array format.
_DOCUMENT_ROOT	No	String	None
(pre 3.1 versions only) Set to the document root of the web server. This configuration parameter is only needed if the web server does not provide this information through the predefined variable `$_SERVER['DOCUMENT_ROOT']`. Omitting this parameter if the action server cannot determine the document root will result in an error.
_ERROR_PAGES	Yes	Array	None
(pre 3.1 versions only) Fill with names of error pages with matching URIs (relative to your web application's context), to be shown if Phrame encounters certain errors. E.g. a 'server error' if the action server cannot locate the configuration of a requested module. Note that you may implement language negotiation to enable the server to show different error pages for different languages (see How To Use Language Negotiation for details). The following constants are mandatory to identify standard error pages: `_SERVER_ERROR` - Denotes the page to return if the action server encounters a problem, e.g. requested module configuration or action not found `_ACCESS_DENIED` - Denotes the page to return if the action server denies access due to insufficient user authorisation `_INVALID_SESSION` - Denotes the page to return if the action server has timed out the user's session
_INCLUDE_DIRS	No	Array	None
(pre 3.1 versions only) Fill with constant names with matching paths (relative to your web application's context) of directories, which the action server will use to set up constants to be used in `require()` and `include()` statements. This will improve maintainability of your Phrame application. The following constants are always available: `PHRAME_CLASSES_DIR` - Denotes the directory holding your custom made classes (the `WEB-INF/classes` directory) `PHRAME_LIB_DIR` - Denotes the directory holding the 3rd party class libraries used by your application (the `WEB-INF/lib` directory) `PHRAME_CORE_DIR` - Denotes the directory holding the Phrame class library (the `WEB-INF/lib/phrame` directory).
_PHP_ERROR_REPORTING	No	valid PHP error reporting level	0
(pre 3.1 versions only) PHP error reporting level to be set by Phrame. See the error_reporting() function for details. WARNING: defaults to 0, i.e. no error reporting !
_SESSION_TIMEOUT	No	Integer	-1
(pre 3.1 versions only) Set to the default period of inactivity after which sessions created by the action server should be timed out automatically. The period must be specified in a whole number of minutes. A value of -1 means a session will never time out.
_TAGLIBS	No	Array	None
(pre 3.1 versions only) Fill with the URIs (relative to your web application's context) of one or more function libraries that should be loaded for use in your application's web resources. Each URI has to start with a '/'. A library supporting several variables with Phrame objects like the current `HttpSession`, `ModuleConfig` and `ServerContext` is included in the `util` directory of the phrame package. You may activate this library as follows: `_TAGLIBS => array( '/WEB-INF/lib/phrame/util/PhrameTagLib.php' );`
_USE_LANGUAGE_NEGOTIATION	No	TRUE \| FALSE	FALSE
(pre 3.1 versions only) Set to TRUE to activate the language negotiation mechanism. When active, the action server searches for a localized version of a web resource before forwarding to it. The URI of this localized version has to contain a language code (as in /mypage_en.php) matching the user's prefered locale (which in this case should be 'en'). If the localized resource exists, the action server forwards to this resource, otherwise it forwards to the non-localized resource.
_WELCOME_FILE	No	String	None
(pre 3.1 versions only) Set to the URI (relative to your web application's context) of the resource to use when a request does not refer to a module, nor to an action. If this situation occurs and no welcome file is specified, the action server returns an error.

Configuration example (pre 3.1 versions)

$serverOptions = array(

  // Application root
  _CONTEXT            => '/myWebApp'

  // Module configurations & digester
  ,_CONFIGS => array(
    ''          => '/WEB-INF/conf/default-config.xml'
    ,'addon'    => '/WEB-INF/conf/addon-config.xml'
  );
  ,_DIGESTER_CLASS    => 'util/xmlConfigDigester'

  // Welcome file
  ,_WELCOME_FILE      => '/common/splash-screen.php'

  // Error pages
  ,_ERROR_PAGES => array(
    _ACCESS_DENIED    => '/common/accessdenied.html'
    ,_INVALID_SESSION => '/common/invalidsession.html'
    ,_SERVER_ERROR    => '/common/servererror.html'
  )

  // Phrame taglibs
  ,_TAGLIBS => array(
    '/WEB-INF/lib/phrame/util/PhrameTagLib.php'
  )
  
  // Error reporting
  ,_PHP_ERROR_REPORTING      => 0

  // Session handling
  ,_SESSION_TIMEOUT          => 30
  ,_ALLOW_SESSION_RESTARTING => TRUE

  // Locale
  ,_DEFAULT_LOCALE           => 'en'
  ,_USE_LANGUAGE_NEGOTIATION => TRUE

);