TarsPHP 快速入门

1. 框架简介

2. 示例：搭建 Http 服务的 HelloWorld

3. 示例：搭建 Tars 服务的 HelloWorld

4. 示例：Tars HelloWorld 服务的客户端程序

5. 论坛邀请

1. 框架简介

tars-client

tars-client 中提供了对 tars 服务进行调用的 php 能力，包括：

调用远程服务的实例；
主调上报
自动寻址模块

tars-server

tars-server 提供了底层的 server 框架,同时支持如下特性

基于 swoole1.x/2.x 的高性能服务
支持 tup 协议和 tars 流两种协议模式
支持 http、tcp、timer 三种 server
上报、监控、日志的集成
tars 平台发布支持

tars-config

从 tars 平台的配置服务拉取配置文件的能力模块。

tars-deploy

进行 tars-server 业务代码打包的模块。

tars-extension

tars 底层依赖的 php 扩展代码

tars-log

tars 进行远程日志写入的模块

tars-monitor

tars 进行主调上报和特性上报的功能模块

tars-registry

tars 进行主控寻址的功能模块

tars-report

tars 进行 keep-alive 服务保活上报的模块

tars-utils

tars 进行配置文件解析的模块

tars2php

代码自动生成的工具,可以自动生成 server 和 client 端的代码。

2. 示例：搭建 Http 服务的 HelloWorld

目录结构说明

scripts 存储业务所需要的脚本,如 tars2php.sh 负责的就是根据 tars 文件,生成客户端所需要的代码
src 业务逻辑所在的目录,主要包含以下结构:
component: 存储 Controller 的基础类,方便所有的 Controller 公用
conf: 业务需要的配置, 这里只是给出一个 demo,如果从平台下发配置,默认也会写入到这个文件夹中;
controller: MVC 模型中的 C 层;
servant: 使用 tars2php 生成的 client 端的代码, 这个目录名称完全可以自定义,只需要在使用的时候加以区分就可以了;
composer.json: 说明项目的依赖情况
index.php: 整个服务的入口文件,这个文件名称可以自定义,但是必须要更改平台上的私有模板,增加 entrance 这个字段在 server 下面
services.php: 声明整个项目的基础 namespaceName
tars 这个 tcp 服务所依赖的就是这个文件夹下面的*.tars 文件而 tars.client.proto.php 文件,则是生成 servant 下代码所必须的,这个会在下面的 guideline 中具体说明。

服务部署 guideline

进入运维管理=> 模板管理

平台会提供一份新的针对 php 的模板,命名为 tars.tarsphp.default.

!!!!!!!必须首先修改其中 php 的执行路径!!!!!!!

其次有两种方式保证 http-server 使用正确的模板:
在平台上进入运维管理=>部署服务,填写对应的应用名和服务名称,注意,这个与下文中 tars 文件夹中的 tars.proto.php

需要完全一致。
选择服务类型为 tars_php
选择模板为 tars.tarsphp.default 服务模板,默认不启用 set
选择可用端口,填写服务器内网 ip. (可在运维管理=>节点管理中查看)
端口类型为 TCP

!!!!协议类型 HTTP 服务必须选择非 TARS!!!!!!
线程数对应 SWOOLE 的进程数
最大连接数和队列最大长度、队列超时时间,对 php 服务不生效
点击添加和提交即可,接下来请进入开发 guideline

服务部署

开发 guideline

新建对应的目录结构,固定为 scripts、src 和 tars
新建 src/composer.json 文件,内容如下:

{
  "name": "tars/helloworld/phphttp",
  "description": "tars php http hello world",
  "require": {
    "phptars/tars-server": "~0.2",
    "phptars/tars-deploy": "~0.1",
    "phptars/tars2php": "~0.1",
    "phptars/tars-log": "~0.1",
    "ext-zip": ">=0.0.1"
  },
  "autoload": {
    "psr-4": {
      "PHPHttp\\": "./"
    }
  },
  "minimum-stability": "stable",
  "scripts": {
    "deploy": "\\Tars\\deploy\\Deploy::run"
  },
  "repositories": {
    "packagist": {
      "type": "composer",
      "url": "https://mirrors.aliyun.com/composer/"
    }
  }
}

