
<h2> How to execute a PHP function over network</h2>

1. Parameters

When RPC server is turned on, HipHop server will listen on a port that takes
RPC requests in a format like this,

  http://[server]:[port]/function_name?params=...

"params" needs to be a JSON encoded array. The server will execute the function
and return its result.

Alternatively, one can pass in one parameter a time like this,

  http://[server]:[port]/function_name?p=[json value]&p=[json value]...

Each "p" is sequentially fed into the function as its first parameter, second
parameter, etc.. Each parameter needs to be encoded in JSON separately.

There is also an "auth" parameter that needs to be passed in, if server is
configured to authenticate with a simple password. It would normally be a
password specified in /hphp/config.hdf under Satellites.rpc.Password.

2. States

Note that RPC server is considerably faster than an ajax page request, because
it has made an assumption that the function needed to run this way is "pure" or
"stateless", without leaving bad global states to subsequent calls. With this
assumption, the server only initializes libraries once and it will execution
multiple function calls (the number is configurable) within the same loop.
This is very similar to FastCGI's paradigm.

If you need to call a function that leaves bad states to other functions,
please add "reset=1" to the parameter, so the states can be thrown away after
the function is called:

  http://[server]:[port]/function_name?reset=1&...

3. Returns

If stdout is needed in addition to function's return, use "output=2", and
HTTP response is a JSON encoded array like this,

  array {
    "return" => [function's return]
    "output" => [stdout from echos or prints]
  }

If function's return is not needed, use "output=1" to turn it off. Then HTTP
response is stdout's output (from echos and prints) without JSON encoding.

If none is needed, use "output=-1" to suppress them. Then an empty string will
be returned. This may be useful, if the function is not a query but an action.

If more complete information about the return value is needed, use "output=3"
to obtain a PHP-serialized string.

By default, "output=0" and function's return is encoded in JSON response.

To summarize,

0: (default) just function's return in JSON encoding
1: just stdout as a string without JSON encoding
2: both function's return and stdout in a JSON encoded array
3: just function's return with PHP serialization
-1: none

4. File invocation

RPC server now supports direct invocation of a PHP file, under the same
assumption that the request is stateless.

There are two cases. First, the purpose of the RPC call is still to invoke a
function, but the definition of the function is in a file that is not in the
normal initialization path, defined by the RequestInitDocument. In order to
invoke the function reliably, you can add "include=..." or "include_once=..."
to the request:

  http://[server]:[port]/function_name?include_once=file_name.php&...

The difference between include and include_once here is just like that in
normal PHP scripts. A file that is included once on an RPC request will only
execute once for the entire life time of an RPC request handler.

The second case is that you can directly invoke a file, without calling a
function:

  http://[server]:[port]/?include=file_name.php&...

or just

  http://[server]:[port]/file_name.php?...

In this case, you would probably want to use "output=1" for the file
invocation, as a file does not return a value. You would also want to
use "include=...", rather than "include_once=...".