Xaja installation

Prerequisites

Xaja is a Reverse Ajax PHP Framework. In order to successfully install Xaja, you need to be accustomed with PHP application development.

You will first need to set up a PHP development environment, which is usually composed of an Apache web server, the PHP Apache extension and a database (usually MySQL or PostGreSQL).

In this installation procedure, we will assume that you already have this environment installed, working, and that you know the directory of your web application.

Xaja requires at least PHP 5.2 (but not 5.2.6 that contains a bug on sockets management), so be sure your development server runs a PHP 5+ environment. Please note that the PHP Command-line interface needs to be installed. On Linux systems, the PHP CLI is usually in a specific package (usually wisely named "php-cli"). On a Linux command-line, type "php -v" in order to verify that the PHP CLI is installed. If an error occurs, PHP CLI is not installed, and you will need to install it. On Windows systems, look for the php.exe file.

Xaja also requires the PHP socket library to be installed. While testing, if you are getting the error Call to undefined function socket_clear_error(), then it is likely that this library is not installed. Refer to the FAQ for more information on how to install this library. Installation of the library is usually done in the php.ini file by uncommenting the line:

#extension=php_sockets.dll

#extension=php_sockets.so

Xaja requires you to turn off the output buffering parameter in your php.ini file. This setting is turned on by default on some systems. Xaja provides its own output-buffering handling that is in conflict with PHP's default behaviour. So you can dive in your php.ini file and change the output_buffering to

output_buffering = Off

Finally, when using Xaja, you will probably using special <?xaja ?> tags. In order to use these tags, you will have to turn off the short_open_tags option in your php.ini file. Otherwise, those tags would be interpreted directly by the PHP interpreter. So you will change the short_open_tags line to:

short_open_tag = Off

Also, please be aware that this on most systems, there are 2 php.ini files. One for the Apache configuration and one for the CLI configuration. You should modify both of them.

Downloading dependencies

Xaja comes with a database ORM library named TDBM. Although you are not required to use it, it comes by default and has a dependency: PearDB. If you do not plan to use the database ORM library, you can skip this step, but we strongly encourage you to take it.

PearDB is a package from the Pear library. Pear is usually bundled with PHP or comes in a convenient to install package with many Linux distributions (package "php-pear" in Ubuntu for instance).

First, install Pear, if it is not already installed on your server
Then, install the PearDB package, using the command-line prompt and the command:
```
pear install DB
```
You will need to run this command as "root" user if you are running a Linux machine.

Installing Xaja

If you haven't done it yet, you will need to download Xaja. You can do that from the download page

Now, you can copy the content of the xaja directory to your web application.
That's it!

Configuring Xaja

Before using Xaja, you need to configure a few parameters. Xaja options are all in the config.php file at the root of the Xaja directory. You should edit this file before using Xaja.

Xaja web directory parameter

The most important parameter is the $xaja_web_directory parameter. Xaja needs to know how its own Javascript scripts can be accessed from the browser. For instance, if the Xaja main directory is mapped to http://[yourip]/myapp/xaja, then the xaja web directory is /myapp/xaja:

$xaja_web_directory = "/myapp/xaja";

Be sure that you do not put any trailing "/".

Xaja broker URL parameter

Another very important parameter is the $xaja_broker_url parameter. In order to provide reverse Ajax features, Xaja needs to be able to let several processes exchange informations. This is done using the Xaja broker. The Xaja broker is a kind of server. Therefore, it needs to open a listening port. The $xaja_broker_url parameter specifies this port.

Xaja can use 2 connection technologies to let processes dialog:

TCP pipes: the standard network pipes work on any system, and can enable a single broker for many platforms, which may be useful if you are looking to build a cluster of machines.
IPC pipes: Interprocess Communication pipes are the fastest way to let two processes on the same machine. They are local, which means you cannot use them in a clustered environment (with many application servers), and they can be used only on Unix/Linux platforms.

The Xaja Broker URL can be either a IPC pipe (for Unix systems only) or a TCP url. An IPC pipe is a non existing file on your file system that can be written by the Apache process.
For instance: /tmp/xaja_broker might be a valid one.
A TCP url is pointing to a TCP port on a local or distant machine and should start with "tcp://" For instance, tcp://127.0.0.1:4242 might be valid is the 4242 port is not used on your machine.

Note: performance using a TCP port in Linux seems very poor. If you are running a Linux server, we strongly encourage you to use IPC sockets which are tremendously faster.

PHP Command line interface

The Xaja broker acts as a server, and as any server, it needs to be started. Xaja can start it automatically. For this, you need to tell Xaja were the PHP Command line interface is located. You do this using the $xaja_php_cli_program parameter.

For instance, if you are running a Linux system, the path to the program will be something like this:

$xaja_php_cli_program = "/usr/bin/php";

and if you are running a Windows system, it will be something like:

$xaja_php_cli_program = "C:\\Program Files\\wamp\\php\\php.exe";

As usual in PHP with Windows filesystems, do not forget to double all your backslashes.

Xaja cache server URL parameter

The last important parameter is $xaja_cache_server_url

Xaja comes bundled with a Cache Server. Although optionnal, the Cache Server can help you store objects that you often use in memory, so that they can be retrieved quickly. Typically, a Cache System can save numerous database calls, and will help you to improve your application performance.

In order to run, the Cache System needs to have a Cache Server running. The Cache Server is configured in the same way the Xaja Broker is configured. Therefore, you need to specify listening port, either using TCP or IPC sockets. This port MUST BE different from the Xaja broker port.

The Xaja Cache Server URL can be either a IPC pipe (for Unix systems only) or a TCP url. An IPC pipe is a non existing file on your file system that can be written by the Apache process.
For instance: /tmp/cache_server might be a valid one.
A TCP url is pointing to a TCP port on a local or distant machine and should start with "tcp://" For instance, tcp://127.0.0.1:4141 might be valid is the 4141 port is not used on your machine.

Additional steps

Additionaly, you might want to change some settings in your php.ini file.

Especially, if you haven't changed the default value for memory settings, you might want to increase the maximum memory per process to at least 32 MB. This can soon be useful in Xaja because a Xaja process has a longer life than a typical PHP process. So you can just change the memory_limit parameter, for instance to

memory_limit = 32M

If you plan to use extensively the Cache Server, you will probably want to extend the memory limit much beyond that value, or maybe even to disable this memory limit.

Another essential step to take is to enable the logging of errors in your php.ini file. In order to provide a tag library, Xaja uses a PHP feature named output buffering. To make things short, the drawback of this feature is that if a fatal error occurs during the process, nothing is displayed on the screen, making it very hard to pinpoint the bugs. Hopefully, you can log any fatal error by editing your php.ini file and turning on the property:

log_errors = On

By default, the errors will be appended to your Apache logfile. If you are running a standard Linux system, you should find these logs in /var/log/apache2/error.log or in /var/log/httpd/error.log.

Finally, you might really want to have a proper development environment with debugging enabled. This is always extremely handy, especially with output buffers, so you might want to follow this tutorial on XDebug installation.

Tips to using error logs efficiently

On Unix/Linux systems, you can use the tail command to see any new line added to the error logs. For instance, the command

tail -f /var/log/apache2/error.log

will stall and display any new line added to the error.log file.

While developping, it is always useful to have a command line window with a tail running.