phpBeans Client API Specification

Saturday, November 28, 2004; by John Luxford.

This specification documents the phpBeans client API implemented at www.phpbeans.com.

For a non-technical explanation, see our tutorial section.

This page provides all the information that an implementor needs.

Overview

phpBeans is a Remote Method Invocation (RMI) platform that works over a TCP/IP connection.

A phpBeans client makes a request to a phpBeans-compliant server using the phpBeans protocol. The server then determines which object and method to pass your request to, and returns the method response to the client. The client then parses the response and takes appropriate action.

Method parameters can be scalars, numbers, strings, dates, etc.; and can also be records and lists.

The phpBeans client API specification defines a series of "default" methods that should be implemented in a standard manner across all phpBeans client implementations. These methods should ensure a high degree of portability between different phpBeans client API implementations.

Client Class

The phpBeans client class should be named PHP_Bean_Client, and should provide the following public properties and methods:

Properties

string $server = 'localhost'

Server name or IP address.

integer $port = 3843

Server port number.

integer $timeout = 15

Socket timeout for connection and requests.

integer $errno

Error number when an error occurs.

string $error

Error message when an error occurs.

array $log

Log of communication between the client and the server.

boolean $logging = false

Whether to keep a log of the communication or not.

Methods

PHP_Bean_Client(string $server = 'localhost', integer $port = 3843, integer $timeout = 15) -> object

This is the constructor method of the object.

connect() -> boolean

Connects to the server specified to the constructor.

authenticate(string $user, string $pass) -> boolean

Authenticates the client with the server.

getObject(string $name) -> object

Creates a local object that mimicks the specified server-side object, allowing for transparent remote method invocations to occur in a seamless manner.

call(string $request) -> mixed

Calls a method on a remote object.

disconnect() -> void

Disconnects from the server.

Error Handling

In addition to the PHP_Bean_Client object, the following object should be defined so that it can be returned in case of an error on the server.

PHP_Bean_Error

PHP_Bean_Error is an object that is returned when an error occurs within any server-side object. It contains two properties, but no methods. It is never accessed directly via a phpBeans client request, but is returned as a possible value from any server response.

The PHP_Bean_Error has the following properties:

integer $code

The error code, which can be used to identify and handle similar errors. All errors occurring in the server itself, such as unknown object errors, have a code of -1.

string $message

The error message, which contains a brief description of the error that occurred.

Examples

The following examples are written in the PHP programming language, however there should be no issues with porting both this specification and these examples to other programming languages.

<?php

include_once ('Bean.php');

// connect to the server

$client = new PHP_Bean_Client ('localhost', 3843, 2);
if (! $client->connect ()) {
	die ($client->error);
}

// authenticate yourself
if (! $client->authenticate ($user, $pass)) {
	die ($client->error);
}

// call a method using the literal query syntax

$res = $client->call ('server/uptime');
if (! $res) {
	die ($client->error);
}

echo 'Server up since: ' . $res;

// or use a local object to alias a server-side one

$server =& $client->getObject ('server');

echo 'Server up since: ' . $server->uptime ();

// and finally, disconnect

$client->disconnect ();

?>

Strategies/Goals

Simplicity and transparency. We wanted a standard that allowed both object and client writers to be able to work with as few encumbrances as possible. The server API specification defines the necessary reflection methods that make it possible to replicate server-side objects as closely as possible on the client side. The protocol specification provides a light-weight and easy-to-implement communication layer for clients and servers to talk to one another. This simplicity is also a key component to ensuring the security of the phpBeans protocol and server API specifications, since a simpler standard is more easily verifiable.

Speed. We wanted a concise, straight-forward set of objects necessary for solving common problems. Speed of execution, communication, as well as speed of development are all important factors.

Ease of implementation. We also wanted it to be an easy to implement API that could quickly be adapted to run in other environments, on other operating systems, and in other programming languages.

Copyright and Disclaimer

© Copyright 2004 Simian Systems Inc. All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and these paragraphs are included on all such copies and derivative works.

This document may not be modified in any way, such as by removing the copyright notice or references to Simian Systems or other organizations. Further, while these copyright restrictions apply to the written phpBeans specification, no claim of ownership is made by Simian Systems to the protocol it describes. Any party may, for commercial or non-commercial purposes, implement this protocol without royalty or license fee to Simian Systems. The limited permissions granted herein are perpetual and will not be revoked by Simian Systems or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and SIMIAN SYSTEMS INC. DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Return to Top