Pajax

What is this?

This is a library to allow simple PHP objects to be made remotable in JavaScript, using XMLHttpRequest.

Introducing JSON

AJAX technique usually implies using XML as a data exchange format. While suitable as a format to marshal parameters back and forth, there is another format that is much more suitable for JavaScript. JSON (JavaScript Object Notation) is an alternate markup format that can be used to describe structured text data. It is based on the internal format used to store JavaScript Objects.

Object Request Broker pattern

CORBA and RMI are two well known instances of the ORB (Object Request Broker) pattern. In this pattern, objects in a distributed environment need to call methods of remote objects. For remote call to work, many details must be just right. This pattern covers the aspect of building an infrastructure that hides all the complexity from the caller standpoint.

Of caller, callee, stub and dispatcher

PAJAX is just such a framework that hides the complexity involved in calling a method on a remote object. In this example, we're going to create a basic calculator in JavaScript where the operations are performed in a PHP class. Let's start with the PHP class for our calculator:

<?
 class Calculator extends PajaxRemote {
   function add($x, $y) {
      return $x + $y;
   }

   function multiply($x, $y) {
      return $x * $y;
   }

    ...
}
?>

The class only needs to extend the base class PajaxRemote. This marker class is used to indicate that this class is remotable and thus, a stub can be created and an instance of this class can be created remotely.

In order to access this class within JavaScript, a stub class is required. It can be generated by including the following in the HTML file containing the JavaScript

<script type="text/javascript" src="pajax_import.php?Calculator">
</script>

The resulting stub class can then be used like a regular JavaScript object. The framework automatically takes care of marshaling the parameters and performs the remote call.

var calculator = new Calculator();
result = calculator.add(2, 3);

By default, the calls are performed synchronously. In most cases, it is not suitable to have the caller blocked while invoking methods on an object that lives across the network. This typically leads to a frozen UI and an overall unresponsive application.

Asynchronous Call

When you invoke a method asynchronously, the call returns immediately. Most usefull methods will return some value, so you need a way to retrieve the returned value asynchronously. This is done by specifying a listener companion object for each remote object. Each method in the remote object has a corresponding method on the listener, prefixed with "on", that is automatically invoked upon completion of the remote call. Here is a diagram of the calling sequence:

var listener = new CalculatorListener();
listener.onAdd = function(ret) {
  alert("Result:" + ret);
}

var calculator = new Calculator(listener);
// Method will return immediatly
result = calculator.add(2, 3);

Remote Object Binding

If your php object contains instance variables, you'd like to retain the same object between calls. PAJAX maintains a relationship with each instances of client object and their remote counterpart. It will lazily create a new object on the first call and bind subsequent calls to that particular object.

Demo

Try a live demo of examples using PAJAX.

Documentation

PAJAX documentation

Get the source

Get or fork pajax on Github.

License

PAJAX is licensed under the MIT license

Fantastic library.

Was just testing out your pajax engine .. and boy is it nice and clean.

... I think design vise you library is the best PHP version of AJAX for now.

Out of the many tool kits that I reviewed, many provided only part of the functionality that was needed. Many others, had requirements beyond what was feasible. Out of all that were reviewed, your Pajax tool kit was the only one that passed all the requirements. In addition, the code that makes up the toolkit is cleanly designed and is easily integrated into existing projects without a major rewrite of the code base.

I've started learning Ajax (and all that comes with it) recently, and have discovered your library - it's simply amazing. I love it.

... gr8 work on the toolkit.