Book/yar-Phpdoc专题

Yet Another RPC Framework

简介
安装／配置
预定义常量
范例
Yar_Server — The Yar_Server class
- Yar_Server::__construct — 创建一个HTTP RPC Server
- Yar_Server::handle — 启动HTTP RPC Server
Yar_Client — The Yar_Client class
- Yar_Client::__call — 调用远程服务
- Yar_Client::__construct — 创建一个客户端实例
- Yar_Client::setOpt — 设置调用的配置
Yar_Concurrent_Client — The Yar_Concurrent_Client class
- Yar_Concurrent_Client::call — 注册一个并行的服务调用
- Yar_Concurrent_Client::loop — 发送所有注册的并行调用
- Yar_Concurrent_Client::reset — Clean all registered calls
Yar_Server_Exception — The Yar_Server_Exception class
- Yar_Server_Exception::getType — 获取异常的原始类型
Yar_Client_Exception — The Yar_Client_Exception class
- Yar_Client_Exception::getType — The getType purpose

简介

类摘要

Yar_Server

class Yar_Server {

/* 属性 */

protected $_executor ;

/* 方法 */

final public __construct ( Object $obj )

public boolean handle ( void )

}

属性

_executor

Yar_Server::__construct

创建一个HTTP RPC Server

说明

final public Yar_Server::__construct ( Object $obj )

创建一个Yar的HTTP RPC服务，参数 $obj 对象的所有公开方法都会被注册为服务函数，可以被RPC调用。

参数

obj
一个对象实例, 这个对象的所有公开方法都会被注册为服务函数.

返回值

返回一个Yar_Server的实例。

范例

示例 #1 Yar_Server::__construct示例

<?php
class API {
    /**
     * the doc info will be generated automatically into service info page.
     * @params 
     * @return
     */
    public function some_method($parameter, $option = "foo") {
         return "some_method";
    }

    protected function client_can_not_see() {
    }
}

$service = new Yar_Server(new API());
$service->handle();
?>

以上例程的输出类似于：

参见

Yar_Server::handle

Yar_Server::handle

启动HTTP RPC Server

说明

public boolean Yar_Server::handle ( void )

启动服务, 开始接受客户端的调用请求.

Note:

来自客户端的调用, 都是通过POST请求发送过来的. 如果一个GET请求访问到这个Server, 那在yar.expose_info开启的情况下, 这个服务的Server Info信息会被展现.

参数

此函数没有参数。

返回值

boolean

范例

示例 #1 Yar_Server::handle示例

<?php
class API {
    /**
     * the doc info will be generated automatically into service info page.
     * @params 
     * @return
     */
    public function some_method($parameter, $option = "foo") {
    }

    protected function client_can_not_see() {
    }
}

$service = new Yar_Server(new API());
$service->handle();
?>

以上例程的输出类似于：

参见

Yar_Server::__construct

简介

类摘要

Yar_Client

class Yar_Client {

/* 属性 */

protected $_protocol ;

protected $_uri ;

protected $_options ;

protected $_running ;

/* 方法 */

public void __call ( string $method , array $parameters )

final public __construct ( string $url )

public boolean setOpt ( number $name , mixed $value )

}

属性

_protocol

_uri

_options

_running

Yar_Client::__call

调用远程服务

说明

public void Yar_Client::__call ( string $method , array $parameters )

发起一个RPC调用, 并且得到返回值. 如果服务端的远程调用抛出异常, 那么本地也会相应的抛出一个Yar_Server_Exception异常.

参数

method
远程服务的名字.

parameters
调用参数.

返回值

范例

示例 #1 Yar_Client::__call example

<?php

$client = new Yar_Client("http://host/api/");

/* 调用远程服务的some_method服务 */
$result = $client->some_method("parameter");

?>

以上例程的输出类似于：

参见

Yar_Client::setOpt

Yar_Client::__construct

创建一个客户端实例

说明

final public Yar_Client::__construct ( string $url )

创建一个Yar_Client 到一个 Yar_Server的实例.

参数

url
服务端的HTTP URL路径.

返回值

Yar_Client实例.

范例

示例 #1 Yar_Client::__construct示例

