3.10 Writing an Ice Application with PHP

This section shows how to create an Ice client application with PHP.

Compiling a Slice Definition for PHP

The first step in creating our PHP application is to compile our Slice definition to generate PHP code. You can compile the definition as follows:¹

$ slice2php Printer.ice

The slice2php compiler produces a single source file, Printer.php, from this definition. The exact contents of the source file do not concern us for now—it contains the generated code that corresponds to the Printer interface we defined in Printer.ice.

Writing a Client

The client code, in Client.php, is shown below in full:

<?php
require 'Ice.php';
require 'Printer.php';

$ic = null;
try
{
    $ic = Ice_initialize();
    $base = $ic‑>stringToProxy("SimplePrinter:default ‑p 10000");
    $printer = Demo_PrinterPrxHelper::checkedCast($base);
    if(!$printer)
        throw new RuntimeException("Invalid proxy");

    $printer‑>printString("Hello World!");
}
catch(Exception $ex)
{
    echo $ex;
}

if($ic)
{
    // Clean up
    try
    {
        $ic‑>destroy();
    }
    catch(Exception $ex)
    {
        echo $ex;
    }
}
?>

The program begins with require statements to load the Ice run-time defini­tions (Ice.php) and the code we generated from our Slice definition in the previous section (Printer.php).

The body of the main program contains a try block in which we place all the client code, followed by a catch block. The catch block catches all exceptions that may be thrown by the code; the intent is that, if the code encounters an unex­pected run-time exception anywhere, the stack is unwound all the way back to the main program, which prints the exception and then returns failure to the operating system.

The body of our try block goes through the following steps:

1. We initialize the Ice run time by calling Ice_initialize. The call to initialize returns an Ice::Communicator reference, which is the main handle to the Ice run time.

2. The next step is to obtain a proxy for the remote printer. We create a proxy by calling stringToProxy on the communicator, with the string "SimplePrinter:default ‑p 10000". Note that the string contains the object identity and the port number that were used by the server. (Obvi­ously, hard-coding object identities and port numbers into our applications is a bad idea, but it will do for now; we will see more architecturally sound ways of doing this in Chapter 38.)

3. The proxy returned by stringToProxy is of type Ice::ObjectPrx, which is at the root of the inheritance tree for interfaces and classes. But to actually talk to our printer, we need a proxy for a Demo::Printer interface, not an Object interface. To do this, we need to do a down-cast by calling Demo_PrinterPrxHelper::checkedCast. A checked cast sends a message to the server, effectively asking “is this a proxy for a Demo::Printer interface?” If so, the call returns a proxy narrowed to the Printer interface; otherwise, if the proxy denotes an interface of some other type, the call returns null.

4. We test that the down-cast succeeded and, if not, throw an exception that terminates the client.

5. We now have a live proxy in our address space and can call the print­String method, passing it the time-honored "Hello World!" string. The server prints that string on its terminal.

Before the code exits, it destroys the communicator (if one was created success­fully). Doing this is essential in order to correctly finalize the Ice run time. If a script neglects to destroy the communicator, Ice destroys it automatically.

Running the Client

The server must be started before the client. Since Ice for PHP does not support server-side behavior, we need to use a server from another language mapping. In this case, we will use the C++ server (see Chapter 9):

$ server

At this point, we won’t see anything because the server simply waits for a client to connect to it. We run the client in a different window using PHP’s command-line interpreter:

$ php -f Client.php
$

The client runs and exits without producing any output; however, in the server window, we see the "Hello World!" that is produced by the printer. To get rid of the server, we interrupt it on the command line for now. (We will see cleaner ways to terminate a server in Chapter 24.)

If anything goes wrong, the client will print an error message. For example, if we run the client without having first started the server, we get something like the following:

exception ::Ice::ConnectionRefusedException
{
    error = 111
}

Note that, to successfully run the client, the PHP interpreter must be able to locate the Ice extension for PHP. See the Ice for PHP installation instructions for more information.

---

1

Whenever we show Unix commands in this book, we assume a Bourne or Bash shell. The commands for Windows are essentially identical and therefore not shown.