其中 name、description、autoload 中的 psr-4 可以修改为自己需要的,我们这里以此为例子。

新建 src/index.php ,内容如下:

<?php
/**
 * 框架启动的入口文件
 */
require_once __DIR__.'/vendor/autoload.php';

use \Tars\cmd\Command;

//php index.php  conf restart
$config_path = $argv[1];
$pos = strpos($config_path, '--config=');

$config_path = substr($config_path, $pos + 9);

$cmd = strtolower($argv[2]);

$class = new Command($cmd, $config_path);
$class->run();

这个文件负责进行启动和入口加载工作

新建 src/services.php 文件,内容如下:

<?php
// 以namespace的方式,在psr4的框架下对代码进行加载
return [
    // 请注意，这个Hello代表的就是部署服务时写的obj，
    // 如果不小心忘记了，可以在服务管理->服务管理=>HelloWorld=>PHPHttp=>管理servant中查看，
    // 管理Servant一栏写的HelloWorld.PHPHttp.Hello中的Hello就是你要的obj，这里的命名是AppName.ServerName.ObjName
    'Hello' => [
        'namespaceName' => 'PHPHttp\\', // psr4的根命名空间
        'saveTarsConfigFileDir' => 'src/conf/', //从tarsconfig拉下来的文件保存目录 默认src目录下的conf
        'saveTarsConfigFileName' => ['',], //需要从tarsconfig拉下来的文件名 在web上配置
        'monitorStoreConf' => [
            //使用redis缓存主调上报信息
            //'className' => Tars\monitor\cache\RedisStoreCache::class,
            //'config' => [
            // 'host' => '127.0.0.1',
            // 'port' => 6379,
            // 'password' => ':'
            //],
            //使用swoole_table缓存主调上报信息（默认）
            'className' => Tars\monitor\cache\SwooleTableStoreCache::class,
            'config' => [
                'size' => 40960
            ]
        ],
        'registryStoreConf' => [
            'className' => Tars\registry\RouteTable::class,
            'config' => [
                'size' => 200
            ]
        ],
        'protocolName' => 'http', //http, json, tars or other
        'serverType' => 'http', //http(no_tars default), websocket, tcp(tars default), udp
    ],
];

namespaceName 为业务实际使用的 namespaceName,必须与 composer.json 中的配置相互对应.

monitorStoreConf 为主调上报信息的存储配置

className 为主调上报信息的存储实现类的类名，默认为 \Tars\monitor\cache\SwooleTableStoreCache::class 使用swoole_table存储，tars-monitor中还提供了redis的存储方式，用户也可以自定义新的实现，但是必须实现 \Tars\monitor\contract\StoreCacheInterface 接口
config 为主调上报信息的存储实现类的配置信息，在实现类初始化时作为参数传入，默认对应swoole_table的 size

composer install,加载对应的依赖包
新建 tars/tars.proto.php 文件, 里面需要包含对你服务本身的说明:

<?php
return [
    'appName' => 'HelloWorld', // 对应部署服务的应用名称
    'serverName' => 'PHPHttp', // 对应部署服务的服务名称
    'objName' => 'Hello', // 对应部署服务的obj
];

这个名称要与在 tars 平台上面的名称完全一一对应。

新建 src/component/Controller.php

<?php

namespace PHPHttp\component;

use Tars\core\Request;
use Tars\core\Response;

class Controller
{
    protected $request;
    protected $response;

    public function __construct(Request $request, Response $response)
    {
        $this->request = $request;
        $this->response = $response;
    }

    public function getResponse()
    {
        return $this->response;
    }

    public function getRequest()
    {
        return $this->request;
    }

    public function cookie($key, $value = '', $expire = 0, $path = '/', $domain = '', $secure = false, $httponly = false)
    {
        $this->response->cookie($key, $value, $expire, $path, $domain, $secure, $httponly);
    }

    // 给客户端发送数据
    public function sendRaw($result)
    {
        $this->response->send($result);
    }

    public function header($key, $value)
    {
        $this->response->header($key, $value);
    }

    public function status($http_status_code)
    {
        $this->response->status($http_status_code);
    }
}

这是所有 Controller 的基类

新建 src/controller/IndexController.php

<?php

