当前位置: 首页 > 工具软件 > TARS > 使用案例 >

tars-php文档,TarsPHP - tars-extension - 《Tars 1.8 使用手册》 - 书栈网 · BookStack

颜宸
2023-12-01

tars-extension

phptars 扩展使用说明

php扩展能力说明

为了在扩展中实现tars打包解包和tup编码解码的全部体系,所以php扩展主要做了三件事情:将tars的所有数据结构进行了扩展类型的映射

将tars的三种复杂类型进行了特殊的扩展类型的映射

提供了tup和tars协议的打包解包与编码解码的能力。

基本类型的映射

如下是我们对基本类型的映射:bool=>\TARS::BOOL

char=>\TARS::CHAR

uint8=>\TARS::UINT8

short=>\TARS::SHORT

uint16=>\TARS::UINT16

float=>\TARS::FLOAT

double=>\TARS::DOUBLE

int32=>\TARS::INT32

uint32=>\TARS::UINT32

int64=>\TARS::INT64

string=>\TARS::STRING

vector=>\TARS::VECTOR

map=>\TARS::MAP

struct=>\TARS::STRUCT

当我们需要标识具体的变量类型的时候,就需要用到这些基本的类型了,这些类型都是常量,从1-14。

复杂类型的映射

针对vector、map、struct三种基本的类型,有一些特殊的打包解包的机制,因此需要引入特别的数据类型: vector:vector=>\TARS_VECTOR

它同时具有两个成员函数pushBack()和push_back()

入参为取决于vector本身是包含什么类型的数组

例如:

$shorts=["test1","test2"];

$vector=new\TARS_VECTOR(\TARS::STRING);//定义一个string类型的vector

foreach($shortsas$short){

$vector->pushBack($short);//依次吧test1,test2两个元素,压入vector中

}

map:map=>\TARS_MAP

它同时具有两个成员函数pushBack()和push_back()

入参为取决于map本身包含什么类型

例如:

$strings=[["test1"=>1],["test2"=>2]];

$map=new\TARS_MAP(\TARS::STRING,\TARS::INT64);//定义一个key为string,value是int64的map

foreach($stringsas$string){

$map->pushBack($string);//依次把两个元素压入map中,注意pushBack接收一个array,且array只有一个元素

}

struct:struct=>\TARS_Struct

struct的构造函数比较特殊,接收classname和classfields两个参数

第一个描述名称,第二个描述struct内的变量的信息

例如:

classSimpleStructextends\TARS_Struct{

constID=0;//TARS文件中每个struct的tag

constCOUNT=1;

public$id;//strcut中每个元素的值保存在这里

public$count;

protectedstatic$fields=array(

self::ID=>array(

'name'=>'id',//struct中每个元素的名称

'required'=>true,//struct中每个元素是否必须,对应tars文件中的require和optional

'type'=>\TARS::INT64,//struct中每个元素的类型

),

self::COUNT=>array(

'name'=>'count',

'required'=>true,

'type'=>\TARS::UINT8,

),

);

publicfunction__construct(){

parent::__construct('App_Server_Servant.SimpleStruct',self::$fields);

}

}

打包解包与编码解码

作为扩展的核心功能,就是提供tars的编解码和打包解包的能力:

打包解包// 针对基本类型的打包和解包的方法,输出二进制buf

// iVersion只有1和3两个版本,1版本时$nameOrTagNum需要传入tagNum,方法里面第一个参数为1第二个参数为2以此类推

// 3版本时$nameOrTagNum需要传入name,参数名

$buf=\TASAPI::put*($nameOrTagNum,$value,$iVersion=3)

$value=\TUPAPI::get*($nameOrTagNum,$buf,$isRequire=false,$iVersion=3)

// 针对struct,传输对象,返回结果的时候,以数组的方式返回,其元素与类的成员变量一一对应

$buf=\TUPAPI::putStruct($nameOrTagNum,$clazz,$iVersion=3)

$result=\TUPAPI::getStruct($nameOrTagNum,$clazz,$buf,$isRequire=false,$iVersion=3)

// 针对vector,传入完成pushBack的vector

$buf=\TUPAPI::putVector($nameOrTagNum,TARS_Vector $clazz,$iVersion=3)

$value=\TUPAPI::getVector($nameOrTagNum,TARS_Vector $clazz,$buf,$isRequire=false,$iVersion=3)

// 针对map,传入完成pushBack的map

$buf=\TUPAPI::putMap($nameOrTagNum,TARS_Map $clazz,$iVersion=3)

$value=\TUPAPI::getMap($nameOrTagNum,TARS_Map $clazz,$buf,$isRequire=false,$iVersion=3)

// 需要将上述打好包的数据放在一起用来编码

$inbuf_arr[$nameOrTagNum]=$buf

编码解码//针对tup协议(iVersion=3)的情况:

//这种情况下客户端发包用encode编码,服务端收包用decode解码,服务端回包用encode编码,客户端收包用decode解码

// 进行tup协议的编码,返回结果可以用来传输、持久化

$reqBuffer=\TUPAPI::encode(

$iVersion=3,

$iRequestId,

$servantName,

$funcName,

$cPacketType=0,

$iMessageType=0,

$iTimeout,

$context=[],

$statuses=[],

$bufs)

// 进行tup协议的解码

$ret=\TUPAPI::decode($respBuffer,$iVersion=3)

$code=$ret['iRet']

$buf=$ret['sBuffer']

//针对tars协议(iVersion=1)的情况:

//这种情况下客户端发包用encode编码,服务端收包用decodeReqPacket解码,服务端回包用encodeRspPacket编码,客户端收包用decode解码

//客户端发包

$reqBuffer=\TUPAPI::encode(

$iVersion=1,

$iRequestId,

$servantName,

$funcName,

$cPacketType=0,

$iMessageType=0,

$iTimeout,

$context=[],

$statuses=[],

$bufs)

//服务端收包,解包

$ret=\TUPAPI::decodeReqPacket($respBuffer)

$code=$ret['iRet']

$buf=$ret['sBuffer']

//服务端回包,打包encodeRspPacket

$reqBuffer=\TUPAPI::encodeRspPacket(

$iVersion=1,

$cPacketType,

$iMessageType,

$iRequestid,

$iRet=0,

$sResultDesc='',

$bufs,

$statuses=[])

//客户端收包,解包

$ret=\TUPAPI::decode($respBuffer,$iVersion=1)

$code=$ret['iRet']

$buf=$ret['sBuffer']

对于不同类型的结构的打包解包的更丰富的使用请参考tests/

tars2php(自动生成php类工具)使用说明

请参见tars2php模块下的文档说明: 详细说明

测试用例

phpunite版本的测试用例

针对扩展的常见使用,增加了测试用例,位于/ext/testcases文件夹下, 测试时只需要执行php phpunit-4.8.36.phar test.php 即可完成所有测试用例的执行。其中覆盖到了:所有基本类型的打包解包和编码的测试

简单struct类型打包解包和编码的测试

简单vector类型的打包解包和编码的测试

简单map类型的打包解包和编码的测试

复杂vector类型(包含非基本数据类型)的打包解包和编码的测试

复杂map类型(包含非基本数据类型)的打包解包和编码的测试

复杂struct类型(嵌套vector和map)的打包解包和编码的测试

另外testTARSClient.php和testTARSServer.php是tars协议(iVersion=1)情况下客户端发包,服务端解包 和 服务端回包,客户端解包的测试用例。

注意,需要自行下载phpunit的可执行文件,或直接使用预先安装好的phpunit工具,进行单元测试。

同时指出phpt版本的测试用例

安装完成扩展后,执行make test即可。

 类似资料: