QuickBooks Online API 查询中正确插入日期变量的完整教程-php教程-PHP中文网

QuickBooks Online API 查询中正确插入日期变量的完整教程

在使用 QuickBooks Online (QBO) PHP SDK 执行时间范围查询时，若将 MySQL 中读取的日期变量（如 '2022-01-01'）直接拼入 Query 字符串，常因引号缺失导致语法错误、无结果返回；正确做法是显式为变量值添加单引号，并确保字符串拼接安全。

在使用 quickbooks online (qbo) php sdk 执行时间范围查询时，若将 mysql 中读取的日期变量（如 `'2022-01-01'`）直接拼入 query 字符串，常因引号缺失导致语法错误、无结果返回；正确做法是显式为变量值添加单引号，并确保字符串拼接安全。

在 QuickBooks Online 的 REST API 查询中，MetaData.LastUpdatedTime 是一个 ISO 8601 格式的 UTC 时间戳（例如 2022-01-01T00:00:00Z），但 QBO 的 Query 接口支持对 LastUpdatedTime 使用日期字符串比较（仅年-月-日部分），前提是该字符串被严格包裹在单引号内。这是关键语法约束：QBO 查询解析器不会自动为未加引号的变量值补全引号，因此 MetaData.LastUpdatedTime > $qboLastUpdate 实际被解析为类似 MetaData.LastUpdatedTime > 2022-01-01 —— 这在 SQL 中会被解释为数学减法（2022 - 1 - 1 = 2020），完全偏离预期。

✅ 正确写法（必须手动添加单引号）：

$qboLastUpdate = '2022-01-01'; // 来自 MySQL DATE 字段，格式为 Y-m-d
$i = 1;
$end = 100;
$qboTable = 'Customer';

$query = "SELECT * FROM $qboTable 
          WHERE MetaData.LastUpdatedTime > '$qboLastUpdate' 
          STARTPOSITION $i MAXRESULTS $end";

$qboTableExtract = $dataService->Query($query);

⚠️ 常见错误及说明：

❌ "MetaData.LastUpdatedTime > $qboLastUpdate" → 缺失引号，触发隐式类型转换或语法失败；
❌ "MetaData.LastUpdatedTime > \"$qboLastUpdate\"" → 双引号在 QBO 查询中无效，仅接受单引号；
❌ 使用 STR_TO_DATE() 或 PHP date() 二次格式化 → QBO 不识别 MySQL 函数，且 PHP 端已确保 $qboLastUpdate 为 Y-m-d 格式即可，无需额外处理；
❌ 忽略时区：LastUpdatedTime 始终为 UTC，而你的 MySQL 存储应统一用 DATE 类型（不带时分秒），避免本地时区干扰比较逻辑。

? 最佳实践建议：

始终验证变量内容：在执行前 var_dump($qboLastUpdate)，确认其为字符串类型且格式为 YYYY-MM-DD；
启用查询日志：临时开启 $dataService->setLogLocation('/tmp/qbo.log')，捕获实际发送的查询语句，快速定位引号/空格问题；
防御性拼接：对 $qboTable 做白名单校验（如 in_array($qboTable, ['Customer', 'Invoice', 'Vendor'])），防止 SQL 注入式表名注入（尽管 QBO 不支持多语句，但仍属安全规范）；
升级健壮性：考虑改用参数化风格的 QueryBuilder（如社区封装类），或构造 ISO 时间范围（如 >= '2022-01-01T00:00:00Z'）以获得更高精度控制。

总结：QBO Query 语句中的字符串字面量必须显式用单引号包裹，PHP 变量需通过字符串拼接方式安全嵌入，而非依赖解析器自动补全。这一细节虽小，却是集成稳定性的关键支点。