phpBeans Server API Specification

Saturday, November 27, 2004; by John Luxford.

This specification documents the phpBeans server 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 request is made to a phpBeans-compliant server, which determines which object and method to pass your request to, and returns the method response to the client, using the phpBeans protocol.

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

The phpBeans server API specification defines a series of "default" objects and methods that should be implemented in a standard manner across all phpBeans server implementations.

Objects

All phpBeans server-side objects inherit from the PHP_Bean object, which provides standard persistence mechanisms and object introspection facilities for the client to auto-discover your objects. Additionally, objects are defined for querying the server about itself, the server access logs, and for managing user access privileges to the server.

PHP_Bean

PHP_Bean is the base object from which all PHP beans inherit. Its goal is to provide standard capabilities for object and method introspection and persistence. As such, it is never called directly, but its methods are available to all server-side objects.

The PHP_Bean object implements the following methods:

listMethods() -> array

Retrieves the list of methods accessible from the current object.

hasMethod(string $name) -> boolean

Determines whether the specified method is provided by the current object.

methodInfo(string $name) -> array

Returns a hash with the name, description, parameters array, and return type of the specified method.

objectInfo() -> array

Returns a hash with all of the public methods.

store(string $id = '') -> boolean

Saves the state of the current object.

fetch(string $id = '') -> object

Fetches the last saved state of the current object.

delete(string $id = '') -> boolean

Deletes the current object from storage.

restore(string $id = '') -> boolean

Restores the state of the current object from storage.

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.

Server

The Server object provides access to the basic server information, and provides the following methods:

uptime() -> string

Returns the date and time that the server was last started. The format of the return value is 2004-05-23 13:51:02 (Year-Month-Day Hour:Minute:Second).

say() -> string

Repeats any value it's given.

listObjects() -> array

Returns a list of objects that the current client has access to.

Log

The Log object provides methods for querying the server access log, for the purposes of reporting, statistical analysis, and performance profiling. It provides the following methods:

listAll(string $request, integer $start, integer $end) -> array

Returns all of the request for the specified request field (one of 'user', 'object', 'method', or 'host') for the specified time range.  Both times must be specified in Unix timestamp format.  The return value is a 2-dimensional array with the inner arrays containing the keys 'name' and 'total' representing each result item.

countAll() -> integer

Returns the total number of requests for the specified time range.

clearAll() -> boolean

Clears all entries from the access log.

User

The User object provides methods for managing user access privileges to the object server. It provides the following methods:

add(string $name, string $pass, string $host = '*', string $objects = '*') -> boolean

Adds a user to the system. User permissions can be restricted to specific remote host names/IP addresses, specified as a comma-separated list. '*' means 'any host'. Users can also be restricted to specific objects, specified as a comma-separated list of object names. '*' means 'all objects'.

edit(string $name, string $new_pass) -> boolean

Modifies a user in the system.

delete(string $name) -> boolean

Deletes a user from the system.

grant(string $name, string $object) -> boolean

Grants a user access to the specified object.

revoke(string $name, string $object) -> boolean

Revokes a user's access to the specified object.

listAll() -> array

Lists all of the users in the system.

userInfo(string $name) -> array

Retrieves the user, password, host, and objects info for the specified user.

Examples

server/listObjects

server/uptime

log/countAll

user/listMethods

user/add?name=admin&pass=admin&host=*&objects=*

user/hasMethod?name=add

user/methodInfo?name=revoke

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