Unified runners in the web

at 2009-08-11 in Examples, Editorial, Announcements by kiesel (0 comments)

The XP framework had offered developers the power of an easy class loading setup via the new XP runners that are delivered with every release since several releases now. These runners have proven themselves very useful in day-to-day business, so we're working on porting them to the web!

With the so-called web-runners these new cool and useful features will become available for you:

Easier classpath setup
Classpaths will be constructed from .pth files, in the same manner as xpcli does it.

No boilerplate "index.php"s any more
you won't need the same index.php over and over in every project again; even more: you don't need any entrypoint .php any more even for SOAP- or JSON-endpoints.

Multiple etc/ configuration directories
you can switch between multipe etc/, eg. one for the test server and one for production, by changing a single file

Overwrite arbitrary settings for special servers
you can overwrite settings, eg. debugging settings, based on where your application runs - eg. on the development machine, you can have debugging enabled, while on production it's disabled. You don't need to have different files for them - no more mistakenly committed debug settings.

This article shows you how you can make use of the web runners in a XP application. Read on for more information!

The web runners provide the main entrypoint for a web application through the tools/web.php file; this file is a replacement for basically any index.php that exist in the document root. Any requests that were routed through the former index.php need to be routed through an alias:

Apache configuration

This is what you need in you virtualhost setup:

Alias /xp-web /path/to/xp/trunk/tools/web.php
RewriteEngine On
RewriteCond %{REQUEST_URI} !^/static
RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} !-f
RewriteRule ^/.*$ /xp-web [PT,L]

This will pass all requests that do not access a file in the /static folder and that does access any path that actually exists in the file system to the /xp-web alias, which is in return an alias to our web.php.

Note: this implies that there will be the convention to store static content in the /static path. The second RewriteCond makes your upgrade path easier, by letting pass all requests that access files not in /static; you can - and should - omit this, if your application already complies with the above convention.

The original index.php has been substituted now, instead web.php will be run; it needs a bit of configuration in etc/web.ini:

XP framework configuration

[app]
mappings="/service:website-ajax-service|/:website"

[app::website]
class="net.xp-framework.website.scriptlet.WebsiteScriptlet"
init-params="net.xp-framework.website|{WEBROOT}/xsl"
init-envs="DEF_PROD:website"

[app::website@qualityassurance]
prop-base="{WEBROOT}/etc/qa"

[app::website@development]
debug="XML|ERRORS|STACKTRACE"

[app::website-ajax-service]
class="net.xp-framework.website.scriptlet.ajax.WebsiteRpcRouter"
init-params="net.xp-framework.website.ajax"

Settings overview

The [app] section is mandatory - it's the main entry point for the web runner; the expressions in mappings will be read and the first one matching the current request will be chosen. The associated name, prefixed with app:: is the name of the section which then is being read and which contains the basic application configuration. The following list shows the directives being read and their meaning:

class= -defines which scriptlet class to load and run

init-params= - defines which parameters are given to the scriptlet's constructor (usually package name and path to xsl/ files). The string {WEBROOT} will be replaced by the full path to the folder of your application, it can be used to build relative paths to xsl/ or other folders, for example.

init-envs= contains a set of environment variables that is being set for the application. Use of this directive is discouraged, but was included for backward compatibility reasons: so far, XP scriptlet applications fetch some of their runtime configuration from environment variables.

debug= - this rule controls which debug information are printed; it can be an enumeration of different string, joined with a pipe ("|"). These tokens are available:
- XML - prints the XML document
- ERRORS - prints the XP framework error stack
- STACKTRACE - prints a full stacktrace in case of uncaught exceptions
- TRACE - if the scriptlet class implements util.Traceable, it can be traced with this token.
.

prop-base= - moves the base directory for the util.PropertyManager to the path given in this line; also supports the {WEBROOT} abbreviation. If this is omitted, it defaults to {WEBROOT}/etc.

Server profile

Last but not least, the web-runner introduces one last special environment variable into the Apache configuration: SERVER_PROFILE. This variable can be set to associate the server with a website profile. In above example, there are two profiles being used "qualityassurance" and "development". The effect here is: the section of the application only becomes active, if the server's profile matches the part after the @ in the configuration.

Include paths

Include path setting was one of the most mysterious configuration settings for most users when they set up an XP framework application. Now, it's easy: the web-runner just searches the global include_path for .pth files and evaluates those in the same way xpcli does it. There is one special path: ~ is always expanded to the applications home dir which is {WEBROOT} which is the directory one level above doc_root. So, at least for development machines, you can just globally set your include path to ~:/path/to/xp/skeleton to pick up the framework core and your application's paths.

You can subscribe to the XP framework's news by using RSS syndication.