PHPOlaitEx
Web 2.0 RPC Server in an instant
Ever want to re-use your existing php classes to web 2.0 style pages?
Well, read on….
PHPOlaitEx is a fork of the excelent phpolait library. It’s goal is to increase simplicity of use and maximize compatibility when used with other javascript libraries. As simple as configuring proxy metafile to start using your existing class.
With PHPOlaitEx, you can create web 2.0 (ajax) rpc server in an instant from your existing php class. The main reason for this fork is to make phpolait compatible with dojo toolkit. Combined together, phpolait and dojo toolkit make perfect tools to develop easy web 2.0 with RPC Server support. However, there is no limitation how to use phpolait with. You can use it to create Service Oriented Architecture, or just to get RPC Server support.
This documentation is still lack details. But I hope it serve as a basic knowledge.
This document and examples in this page can also found in the source package.
For you who are not familiar with phpolait, here is a quick quote from the original phpolait:
“PHP-O-Lait, in two boiler-plate lines of code (three if you include the
'require_once') provides a transparent bridge between server-side PHP methods
and client-side JavaScript code .
Under the hood, PHP-O-Lait uses Ajax to send the request and receive the response, and JSON for the data encoding /
decoding. You don't need to know what either of these are to use PHP-O-Lait,
but Ajax is a bag-of-tricks using client-side JavaScript to communicate with a
server without loading a new page in the browser, and JSON is a light-weight
data transfer protocol that is much more bandwidth-friendly than XML, and, I
think, better suited to loosely-typed languages such as PHP and JavaScript.”
Or you can visit the website at: http://phpolait.sourceforge.net/doc/index.html
PHPOlaitEx share most of the original PHPOlait, with added simplicity and flexibility. PHPOlaitEx is different in implementation than the original project, yet, in many way, I want to make it as compatible as possible with the original project.
These are among other new features provided by PHPOlaitEx:
<script type=”text/javascript” src=”insert_your_phpolait_class_here”></script>
Trying up PHPOlaitEx is fairly simple, but a little different from the original phpolait. This drive toward web 2.0 style. For a simple start, you only need to configure proxy metafile to start calling your class with PHPOlaitEx. No need extra code. Given your class follow these guidline.
PHPOlait will expose methods of a class. Any value returned from a method, will be return back to the caller (Javascript in this case). Any error thrown from a method will also get caught in the caller (provided you create an event handler). As of common rpc server. Sync or Asynchrounously
You should design your class as a data producer or data consumer, and strictly that. Don’t produce any output directly to output buffer, either with echo or print or any other method that has the purpose to produce output. It will make PHPOlaitEx failed to deliver values to javascript caller function. PHPOlaitEx communicate using json transparently, any direct output will break the json format used to communicate between javascript and RPC Server.
Handle your errors without using default php errorhandling. You could simply throw error in your methods with exception object and it will be catch by PHPOlaitEx in the javascript. Errors displayed directly to output will break JSON notation. Be sure to turn off display_error in your php ini.
To put it simple, don’t use any direct output. PHPOlaitEx will tranparently convert any result from methods into JSON notation. PHPOlaitEx can convert any type supported by php to json notation, including objects. You should limit object return from methods as structs. Methods exist within object returned will not be generated into JSON object. Try it your self.
You should also design your class as smaller classes. Don’t be tempted to put all of your function into one class. As you have more functions or methods, you could save some cpu cycles when you put your methods into smaller classes. Think hundres of methods.
All files are available trough sourceforge download page
Installation should be straightforward: unzip the zip file into your webserver directory. I presume, for this documentation, that it's in the root of your webserver, but it should work correctly anywhere. You will have three directories: /doc, which contains this documentation, /phpolait, which contains everything you need to write PHP-O-Lait enabled applications, and /examples, which contains the some examples.
Configuring PHP-O-Lait
PHP-O-Lait should require no configuration. All required packages are bundled in the phpolait directory.
Optional Libraries
If you like to use smarty, you must include smarty library in the proxy metafile.
While not be two line-er code, all you need to do to start using your php class with PHPOlaitEx is configuring the proxy metafile.
Okay, here is three easy step to PHPOlaitEx.
First, setup your php class. Here is an example.
<?php
/* filename: test.class.php
PHPOlaitEx Example php class
@author Henry Eko, dmaster@cbn.net.id
licensed under LGPL
*/
class testClass{
function r_add($a,$b){
return $a + $b;
}
function r_subtract($a,$b){
return $a - $b;
}
function r_multiply($a,$b){
return $a * $b;
}
function r_divide($a,$b){
return $a / $b;
}
function r_echo($s){
//delay(10);
return "echoed from rpc server :" . $s;
}
}
?>
Save this file as “test.class.php”
Second, setup a proxy metafile, proxy metafile is used by PHPOlaitEx to describes your class to a web page. This is a simple proxy metafile template.
<?php
/**
* PHPOlaitEx simple proxy metafileThis is a simple proxy metafile template to generate source javascript use in jsolait rpc call
* Licensed under LGPL
* @version 0.1
* @author Henry Eko H - dmaster@cbn.net.id
* @copyright Oktober 2006.
* @param string path - path to php class file
* @param string name - name of target php class
* @param string proxy - name of proxy variable in javascript
* To use phpolait smarty, you must include smarty library in this metafile.
*/
require_once("../PHPOlaitExt.php");
//require_once("../phpolait.smarty.class.php");
/**
* @var string path to rpc class file
*/
$strClassPath = "test.class.php";
/**
* @var string Name of your class
*/
$strClassName = "testClass";
/**
* @var string Name of proxy object in javascript
* methods from your class will be put as methods in this proxy object
*/
$strProxyName = "proxyTest";
require_once($strClassPath);
$srcOutputMode = $_GET["srcOutputMode"];
/*
* there are two types of JSONRpcServerEx. Standard and Smart with smarty library support.
* to use JSONRpcServerSmart you must include smarty library in the proxy metafile
*/
$server = new JSONRpcServerEx(new $strClassName);
//$server = new JSONRpcServerSmart(new $strClassName);
if ($srcOutputMode=="SMD"){
$server->srcSMD();
}else{
$server->srcJavaScript($strProxyName);
}
?>
Save this example as “test.proxy.php”
By default, to setup a simple proxy metafile, just setup the variables to match your needs. No need to change the rest of metafile. Unless you want to use the smarty extension.
Third, the caller. This is an example page.
<html>
<!--
PHPOlaitEx Example Page
@author Henry Eko, dmaster@cbn.net.id, December 2007
Licensed under LGPL
/-->
<!-- there is some certain compatibility issue with other js libraries
if jsolait libraries is create / write dynamicly with document.write
so, include these libraries manual -->
<!-- include jsolait library manually here -->
<script type="text/javascript" src="../jsolait/init.js"></script>
<script type="text/javascript" src="../jsolait/lib/urllib.js"></script>
<script type="text/javascript" src="../jsolait/lib/jsonrpc.js"></script>
<!-- at least these 3 libaries are needed to use PHPOlaitEx -->
<!--reference to your proxy file /-->
<script type="text/javascript" src="test.proxy.php"></script>
<script type="text/javascript">
/*
var valA;
var valB;
var cTest;
var valEcho;
valA = document.getElementById("valA");
valB = document.getElementById("valB");
checkAS = document.getElementById("checkAS").value;
valEcho = document.getElementById("valEcho");
*/
</script>
<script type="text/javascript">
function btnAdd_OnClick(){
valA = document.getElementById("valA");
valB = document.getElementById("valB");
checkAS = document.getElementById("checkAS").value;
if (checkAS){
/**
* sync call will wait until the function is finished
* and return the value directly
* proxyTest is the name of our rpc object as describe in the proxy metafile
*/
alert("return :" + proxyTest.r_add(valA.value,valB.value));
}else{
/**
* async call will not wait for function to finished,
* instead it could call a function back when finished.
* provide a function as call back in the last parameter of your function
*/
proxyTest.r_add(valA.value,valB.value,CB_Common);
}
}
function btnSub_OnClick(){
valA = document.getElementById("valA");
valB = document.getElementById("valB");
checkAS = document.getElementById("checkAS").value;
if (checkAS){
/**
* sync call will wait until the function is finished
* and return the value directly
* proxyTest is the name of our rpc object as describe in the proxy metafile
*/
alert("return :" + proxyTest.r_subtract(valA.value,valB.value));
}else{
/**
* async call will not wait for function to finished,
* instead it could call a function back when finished.
* provide a function as call back in the last parameter of your function
*/
proxyTest.r_subtract(valA.value,valB.value,CB_Common);
}
}
function btnEcho_OnClick(){
valEcho = document.getElementById("valEcho");
checkAS = document.getElementById("checkAS").value;
if (checkAS){
/**
* sync call will wait until the function is finished
* and return the value directly
* proxyTest is the name of our rpc object as describe in the proxy metafile
*/
alert("return :" + proxyTest.r_echo(valEcho.value));
}else{
/**
* async call will not wait for function to finished,
* instead it could call a function back when finished.
* provide a function as call back in the last parameter of your function
*/
proxyTest.r_echo(valEcho.value,CB_Common);
}
}
/**
* Simple callback used with PHPOlaitEx callback;
* callback function must have two parameter
* @param {Object} res. the return value is here
* @param {Object} err. error value
*/
function CB_Common(res,err){
/**
* Get the error message
*/
if (err!=null){
alert(err.msg);
}else{
//process the result
alert(res);
}
}
</script>
<body>
<h1>PHPOlaitEx Examples</h1>
<input type="checkbox" id="checkAS">Check to call rpc synchronously</input><br/>
Input value a : <input id="valA"></input><br/>
Input value b : <input id="valB"></input><br/>
<input type="button" onclick="btnAdd_OnClick()" value="Remote Add A + B"> </input>
<input type="button" onclick="btnSub_OnClick()" value="Remote Subtract A - B"></input><br />
Echo test <input id="valEcho"></input><br/>
<input type="button" onclick="btnEcho_OnClick()" value="Test Echo"></input><br/>
</body>
</html>
Save this example as test.page.html
Okay,I hope to keep it simple. Web 2.0 wave is high, with PHPOlaitEx, everyone can have a joy ride. The main reason I create a fork instead working directly inside the original project is because I couldn’t contact the original author. I try to reach him with email with no luck. So I just fork it. Some of the original code was changed.
Why took so long to publish PHPOlaitEx, well, connectivity is to blame. The internet is not always available to me. I would like to sync my svn repo to google code hosting, but since PHPOlaitEx is part of a larger project, I just don’t know how to do it.
PHPOlaitEx is used in live projects far before this first package is published.
Happy coding….
© Henry Eko Hapsanto, dmaster@cbn.net.id