LaunchDarkly PHP SDK需显式传入SDK key并构造Context对象，否则初始化失败或灰度失效；必须启用cURL、JSON、OpenSSL扩展，配置连接与读取超时，并关闭调试日志。
直接用 composer require launchdarkly/launchdarkly-php 就能装上，但光装完不行——它依赖 cURL、JSON 和 OpenSSL，且必须手动初始化 SDK 实例并传入 SDK key，否则 LDClient::getInstance() 会静默失败或抛出未捕获异常。
安装命令与 PHP 环境硬性要求
执行前先确认你的 PHP 环境满足最低条件：
- PHP ≥ 7.2（官方明确不支持 7.1 及更早版本）
- 已启用
curl、json、openssl扩展（缺任一都会在new LDClient()时触发RuntimeException） - 若用 Composer 2.5+，需确保
allow-plugins允许launchdarkly/launchdarkly-php的 autoloader 插件（默认开启，但某些企业 CI 环境会禁用）
安装命令就是一行：
composer require launchdarkly/launchdarkly-php
它会自动写入 composer.json 的 require 字段，并生成或更新 vendor/autoload.php。注意：不要用 composer update 替代，否则可能意外升级到 v6.x（已移除对 PHP 7.2 的支持）。
立即学习“PHP免费学习笔记（深入）”；
初始化 SDK 必须传入有效 SDK key，不能只靠环境变量
LaunchDarkly 官方 SDK 不会自动读取 LAUNCHDARKLY_SDK_KEY 环境变量——你得显式传进去。漏掉或传空字符串会导致客户端初始化失败，但不会报错，后续调用 $client->variation() 时才返回 null 或触发 Target key not found 错误。
正确初始化方式：
$sdkKey = $_ENV['LAUNCHDARKLY_SDK_KEY'] ?? 'your-sdk-key-here';<br>if (empty($sdkKey)) {<br> throw new RuntimeException('LaunchDarkly SDK key is missing');<br>}<br>$client = new \LaunchDarkly\LDClient($sdkKey);
常见错误场景：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 把测试环境的 client-side ID（以
client-开头）当 server-side SDK key 用 → 初始化成功但所有 flag 返回false - SDK key 写在
.env但没用vlucas/phpdotenv加载 →$_ENV为空，$client为 null - 在 CLI 脚本中运行却忘了导出环境变量 →
getenv('LAUNCHDARKLY_SDK_KEY')返回 false
feature flag 判断逻辑必须配合用户上下文对象
直接传字符串 user key 是不够的。SDK 要求构造 \LaunchDarkly\Context 对象（v6 起已废弃旧版 LDUser），否则 flag 计算结果不准，A/B 测试分流失效。
示例（带关键字段）：
$user = \LaunchDarkly\Context::builder('user-key-123')<br> ->name('Alice')<br> ->email('alice@example.com')<br> ->custom('department', 'engineering')<br> ->build();<br><br>$flagValue = $client->variation('enable-new-dashboard', $user, false);
容易踩的坑：
- 用数组或 stdClass 替代
Context::builder()→ 抛出TypeError（v6+ 强类型校验） - 用户 key 用时间戳或随机字符串，没做业务唯一性保证 → 同一用户被分到不同实验组
- 没传
$user参数，只传'user-key'字符串 → SDK 回退到匿名上下文，无法复用用户历史行为
生产环境必须关闭调试日志并设置连接超时
默认配置下，SDK 会在每次 flag 请求时打 debug 日志（通过 PSR-3 logger），线上高频请求会拖慢响应，甚至填满磁盘。同时，默认 HTTP 连接无超时，网络抖动时可能卡住整个请求。
上线前务必覆盖配置：
$config = new \LaunchDarkly\LDConfig([<br> 'base_uri' => 'https://app.launchdarkly.com',<br> 'connect_timeout' => 3,<br> 'read_timeout' => 3,<br> 'logger' => new \Psr\Log\NullLogger(),<br>]);<br>$client = new \LaunchDarkly\LDClient($sdkKey, $config);
额外注意：
-
connect_timeout和read_timeout单位是秒，设为0表示无限等待（绝对不要） - 别用
error_log或Monolog\Handler\StreamHandler直接往文件写 —— 高并发下 I/O 成瓶颈 - 如果用了 Laravel，建议绑定到容器时加
app()->singleton(LDClient::class, ...)，避免重复初始化
最常被忽略的是 Context 构造和超时配置——前者导致灰度失效，后者让服务雪崩。这两个点不调好，再准的 feature flag 规则也白搭。
