---
code: php_sdk_installation
name: "PHP"
wikiToken: XjWfwdvmliurf5k9Tr7cevp3nhc
parentWikiToken: O3YxwgHGiiEnvYkHCcIcX51inkf
updateTime: 1745310928000
sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=php_sdk_installation
---
# PHP

::: tip 提示

 在接入前, 请先阅读接入前准备。

您可以在 GitHub 获取 PHP SDK 源码。

 :::

**最新版本**：v3.1.1

**更新时间**：2024-07-24

**资源下载：**源代码

::: warning 注意

当前文档适用于 v3.0.0 及以后的版本，历史版本请参考 PHP SDK 接入指南（V2）

::: 

### 一、集成SDK

1. 使用 composer 集成
```
{
    "require": {
        "thinkinggame/ta-php-sdk": "v3.1.1"
    }
}
```

1. 您也可以从GitHub中获取 SDK 的源码，并集成到您的项目中。只需要将 TaPhpSdk.php 放到你项目所在的目录即可。本 SDK 兼容 PHP >5.5，部分功能依赖 curl 扩展。
1.  安装Logbus
我们推荐使用SDK+LogBus的形式，完成服务端数据的采集上报.您可以参考以下文档完成Logbus的安装:LogBus使用指南

### 二、初始化

以下是SDK初始化的示例代码:

```
require_once "vendor/autoload.php";

use Exception;
use ThinkingData\TDLog;
use ThinkingData\TDAnalytics;
use ThinkingData\TDFileConsumer;
use ThinkingData\TDDebugConsumer;
use ThinkingData\TDBatchConsumer;
use ThinkingData\ThinkingDataException;

TDLog::*$enable *= true;

$consumer = new TDFileConsumer("LOG_DIRECTORY", 200, true, "LOG_FILE_PREFIX");
$teSDK = new TDAnalytics($consumer, true);
```

`LOG_DIRECTORY`为写入本地的文件夹地址。您只需将 LogBus 的监听文件夹地址设置为此处的地址，即可使用 LogBus 进行数据的监听上传。

`LOG_FILE_PREFIX`为日志文件名字的前缀。

### 三、常用功能

为了保证访客 ID 与账号 ID 能够顺利进行绑定，如果您的游戏中会用到访客 ID 与账号 ID，我们极力建议您同时上传这两个 ID，否则将会出现账号无法匹配的情况，导致用户重复计算，具体的 ID 绑定规则可参考用户识别规则一章。

#### 3.1 发送事件

您可以调用`track`来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，以下是发送事件的示例代码:

```
$account_id = 2121;
$distinct_id = 'SJ232d233243';
$properties = array();
$properties['age'] = 20;
$properties['Product_Name'] = 'c';
$properties['update_time'] = date('Y-m-d H:i:s', time());
$json = array();
$json['a'] = "a";
$json['b'] = "b";
$jsonArray = array();
$jsonArray[0] = $json;
$jsonArray[1] = $json;
$properties['json'] = $json;
$properties['jsonArray'] = $jsonArray;

try {
    $teSDK->track($distinct_id, $account_id, "viewPage", $properties);
} catch (Exception $e) {
    echo $e;
}
```

- 事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。
- Key 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感,TE会统一转化为小写字母
- Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组
<!-- unsupported block: 34 -->

**用户属性的要求与事件属性保持一致**

#### 3.2 设置用户属性

对于一般的用户属性，您可以调用 `user_set` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：

```
$properties = array();
$properties['once_key'] = 'twice';
$properties['age'] = 10;
$properties['money'] = 300;
$properties['array1'] = ['str1', 'str2'];
try {
    $teSDK->user_set('distinct_id', 'account_id', $properties);
} catch (Exception $e) {
    //handle except
    echo $e;
}
```

#### 3.3 数据上报

使用 `TDFileConsumer` 时，采集到的事件会先转成 json 字符串，然后添加到缓存数组中。当数组元素个数超出设置的容量时才会将数据写入磁盘。默认容量限制为100条数据。

在某些业务场景下，如果您期望数据立即上报到TE服务器，可以通过调用`flush()`接口完成。需要注意，频繁调用`flush()`会导致服务性能下降。

```
$te->flush();
```

#### 3.4 关闭SDK

```
try{
  $te->close();
} catch (Exception $e){
  //异常处理
  echo $e;
}
```

<!-- unsupported block: 34 -->

关闭并退出 SDK，请在关闭服务器前调用本接口，以避免缓存内的数据丢失

### 四、最佳实践

以下示例代码包含以上所有操作，我们推荐按照如下步骤使用:

```
require_once "vendor/autoload.php";

use Exception;
use ThinkingData\TDLog;
use ThinkingData\TDAnalytics;
use ThinkingData\TDFileConsumer;
use ThinkingData\TDDebugConsumer;
use ThinkingData\TDBatchConsumer;
use ThinkingData\ThinkingDataException;

TDLog::*$enable *= true;

$consumer = new TDFileConsumer("LOG_`DIRECTORY`", 200, true, "te");
$teSDK = new TDAnalytics($consumer, true);

$account_id = 2121;
$distinct_id = 'SJ232d233243';
$properties = array();
$properties['age'] = 20;
$properties['Product_Name'] = 'c';
$properties['update_time'] = date('Y-m-d H:i:s', time());
$json = array();
$json['a'] = "a";
$json['b'] = "b";
$jsonArray = array();
$jsonArray[0] = $json;
$jsonArray[1] = $json;
$properties['json'] = $json;
$properties['jsonArray'] = $jsonArray;

try {
    $teSDK->track($distinct_id, $account_id, "viewPage", $properties);
} catch (Exception $e) {
    echo $e;
}

$properties = array();
$properties['once_key'] = 'twice';
$properties['age'] = 10;
$properties['money'] = 300;
$properties['array1'] = ['str1', 'str2'];
try {
    $teSDK->user_set($distinct_id, $account_id, $properties);
} catch (Exception $e) {
    //handle except
    echo $e;
}
```

###