<?php
$client = new Yar_Client("http://host/api/");
?>

以上例程的输出类似于：

参见

Yar_Client::__call
Yar_Client::setOpt

Yar_Client::setOpt

设置调用的配置

说明

public boolean Yar_Client::setOpt ( number $name , mixed $value )

设置调用远程服务的一些配置, 比如超时值, 打包类型等.

参数

name
可以是: YAR_OPT_PACKAGER, YAR_OPT_PERSISTENT (需要服务端支持keepalive), YAR_OPT_TIMEOUT, YAR_OPT_CONNECT_TIMEOUT

value

返回值

范例

示例 #1 Yar_Client::setOpt示例

<?php

$cient = new Yar_Client("http://host/api/");

//Set timeout to 1s
$client->SetOpt(YAR_OPT_CONNECT_TIMEOUT, 1000);

//Set packager to JSON
$client->SetOpt(YAR_OPT_PACKAGER, "json");

/* call remote service */
$result = $client->some_method("parameter");
?>

以上例程的输出类似于：

参见

Yar_Client::__call

简介

类摘要

Yar_Concurrent_Client

class Yar_Concurrent_Client {

/* 属性 */

static $_callstack ;

static $_callback ;

static $_error_callback ;

/* 方法 */

public static int call ( string $uri , string $method [, array $parameters [, callable $callback [, callable $error_callback [, array $options ]]]] )

public static boolean loop ([ callable $callback [, callable $error_callback ]] )

public static bool reset ( void )

}

属性

_callstack

_callback

_error_callback

Yar_Concurrent_Client::call

注册一个并行的服务调用

说明

public static int Yar_Concurrent_Client::call ( string $uri , string $method [, array $parameters [, callable $callback [, callable $error_callback [, array $options ]]]] )

注册一个并行的(异步的)远程服务调用, 不过这个调用请求不会被立即发出, 而是会在接下来调用 Yar_Concurrent_Client::loop的时候才真正的发送出去.

参数

uri
RPC 服务的 URI(http 或 tcp).

method
调用的服务名字(也就是服务方法名).

parameters
调用的参数.

callback
回调函数, 在远程服务的返回到达的时候被Yar调用, 从而可以处理返回内容.

返回值

唯一 ID，可用于区分到底是那个调用的返回.

范例

示例 #1 Yar_Concurrent_Client::call示例

<?php
function callback($retval, $callinfo) {
     var_dump($retval);
}

function error_callback($type, $error, $callinfo) {
    error_log($error);
}

Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback");
Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"));   // if the callback is not specificed, 
                                                                               // callback in loop will be used
Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback", NULL, array(YAR_OPT_PACKAGER => "json"));
                                                                               //this server accept json packager
Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback", NULL, array(YAR_OPT_TIMEOUT=>1));
                                                                               //custom timeout 

// 这个时候请求都还没有发出
?>

以上例程的输出类似于：

参见

Yar_Concurrent_Client::loop
Yar_Concurrent_Client::reset
Yar_Server::__construct
Yar_Server::handle

Yar_Concurrent_Client::loop

发送所有注册的并行调用

说明

public static boolean Yar_Concurrent_Client::loop ([ callable $callback [, callable $error_callback ]] )

发送所有的已经通过 Yar_Concurrent_Client::call注册的并行调用, 并且等待返回.

参数

callback
如果这个回掉函数被设置, 那么Yar在发送出所有的请求之后立即调用一次这个回掉函数(此时还没有任何请求返回), 调用的时候$callinfo参数是NULL.

如果在注册并行调用的时候制定了callback, 那么那个callback有更高的优先级.

error_callback
错误回掉函数, 如果设置了, 那么Yar在出错的时候会调用这个回掉函数.

返回值

范例

示例 #1 Yar_Concurrent_Client::loop example

<?php
function callback($retval, $callinfo) {
     if ($callinfo == NULL) {
        echo "现在, 所有的请求都发出去了, 还没有任何请求返回\n";
     } else {
              echo "这是一个远程调用的返回, 调用的服务名是", $callinfo["method"], 
                      ". 调用的sequence是 " , $callinfo["sequence"] , "\n";
        var_dump($retval);
     }
} 

