Writing PHP handlers
Types of handler
By default, without requiring any explicit configuration, PHP scripts will be served out of the public
folder as described in the File serving article.
PHP scripts can also be used to implement REST resource handlers as described in the
Resource (REST) handling article and to implement renderers as described
in the Response rendering article.
In addition, PHP scripts can be registered as handlers for any type of WebSphere® sMash
event by implementing a custom event handler.
PHP Custom Event Handlers
Custom handlers are registered in zero.config as described in the event handler registration section of the
Configuration article.
PHP files implementing custom handlers must be placed under the app/scripts folder.
The following example declares the myevent event to be handled by the myeventhandler.php
script in the app/scripts directory of the application.
/config/handlers += [{
"events" : "myevent",
"handler" : "myeventhandler.php"
}]
PHP custom event handlers can be implemented either as procedural scripts or PHP classes. In either case the global context is used to share contextual information about the event with the invoker. The example below is a procedural script that sets a value in the global context for use by the handler that fired the event.
<?php
// Event Handler for "myevent" stored in app/scripts/myeventhandler.php
$arr =
array('foo' => 'bar');
zput('/request/somekey', $arr);
?>
The same handler can also be coded as a PHP class. To do this a class must be defined which has the same name as the file specified as the
handler in the configuration, omitting any path information and the php suffix. In this case the class must be called myeventhandler.
When the event is handled, WebSphere® sMash will look for a file in app/scripts which matches the name specified in zero.config
It will first execute any outer scope script that may be present in the file. This is often used to run include statements.
It will then look for a PHP class defined in the runtime with a class name that matches the filename.
If a matching class is found and it contains a method with a name on followed by the name of the event then it
will be invoked. For example in this case the event myevent results in an invocation of the method onmyevent.
WebSphere sMash prepares to invoke the method by creating an instance of the PHP class. If there is a constructor method that takes no arguments then this will be called.
<?php
// Event Handler for "myevent" stored in app/scripts/myeventhandler.php
include "my_include.php"; //outer scope code is executed first
class myeventhadler {
function __construct() {
// Constructor with no arguments will be called
echo "sMash:";
}
function onMyEvent() {
$arr = array('foo' => 'bar');
zput('/request/somekey', $arr); }
}
}
?>
Note that the class does not actually need to be defined in the PHP file specified as the event handler. It can instead be defined in an includeed PHP script.
Note that PHP Class and function names are case-insensitive so whilst it is good practice to use names such as onMyEvent in fact onmyevent would also match.
PHP event handler for GET, PUT, POST and DELETE events
PHP scripts can be registered as handlers for any type of WebSphere® sMash event by implementing a custom event handler. As an example you can write a PHP script to handle the GET, PUT, POST and DELETE events.
This simple PHP script (called handler.php in /app/scripts) will echo a string as the response to a GET, PUT, POST or DELETE event.
<?php
class Handler {
function onGET() {
echo "onGET";
}
function onPOST() {
echo "onPOST";
}
function onPUT() {
echo "onPUT";
}
function onDELETE() {
echo "onDELETE";
}
}
?>
The following extract from the zero.config file shows how to get the handler to be called for all requests
to a URL that starts with /foo (for example, http://localhost:8080/foo/example).
# Add a custom handler
/config/handlers += [{
"events" : ["GET","PUT","POST","DELETE"],
"handler" : "handler.php",
"conditions" : "/request/path =~ /foo(/.*)?"
}]
Firing events from PHP
The PHP support in WebSphere sMash allows you to create and fire events
you define in the context of running a request using the fire_event() function.
The following script illustrates firing the specified event with contextual information that can be accessed by the event handlers.
fireevent.php
<?php
// Fire a user defined event (myevent) from a php script.
$eventctxt =
array('otherctxt' => 'foobar');
fire_event('myevent', $eventctxt);
// Get a value stored by the event handler for verification
$arr = zget('/request/somekey');
zput('/request/headers/out/Content-Type', 'text/plain');
foreach($arr as $key => $value) {
echo " $key $value";
}
?>
PHP access to the Global Context
PHP scripts and handlers in WebSphere sMash can interact with the Global Context as described in Accessing the Global Context. For a convenient list of the contents of the Global Context see the Global Context Reference.
In many cases, information in the global context would traditionally be accessed in other ways in a conventional PHP script. For example the request parameters which are
present in the global context at the key /request/params are also present in a PHP script in the $_REQUEST superglobal. The aproach taken in PHP in sMash is to
support both the sMash specific access mechanism which is consistent with the other parts of WebSphere sMash and also the PHP convention so that the expectations of experienced PHP programmers
are met and existing PHP code will run unchanged.
See the section "Zero specific PHP Function Reference" in the "PHP Support" section for documentation on the PHP functions used to access the global context:
zget, zput, zpost, zlist, zlist_all, zdelete, zdump and zcontains.
