phpBeans Protocol Specification

Sunday, September 26, 2004; by John Luxford.

This specification documents the phpBeans protocol 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) protocol that works over a TCP/IP connection.

A phpBeans request message is a URI-formatted string. A phpBeans response message is a PHP serialized data structure. A remote object executes the appropriate method on the server.

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

Example

Here's an example of a simple server uptime request:

(Client initiates connection to server on port 3843)

SERVER: s:8:"identify";

CLIENT: USER/PASS

SERVER: s:7:"welcome";

CLIENT: server/uptime

SERVER: S:19:"2004-09-05 13:01:37";

CLIENT: quit

SERVER: s:7:"goodbye";

(Connection is closed by both parties)

Request Format

Requests use a URI-compatible format, where the protocol identifier is optional. There are three types of requests that can be sent from the client:

Authentication request

The authentication request contains the username followed by a forward-slash (/) followed by the password. If either the username or the password contain illegal URI values, they must be encoded according to the URI specification.

Method request

Method requests always begin with the object name followed by a forward-slash (/) followed by the method name. Method parameters are passed after a question-mark (?) and are separated by ampersands (&). Parameters have both a name and a value, which are separated by an equal sign (=). Values containing illegal URI values must be encoded according to the URI specification.

Array and list values can be passed by specifying the list name separately for each value, followed by square brackets ([]) which may be left empty, or contain the key as a number or as a letter.

Quit

When the client is finished a session, it sends the request "quit" to the server and closes the connection.

Examples of Valid Requests

joe_user/my_pass

server/uptime

server/listMethods

server/methodInfo?name=uptime

server/say?text=hello+world

server/say?text[1]=hello&text[2]=world

quit

Session Flow

1. The server sends the encoded string "identify" to all new connections.

2. In response, the first message sent by the client is their username followed by a forward-slash followed by their password.

3. If the server successfully identifies the client, the server issues an encoded "welcome" string. If the server does not successfully identify the client, it will issue a php_bean_error object as a response, which encoded looks like this:

O:14:"php_bean_error":2:{s:7:"message";s:19:"Invalid.  Try again";s:4:"code";i:-1;}

This instructs the client to repeat step 2.

4. The client is now able to issue method requests to the server. For each method request, either the return value of that method is sent as a response, or in case of an error, a php_bean_error object is sent instead, containing an error message and error code.

5. When a client has finished executing remote methods on the server, it issues a "quit" command. The server issues an encoded "goodbye" string as a response and then closes its connection to the client. The client may wait for the server or exit immediately after sending the "quit" command.

Response Format

The response format of the server is the same as that used by the PHP programming language's built-in serialize() and unserialize() functions. This format can be used to serialize the most complex of objects or data structures into a single string that can be later unserialized into the identical object or data structure. And since it's built into PHP already, a simple format, and a terse format, it is well suited for phpBeans server responses.

The response format serializes variables as follows. The variable type is abbreviated into a single letter initial. These are as follows:

• i - Integer
• d - Float/Decimal
  
• s - String
• b - Boolean
• N - Null
• a - Array
• O - Object

The rest of the formatting depends on the variable type. Each type is explained below.

Integers

Integers begin with an "i" followed by a colon (:) followed by the integer value followed by a semi-colon (;). So the number 2 becomes:

i:2;

Float/Decimal

d:3.79999999999999982236431605997495353221893310546875;

Strings

Strings begin with an "s" followed by a colon (:) followed by the length of the string followed by a colon (:) followed by the string surrounded by double-quotes (") followed by a semi-colon (;). So the string "string" becomes:

s:6:"string";

Additional double-quotes or semi-colons inside the string do not need to be quoted, since the length value determines how long the string is beforehand.

Boolean Values

Boolean values begin with a "b" followed by a colon (:) followed by an integer representing the true or false states of the variable followed by a semi-colon (;). The integer 1 means true, while the integer 0 means false. So a boolean true becomes:

b:1;

Null Values

Null values begin with an "N" followed by a semi-colon (;). So a null value becomes:

N;

Arrays

Arrays begin with an "a" followed by a colon (:) followed by the length of the array followed by a colon (:) followed by an open curly brace ({) followed by additional encoded values which are the contents of the array, including both the keys and the values, followed by a closing curly brace (}). So an empty array becomes:

a:0:{}

A one-item array with a numeric key and a string value "string" becomes:

a:1:{i:0;s:6:"string";}

Objects

Objects begin with an "O" followed by a colon (:) followed by the length of the class name of the object followed by a colon (:) followed by the name of the object's class surrounded in double-quotes (") followed by a colon (:) followed by the number of properties of the object followed by a colon (:) followed by an open curly brace ({) followed by the alternating encoded property names and values followed by a closing curly brace (}). So an empty object of type "foo" becomes:

O:3"foo":0:{}

An object of the class "bar" with properties "bar" and "asdf", containing the values Null and "qwerty" respectively, becomes:

O:3:"bar":2:{s:3:"bar";N;s:4:"asdf";s:6:"qwerty";}

Additional Examples

Authentication Failure

SERVER: s:8:"identify";

CLIENT: USER/WRONG_PASS

SERVER: O:14:"php_bean_error":2:{s:7:"message";s:19:"Invalid.  Try again";s:4:"code";i:-1;}

CLIENT: USER/CORRECT_PASS

SERVER: s:7:"welcome";

CLIENT: quit

SERVER: s:7:"goodbye";

(Connection is closed by both parties)

Object Error

SERVER: s:8:"identify";

CLIENT: USER/PASS

SERVER: s:7:"welcome";

CLIENT: server/upthyme

SERVER: O:14:"php_bean_error":2:{s:7:"message";s:18:"Unsupported Method";s:4:"code";i:-1;}

CLIENT: server/uptime

SERVER: s:19:"2004-09-18 22:31:08";

CLIENT: quit

SERVER: s:7:"goodbye";

(Connection is closed by both parties)

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 complementary 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 server API specification also defines methods for auto-discovering which objects are available to the client, as well as which methods are available from each object.

Speed. We wanted a concise, simple communication layer for language-agnostic n-tier application development. 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 protocol 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