Phrame 3 Documentation

How To Configure The Phrame Container

From Phrame version 3.1 onwards, your Phrame applications run in a so-called Phrame container, which mimicks some of the behaviour of a Java servlet container and also adds some features that are unique to PHP.

The Phrame container is configured through an array that you have to pass to the container's constructor method. Many of the parameters have a similar meaning as the parameters in the Web Application Deployment Descriptor used with Java web applications.

Configuration parameters

Listed below are all possible configuration parameters, with their allowed value(s) and default value, if any. Be aware 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
_CONTEXT	No	String	Directory of bootstrap script
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
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.
_DOCUMENT_ROOT	No	String	None
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_HANDLER	No	Array	None (will use standard PHP error handling)
The set of configuration parameters for the error handler to be used by Phrame. Note that if you omit this parameter, the standard PHP error handler will be used. The individual parameters are described here.
_ERROR_PAGES	No	Array	None
Fill with HTTP error codes and matching URIs (relative to your web application's context) of error pages to be shown if Phrame triggers such HTTP errors. You may also include error pages for one or more of the following Phrame events; only use the predefined constants to identify the pages or Phrame will not be able to locate them: _ACCESS_DENIED - page to be shown if Phrame denies access to a user based on its role-based access authorization mechanism _INVALID_SESSION - page to be shown if Phrame times out a user's session _SERVER_ERROR - page to be shown if Phrame cannot find a welcome file, module configuration or action mapping Note that error pages for HTTP errors cannot be localized; the error pages for Phrame server events however can (see How To Use Language Negotiation for more information on localization). All pages may contain PHP, but only the error pages for Phrame server events may refer to taglib functions. For example: if the action server cannot locate the configuration of a requested module, it will forward to the _SERVER_ERROR page if defined. If not defined, it will send an error response using the error page for HTTP status 202 (Accepted). If not defined, it will send a standard response the client simply notifying the user that a '202' error has occurred. For your conveniance below a list of possible HTTP errors generated by Phrame (your application might generate additional error responses): `202` - The action server encountered a problem, e.g. requested module configuration or action not found `401` - The action server has denied access due to insufficient user authorisation
_INCLUDE_DIRS	No	Array	None
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_CORE_DIR` - Name of the directory holding the Phrame class library (the `WEB-INF/lib/phrame` directory). `PHRAME_CLASSES_DIR` - Name of the directory holding your custom made classes (the `WEB-INF/classes` directory) `PHRAME_LIB_DIR` - Name of the directory holding the 3rd party class libraries used by your application (the `WEB-INF/lib` directory) `PHRAME_WEBINF_DIR` - Name of the `WEB-INF` directory
_SERVERS	Yes	Array	None
Array containing a set of configuration parameters for each action server that will be runnning in the Phrame container, keyed by the name of the action server. A zero-length name denotes the default action server, which will be used if you donot specify a name with the `PhrameContainer::run()` method. See How To Trigger The Phrame Container for more information. The individual parameters for each action server are described here.
_SESSION_CONFIG	No	Array	None
The set of parameters to configure how the Phrame container will handle sessions. The individual parameters are described here.
_TAGLIBS	No	Array	None
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 `ServerContext`, `HttpRequest` and `HttpSession` 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' );` See also How To Use Tag Libraries
_USE_LANGUAGE_NEGOTIATION	No	TRUE \| FALSE	FALSE
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
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.

Action server configuration parameters

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

Parameter	Mandatory	Value(s)	Default value
_INIT_PARAMS	Yes	Array	None
The set of initialization parameters for the action server. See How To Configure The Action Server for details. At minimum you have to specify the path to the default module configuration.
_SERVER_CLASS	No	String	ActionServer
(not yet supported) Class name of the `ActionServer` descendent that will be running in the Phrame container. Note that you donot have to specify Phrame's built-in `ActionServer` class since this will be used if you donot specify your own server. 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 `servers/MyServer` if the class `MyServer` resides in `WEB-INF/classes/servers`.
_SERVER_MAPPING	No	Array	None
The set of configuration parameters telling the action server how to map requests to a module and action. The individual parameters are described here.

Action server mapping configuration parameters

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

Parameter	Mandatory	Value(s)	Default value
_ACTION_PARAM	No	String	action
Name of the request parameter holding the action to be executed by the action server that is running in the Phrame container.
_MODULE_PARAM	No	String	module
Name of the request parameter holding the module to be selected by the action server that is running in the Phrame container.

Session configuration parameters

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

Parameter	Mandatory	Value(s)	Default value
_SAVE_HANDLER_CLASS	No	String	None (will use standard PHP session storage functions)
(not yet supported) Class name of a class that will perform the storage functions regarding the PHP sessions for the Phrame container. The API of the class has to comply with the rules for custom session storage functions as described in the PHP manual (see `session_set_save_handler()` function). Donot specify this parameter if you want to use PHP's standard file based session storage functions. 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 `sessionhandler/MySessionSaveHandler` if the class `MySessionSaveHandler` resides in `WEB-INF/classes/sessionhandler`.
_SESSION_TIMEOUT	No	Integer	-1
Set to the default period of inactivity after which sessions created by the Phrame container 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.

Error handler configuration parameters

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

Note that if you want to use PHP's standard error handler you have to leave the _ERROR_HANDLER parameter out of the container configuration.

Parameter	Mandatory	Value(s)	Default value
_ERROR_HANDLER_CLASS	No	String	ErrorHandler
Class name of the `ErrorHandler` descendent that will be used by Phrame (through PHP's set_error_handler() function). Note that you donot have to specify Phrame's built-in `ErrorHandler` class since this will be used if you donot specify your own error handler. 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 `errorhandler/MyErrorHandler` if the class `MyErrorHandler` resides in `WEB-INF/classes/errorhandler`.
_INIT_PARAMS	Yes	Array	None
The set of initialization parameters for the error handler. See How To Configure The Error Handler for details.

Configuration example

$containerConfig = array(

  // Application root
  _CONTEXT => '/myWebApp'

  // Action server configurations
  ,_SERVERS => array(

    // Default action server
    '' => array(

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

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

  // Error handler configuration
  _ERROR_HANDLER => array(
    _INIT_PARAMS => array(

      _DISPLAY_LEVEL => E_NONE

      ,_LOGGING_LEVEL     => E_ERRORS | E_WARNINGS
      ,_LOGGING_MECHANISM => 2
      ,_LOGFILE_URI       =>
           'my/path/to/phrame-3-demo.log'

      ,_ALERT_LEVEL           => E_ERRORS
      ,_ALERT_SUBJECT_FORMAT  => 
        'Alert from example.com'
      ,_ALERT_BODY_FORMAT     =>
        "The following %e occured on %d1:\n\n
         Message: %m\n
         Script: %f\n
         Line: %l\n
         Backtrace:\n\n
         %b"
      ,_ALERT_EMAIL_ADDRESSES =>
        '[email protected], [email protected]'

      ,_BACKTRACE_LEVEL	=> E_ERRORS
    )
  )

  // Error pages
  ,_ERROR_PAGES => array(

    // HTTP error statuses
    '202'  => '/common/202.html'   // Accepted
    ,'401' => '/common/401.html'   // Access denied
    ,'404' => '/common/404.html'   // Not found

    // Phrame error situations
    ,_INVALID_SESSION => '/common/invalidsession.php'
    ,_SERVER_ERROR    => '/common/servererror.php'
  )

  // Session handling configuration
  ,_SESSION_CONFIG => array(
    _SESSION_TIMEOUT => 30
  )

  // Phrame taglibs
  ,_TAGLIBS => array(
    '/WEB-INF/lib/phrame/util/PhrameTagLib.php'
  )
  
  // Welcome file
  ,_WELCOME_FILE => '/common/splash-screen.php'

  // Language related stuff
  ,_DEFAULT_LOCALE           => 'en'
  ,_USE_LANGUAGE_NEGOTIATION => TRUE

);