rdKafka扩展是PHP直连Kafka的唯一生产级方案；纯PHP客户端如kafka-php因吞吐低、offset管理不可靠，不适用于生产环境。
PHP 直接连 Kafka 做异步任务，不是不行，但得清楚 rdKafka 扩展才是唯一靠谱路径；用纯 PHP 实现的 Kafka 客户端（比如 php-kafka）基本不适用于生产环境，吞吐、重试、offset 管理都靠不住。
rdkafka 扩展安装与基础连接验证
PHP 本身不内置 Kafka 支持，必须装 rdkafka 扩展——它是 librdkafka 的 PHP 封装，稳定、高性能、支持 SASL/SSL、自动重连和精确 offset 控制。
常见错误现象：Class 'RdKafka\Producer' not found 或 Failed to create producer: Failed to resolve 'kafka:9092'，多数是扩展没启用或 broker 地址不通。
- 确认已启用扩展：
php -m | grep rdkafka，没输出就补装（Ubuntu：apt install php-rdkafka；macOS：pecl install rdkafka） - 连接前先 telnet 测试：
telnet localhost 9092（注意：Kafka 默认监听的是 broker 内网地址，Docker 环境务必检查advertised.listeners配置是否映射正确） - 初始化 Producer 时建议加超时和错误回调：
'socket.timeout.ms' => 5000、'log_level' => 7，便于定位连接卡死问题
Producer 发送消息必须设好 key 和 delivery report
不设 key 消息会轮询分发到 partition，导致同一业务逻辑（如用户 ID 相关任务）被分散处理，破坏顺序性；不处理 delivery report 则无法感知发送失败，消息可能静默丢失。
立即学习“PHP免费学习笔记（深入）”；
使用场景：电商下单后触发库存校验、优惠券发放等需按用户维度保序的任务。
- 发送时指定
key：$producer->produce($topic, RD_KAFKA_PARTITION_UA, json_encode($data), $userId) - 必须调用
$producer->poll(0)触发 delivery report 回调，否则回调函数永不执行 - 在 delivery report 回调里判断
$message->err()，非零值表示失败，需记录日志并考虑重试（不要直接 throw Exception，会中断整个 producer 循环）
Consumer 启动前必须明确 group.id 和 auto.offset.reset
group.id 不只是标识名，它决定 consumer 是否能从上次 offset 继续消费；auto.offset.reset 错配会导致“消息不见了”——比如设成 latest 却期望消费历史积压，或设成 earliest 在已有 group 已提交 offset 时重复消费。
性能影响：consumer 启动时若要拉取大量历史消息，fetch.message.max.bytes 和 queued.min.messages 参数不合理会显著拖慢首次拉取速度。
- 开发环境可设
'group.id' => 'test-group'+'auto.offset.reset' => 'earliest'确保看到所有消息 - 生产环境务必用有意义的 group 名（如
order-notify-worker），避免多个服务共用 group 导致 offset 干扰 - 首次启动后，consumer 会自动提交 offset；如需手动控制（例如处理失败时不提交），要关掉
'enable.auto.commit' => false，并在成功处理后显式调用$consumer->commit($message)
PHP 进程模型下 consumer 容易假死或内存泄漏
Kafka consumer 是长连接、持续拉取消息的阻塞模型，PHP-FPM 或 CLI 脚本跑久了容易因未释放资源、未处理异常而僵死。这不是 Kafka 问题，是 PHP 运行时特性决定的。
容易踩的坑：用 while(true) 包裹 $consumer->consume(1000) 却没做任何退出机制；或在回调里用了 file_get_contents 加载大文件导致内存暴涨。
- 必须设置单次运行最大消息数或时间限制，例如每处理 100 条或运行 300 秒后
exit，靠 supervisor 自动重启进程 - 每次 consume 后检查
$message->err()，遇到RD_KAFKA_RESP_ERR__PARTITION_EOF属正常（该 partition 当前无新消息），不用报错 - 避免在 consumer 回调中做同步 HTTP 请求或数据库写入；如必须，加超时和重试，否则一个慢请求会卡住整个 partition 拉取
真正难的不是发几条消息，而是让 consumer 在 PHP 这种无原生线程/协程调度的环境里，长期稳定地维持连接、精准提交 offset、优雅应对网络抖动和 broker 重启——这些细节不压测、不监控，上线后只会以“偶尔丢消息”或“某天突然不消费了”的形式暴露。