namespace PHPHttp\controller;

use PHPHttp\component\Controller;
use Tars\client\CommunicatorConfig;
use Tars\App;

class IndexController extends Controller
{
    public function actionIndex()
    {
        $this->sendRaw('Hello Tars!');
    }
}

创建 IndexController::actionIndex 方法，对应访问地址为 http://{machine_ip}:9000/index/index

完成代码开发后,在 src 目录下执行 composer run-script deploy 会自动进行代码打包
将打包好的代码 src/PHPHttp_xxx.tar.gz,上传到 tars 平台,并进行发布

若服务启动失败，可以在 node 机器或 docker 的/data/app/tars/app_log/HelloWorld/PHPHttp的日志中排查原因
发布操作见下图：

浏览器打开 http://{machine_ip}:9000/index/index 页面将显示 Hello Tars!

3. 示例：搭建 Tars 服务的 HelloWorld

目录结构说明

scripts 存储业务所需要的脚本,如 tars2php.sh 负责的就是根据 tars 文件,生成客户端所需要的代码
src 业务逻辑所在的目录,主要包含以下结构:
component: 基础类封装
conf: 业务需要的配置, 这里只是给出一个 demo,如果从平台下发配置,默认也会写入到这个文件夹中;
impl: tars 接口实现业务层;
servant: 使用 tars2php 生成的 client 端的代码, 这个目录名称完全可以自定义,只需要在使用的时候加以区分就可以了;
composer.json: 说明项目的依赖情况
index.php: 整个服务的入口文件,这个文件名称可以自定义,但是必须要更改平台上的私有模板,增加 entrance 这个字段在 server 下面
services.php: 声明整个项目的基础 namespaceName
tars 这个 tcp 服务所依赖的就是这个文件夹下面的*.tars 文件而 tarsclient.proto.php 文件,则是生成 servant 下代码所必须的,这个会在下面的 guideline 中具体说明。

部署服务

开发 guideline

创建scripts/tars2php.sh

#!/bin/bash

cd ../tars/

php ../src/vendor/phptars/tars2php/src/tars2php.php ./tarsclient.proto.php

这个脚本是用来根据 tarsclient.proto.php 中定义的配置生成相关代码的

创建src/composer.json

{
  "name": "tars/helloworld/phptars",
  "description": "tars php hello world",
  "require": {
    "phptars/tars-server": "~0.2",
    "phptars/tars-deploy": "~0.1",
    "phptars/tars2php": "~0.1",
    "phptars/tars-log": "~0.1",
    "ext-zip": ">=0.0.1"
  },
  "autoload": {
    "psr-4": {
      "PHPTars\\": "./"
    }
  },
  "minimum-stability": "stable",
  "scripts": {
    "deploy": "\\Tars\\deploy\\Deploy::run"
  },
  "repositories": {
    "packagist": {
      "type": "composer",
      "url": "https://mirrors.aliyun.com/composer/"
    }
  }
}

创建完之后运行 composer install

创建框架入口文件src/index.php

<?php
/**
 * 框架启动的入口文件
 */
require_once __DIR__.'/vendor/autoload.php';

use \Tars\cmd\Command;

//php index.php  conf restart
$config_path = $argv[1];
$pos = strpos($config_path, '--config=');

$config_path = substr($config_path, $pos + 9);

$cmd = strtolower($argv[2]);

$class = new Command($cmd, $config_path);
$class->run();

创建 service 声明文件src/services.php

<?php
// 以namespace的方式,在psr4的框架下对代码进行加载
return [
    // 请注意，这个Hello代表的就是部署服务时写的obj，
    // 如果不小心忘记了，可以在服务管理->服务管理->HelloWorld->PHPTars->管理servant中查看，
    // 管理Servant一栏写的HelloWorld.PHPTars.Hello中的Hello就是你要的obj，这里的命名是AppName.ServerName.ObjName
    'Hello' => [
        'home-api' => '\PHPTars\servant\HelloWorld\PHPTars\Hello\SayHelloTafServiceServant',
        'home-class' => '\PHPTars\impl\SayHello',
        'protocolName' => 'tars', //http, json, tars or other
        'serverType' => 'tcp', //http(no_tars default), websocket, tcp(tars default), udp
    ],
];