function error_callback($type, $error, $callinfo) {
    error_log($error);
}

Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback");
Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"));   // if the callback is not specificed, 
                                                                               // callback in loop will be used
Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback", NULL, array(YAR_OPT_PACKAGER => "json"));
                                                                               //this server accept json packager
Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback", NULL, array(YAR_OPT_TIMEOUT=>1));
                                                                               //custom timeout 

Yar_Concurrent_Client::loop("callback", "error_callback"); //send the requests, 
                                                           //the error_callback is optional
?>

以上例程的输出类似于：

现在, 所有的请求都发出去了, 还没有任何请求返回
这是一个远程调用的返回, 调用的服务名是some_method, 调用的sequence是 4
string(11) "some_method"
这是一个远程调用的返回, 调用的服务名是some_method, 调用的sequence是 1
string(11) "some_method"
这是一个远程调用的返回, 调用的服务名是some_method, 调用的sequence是 2
string(11) "some_method"
这是一个远程调用的返回, 调用的服务名是some_method, 调用的sequence是 3
string(11) "some_method"

参见

Yar_Concurrent_Client::call
Yar_Server::__construct
Yar_Server::handle

Yar_Concurrent_Client::reset

Clean all registered calls

说明

public static bool Yar_Concurrent_Client::reset ( void )

Clean all registered calls

参数

返回值

范例

示例 #1 Yar_Concurrent_Client::reset example

以上例程的输出类似于：

参见

Yar_Concurrent_Client::call
Yar_Concurrent_Client::loop
Yar_Server::__construct
Yar_Server::handle

简介

If service threw exceptions, A Yar_Server_Exception will be threw in client side.

类摘要

Yar_Server_Exception

class Yar_Server_Exception extends Exception {

/* 属性 */

protected $_type ;

/* 方法 */

public string getType ( void )

/* 继承的方法 */

final public string Exception::getMessage ( void )

final public Throwable Exception::getPrevious ( void )

final public mixed Exception::getCode ( void )

final public string Exception::getFile ( void )

final public int Exception::getLine ( void )

final public array Exception::getTrace ( void )

final public string Exception::getTraceAsString ( void )

public string Exception::__toString ( void )

final private void Exception::__clone ( void )

}

属性

message

code

file

line

_type

Yar_Server_Exception::getType

获取异常的原始类型

说明

public string Yar_Server_Exception::getType ( void )

当服务端的服务函数抛出异常的时候, 客户端本地会响应的抛出一个Yar_Server_Exception异常. 有一个属性, 标明了服务端异常的类型. 这个方法就是获取这个异常类型.

参数

此函数没有参数。

返回值

string

范例

示例 #1 Yar_Server_Exception::getType示例

//Server.php
<?php
class Custom_Exception extends Exception {};

class API {
    public function throw_exception($name) {
        throw new Custom_Exception($name);
    }
}

$service = new Yar_Server(new API());
$service->handle();
?>

//Client.php
<?php
$client = new Yar_Client("http://host/api.php");

try {
    $client->throw_exception("client");
} catch (Yar_Server_Exception $e) {
    var_dump($e->getType());
    var_dump($e->getMessage());
}

以上例程的输出类似于：

string(16) "Custom_Exception"
string(6) "client"

参见

简介

类摘要

Yar_Client_Exception

class Yar_Client_Exception extends Exception {

/* 属性 */

/* 方法 */

public void getType ( void )

/* 继承的方法 */

final public string Exception::getMessage ( void )

final public Throwable Exception::getPrevious ( void )

final public mixed Exception::getCode ( void )

final public string Exception::getFile ( void )

final public int Exception::getLine ( void )

final public array Exception::getTrace ( void )

final public string Exception::getTraceAsString ( void )

public string Exception::__toString ( void )

final private void Exception::__clone ( void )

}

属性

message

code

file

line

Yar_Client_Exception::getType

The getType purpose

说明

public void Yar_Client_Exception::getType ( void )

Warning

本函数还未编写文档，仅有参数列表。

参数

此函数没有参数。

返回值

范例

示例 #1 Yar_Client_Exception::getType example

<?php

/* ... */

?>

以上例程的输出类似于：

...