hphp/doc/server.rpc_server

   1
   2 <h2> How to execute a PHP function over network</h2>
   3
   4 1. Parameters
   5
   6 When RPC server is turned on, HipHop server will listen on a port that takes
   7 RPC requests in a format like this,
   8
   9   http://[server]:[port]/function_name?params=...
  10
  11 "params" needs to be a JSON encoded array. The server will execute the function
  12 and return its result.
  13
  14 Alternatively, one can pass in one parameter a time like this,
  15
  16   http://[server]:[port]/function_name?p=[json value]&p=[json value]...
  17
  18 Each "p" is sequentially fed into the function as its first parameter, second
  19 parameter, etc.. Each parameter needs to be encoded in JSON separately.
  20
  21 There is also an "auth" parameter that needs to be passed in, if server is
  22 configured to authenticate with a simple password. It would normally be a
  23 password specified in /hphp/config.hdf under Satellites.rpc.Password.
  24
  25 2. States
  26
  27 Note that RPC server is considerably faster than an ajax page request, because
  28 it has made an assumption that the function needed to run this way is "pure" or
  29 "stateless", without leaving bad global states to subsequent calls. With this
  30 assumption, the server only initializes libraries once and it will execution
  31 multiple function calls (the number is configurable) within the same loop.
  32 This is very similar to FastCGI's paradigm.
  33
  34 If you need to call a function that leaves bad states to other functions,
  35 please add "reset=1" to the parameter, so the states can be thrown away after
  36 the function is called:
  37
  38   http://[server]:[port]/function_name?reset=1&...
  39
  40 3. Returns
  41
  42 If stdout is needed in addition to function's return, use "output=2", and
  43 HTTP response is a JSON encoded array like this,
  44
  45   array {
  46     "return" => [function's return]
  47     "output" => [stdout from echos or prints]
  48   }
  49
  50 If function's return is not needed, use "output=1" to turn it off. Then HTTP
  51 response is stdout's output (from echos and prints) without JSON encoding.
  52
  53 If none is needed, use "output=-1" to suppress them. Then an empty string will
  54 be returned. This may be useful, if the function is not a query but an action.
  55
  56 If more complete information about the return value is needed, use "output=3"
  57 to obtain a PHP-serialized string.
  58
  59 By default, "output=0" and function's return is encoded in JSON response.
  60
  61 To summarize,
  62
  63 0: (default) just function's return in JSON encoding
  64 1: just stdout as a string without JSON encoding
  65 2: both function's return and stdout in a JSON encoded array
  66 3: just function's return with PHP serialization
  67 -1: none
  68
  69 4. File invocation
  70
  71 RPC server now supports direct invocation of a PHP file, under the same
  72 assumption that the request is stateless.
  73
  74 There are two cases. First, the purpose of the RPC call is still to invoke a
  75 function, but the definition of the function is in a file that is not in the
  76 normal initialization path, defined by the RequestInitDocument. In order to
  77 invoke the function reliably, you can add "include=..." or "include_once=..."
  78 to the request:
  79
  80   http://[server]:[port]/function_name?include_once=file_name.php&...
  81
  82 The difference between include and include_once here is just like that in
  83 normal PHP scripts. A file that is included once on an RPC request will only
  84 execute once for the entire life time of an RPC request handler.
  85
  86 The second case is that you can directly invoke a file, without calling a
  87 function:
  88
  89   http://[server]:[port]/?include=file_name.php&...
  90
  91 or just
  92
  93   http://[server]:[port]/file_name.php?...
  94
  95 In this case, you would probably want to use "output=1" for the file
  96 invocation, as a file does not return a value. You would also want to
  97 use "include=...", rather than "include_once=...".