创建tars/tars.proto.php

<?php
return [
    'appName' => 'HelloWorld', // 对应部署服务的应用名称
    'serverName' => 'PHPTars', // 对应部署服务的服务名称
    'objName' => 'Hello', // 对应部署服务的obj
];

创建tars/tarsclient.proto.php

<?php
return array(
    'appName' => 'HelloWorld', // 对应部署服务的应用名称
    'serverName' => 'PHPTars', // 对应部署服务的服务名称
    'objName' => 'Hello', // 对应部署服务的obj
    'withServant' => true, //为true生成服务端代码, 为false则生成客户端代码
    'tarsFiles' => array(
        './SayHello.tars', // tars文件地址，目前服务端仅支持一个tars文件，基于tars目录的相对路径
    ),
    'dstPath' => '../src/servant', // 生成代码的目标路径，基于scripts目录的相对路径
    'namespacePrefix' => 'PHPTars\servant', // 生成代码的命名空间前缀
);

定义 tars 代码生成相关的属性

创建 tars/SayHello.tars

module SayHelloTafServiceServant
{
    interface SayHelloTafService
    {
        int greeting(string name, out string greeting); // out代表输出参数，客户端可以获取到这个输出参数
    };

};

关于 tars 文件的编写方式请前往相关文档查看
执行cd scripts && ./tars2php.sh 生成 tars 相关代码

实现 tars 接口，创建src/impl/SayHello.php

<?php

namespace PHPTars\impl;

use PHPTars\servant\HelloWorld\PHPTars\Hello\SayHelloTafServiceServant;

class SayHello implements SayHelloTafServiceServant
{
    public function greeting($name, &$greeting)
    {
        $greeting = "PHPTars says hello to $name";

        return 0;
    }
}

这是 tars 接口 greeting 的具体实现，在src/services.php的home-class中已有相关申明

在 src 目录下执行composer run-script deploy打包代码
发布

代码发布完成之后可以在服务管理=>HelloWorld=>PHPTars=>接口调试中上传刚才编写的SayHello.tars文件进行接口调试
若服务启动失败，可以在 node 机器或 docker 的/data/app/tars/app_log/HelloWorld/PHPTars的日志中排查原因

4. 示例：Tars HelloWorld 服务的客户端程序

接下来我们尝试在 PHPHttp 服务中调用 PHPTars 中刚完成的 Tars 接口

复制刚刚的PHPTars/tars/SayHello.tars到PHPHttp/tars/SayHello.tars
创建tars/tarsclient.proto.php

<?php

return array(
    'appName' => 'HelloWorld',
    'serverName' => 'PHPTars',
    'objName' => 'Hello',
    'withServant' => false, //决定是服务端,还是客户端的自动生成
    'tarsFiles' => array(
        './SayHello.tars',
    ),
    'dstPath' => '../src/servant',
    'namespacePrefix' => 'PHPHttp\servant',
);

执行cd scripts && ./tars2php.sh生成客户端调用代码

编辑src/controller/IndexController.php添加如下代码

   public function actionTestGreeting()
    {
        $config = new \Tars\client\CommunicatorConfig();
        $config->setLocator(\Tars\App::$tarsConfig['tars']['application']['client']['locator']);

        $userService = new \PHPHttp\servant\HelloWorld\PHPTars\Hello\SayHelloTafServiceServant($config);
        $greeting = '';
        $return = $userService->greeting('Frank Lee', $greeting);

        $this->sendRaw(json_encode(compact('return', 'greeting')));
    }

通过刚刚生成的客户端类调用 Tars 接口
框架启动时将配置信息绑定到了\Tars\App::$tarsConfig上
\Tars\App::$tarsConfig['tars']['application']['client']['locator'] 即为主节点地址服务
!!!! 注意：Tars 是个多语言框架，所以在通信过程中数据需要满足强类型相关约束，此处的$greeting 需要预先初始化成目标类型。 !!!!

打包发布

发布完成之后可以访问http://{machine_ip}:{port}/index/TestGreeting观察效果

5. 论坛邀请

欢迎大家加入 TarsDoc 论坛一起探讨在 Tars 使用过程中遇到的问题和新的体会，共建和谐社区

论坛传送门