1. PHP SDK 使用说明

在使用前，请先阅读数据模型的介绍。

2. 集成神策分析 SDK

在 PHP 脚本中集成神策分析 SDK ，使用神策分析采集并分析用户数据。SDK 最低兼容 PHP 5.X，部分功能依赖 curl 扩展。有两种集成方式：

使用 composer 集成。

{
	"require": {
		"sensorsdata/sa-sdk-php": "v2.0.0"
	}
}

JS

直接从 GitHub 获取 SDK 的源码并集成到项目中。

2.1. 初始化神策分析 SDK

2.1.1. 获取配置信息

如下图所示获取数据接收地址：

2.2. 在程序中初始化 SDK

在程序中初始化的代码段中构造神策分析 SDK 的实例：

注意：BatchConsumer 是同步发送数据，测试时候使用，不要在任何线上的服务中使用此 Consumer，线上推荐使用 FileConsumer。

<?php
	require_once("SensorsAnalytics.php");

	# 从神策分析配置页面中获取的数据接收的 URL
	$SA_SERVER_URL = 'YOUR_SERVER_URL';

	# 初始化一个 Consumer，用于数据发送
	# BatchConsumer 是同步发送数据，因此不要在任何线上的服务中使用此 Consumer
	$consumer = new BatchConsumer($SA_SERVER_URL);
	# 使用 Consumer 来构造 SensorsAnalytics 对象
	$sa = new SensorsAnalytics($consumer);
	# 支持在构造SensorsAnalytics对象时指定project, 后续所有通过这个SensorsAnalytics对象发送的数据都将发往这个project
	# $sa = new SensorsAnalytics($consumer, "project_name");

	# 以下是触发一个事件测试数据发送
	$distinct_id = 'ABCDEF123456789';
	$sa->track($distinct_id, true, 'UserLogin');

	$sa->flush();
?>

PHP

其中 YOUR_SERVER_URL 是前文中从神策分析获取的数据接收的 URL。用户程序应该一直持有该实例，直到程序结束。程序退出前，需要使用 `close()` 方法显式关闭，否则可能丢失部分缓存的数据。

至此，我们已经可以正常使用神策分析 SDK 了。需了解更多关于 SDK 的使用方法，可以跳到本文末尾的设置神策分析 SDK 一节。

3. 不同 Consumer 的使用方法

PHP SDK 主要由以下两个组件构成:

SensorsAnalytics: 用于发送数据的接口对象，构造函数需要传入一个 Consumer 实例。
Consumer: Consumer 会进行实际的数据发送

为了让开发者更灵活的接入数据，神策分析 SDK 实现了以下 Consumer:

FileConsumer: 将待发送的数据写入指定的本地文件，后续可以使用 LogAgent 或者 BatchImporter 来进行导入。

<?php
	require_once("SensorsAnalytics.php");
	# 初始化一个 Consumer，用于数据发送
	$consumer = new FileConsumer("sa.log." . date('Y-m-d'));
	# 使用 Consumer 来构造 SensorsAnalytics 对象
	$sa = new SensorsAnalytics($consumer);
?>

PHP

BatchConsumer: 通常用于导入小规模历史数据，或者离线 / 旁路导入数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，因此不要用在任何线上服务中。使用 CURL 批量发送数据的 Consumer，当且仅当数据达到指定的量时，才将数据进行发送。

<?php
	require_once("SensorsAnalytics.php");

	# 从神策分析配置页面中获取的数据接收的 URL
	$SA_SERVER_URL = 'YOUR_SERVER_URL';
	# 可选参数，当缓存的数据量达到参数值时，批量发送数据
	$SA_BULK_SIZE = 100;
	# 可选参数，发送数据的超时时间，单位毫秒
	$SA_REQUEST_TIMEOUT = 100000;
	# 可选参数，发送数据请求是否返回详情
	$RESPONSE_INFO = false;
	# 可选参数，发送数据请求的返回状态及数据落盘文件地址，必须同时 $RESPONSE_INFO 为 ture 时，才会记录
	$FILENAME = false;

	# 初始化一个 Consumer，用于数据发送
	# BatchConsumer 是同步发送数据，因此不要在任何线上的服务中使用此 Consumer
	$consumer = new BatchConsumer($SA_SERVER_URL, $SA_BULK_SIZE, $SA_REQUEST_TIMEOUT, $RESPONSE_INFO, $FILENAME);
	# 使用 Consumer 来构造 SensorsAnalytics 对象
	$sa = new SensorsAnalytics($consumer);

	# 程序结束前调用 flush() ，通知 Consumer 发送所有缓存数据
	$sa->flush();
?>

PHP

# 返回数据请求详情的返回值格式
# 数据进入缓存请求详情返回格式：
            $result = array(
                "ret_content" => "data into cache buffers",
                "ret_origin_data" => "",
                "ret_code" => 900
            );
# 示例
{"ret_content":"data into cache buffers","ret_data":"","ret_code":900}
 
# 数据发送请求详情返回格式：
            $result = array(
                "ret_content" => $ret,
                "ret_origin_data" => $origin_data,
                "ret_code" => curl_getinfo($ch, CURLINFO_HTTP_CODE)
            );
# 示例
{"ret_content":"","ret_origin_data":["{"type":"profile_unset","properties":{"City":true,"$is_login_id":true},"time":1595659757260,"distinct_id":"1234","lib":{"$lib":"php","$lib_version":"1.10.7","$lib_method":"code","$lib_detail":"####\/Users\/kakusei\/phpdemo\/test.php##32"}}"],"ret_code":200}

PHP

DebugConsumer: 用于校验数据导入是否正确，关于 Debug 调试模式的详细信息，请进入相关页面查看。

请注意：Debug 模式是为方便开发者调试而设置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。线上环境使用 Debug 模式会严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭 Debug 模式。

<?php
	require_once("SensorsAnalytics.php");

	# 从神策分析配置页面中获取的数据接收的 URL
	$SA_SERVER_URL = 'YOUR_SERVER_URL';
	# 可选参数，Debug 模式下，是否将数据导入神策分析
	# True - 校验数据，并将数据导入到神策分析中
	# False - 校验数据，但不进行数据导入
	$SA_DEBUG_WRITE_DATA = True;
	# 可选参数，发送数据的超时时间，单位毫秒
	$SA_REQUEST_TIMEOUT = 100000;

	# 初始化一个 Consumer，用于数据发送
	$consumer = new DebugConsumer($SA_SERVER_URL, $SA_DEBUG_WRITE_DATA, $SA_REQUEST_TIMEOUT);
	# 使用 Consumer 来构造 SensorsAnalytics 对象
	$sa = new SensorsAnalytics($consumer);
?>

PHP