生产环境唯一推荐的PHP ClickHouse客户端是smi2/phpclickhouse，它纯PHP实现、不依赖PDO或C扩展，避免编译失败、版本错配及SSL兼容问题；安装需指定版本约束，配置中port必须为字符串，HTTPS需正确设置证书或验证选项，且连接验证应包含ping()和权限校验查询。
用 smi2/phpclickhouse 而不是其他驱动
生产环境唯一推荐的 PHP ClickHouse 客户端是 smi2/phpclickhouse。它纯 PHP 实现，不依赖 PDO 或 C 扩展，避免了编译失败、PHP 版本错配、SSL 协议不兼容等高频翻车点。其他如 the-tinderbox/clickhouse-php-client 或老版 pypclickhouse 已长期无维护，PHP 8.0+ 下大概率报 Fatal error: Call to undefined function curl_init() 或连接静默失败。
安装命令必须带版本约束：
composer require smi2/phpclickhouse:^1.5
若项目已用 PHP 8.2+ 且服务端启用了 TLS 1.3，则可升至 ^2.0，但需同步确认 ClickHouse 服务端 HTTPS 配置有效（否则 https() 调用会卡住）。
配置数组里 port 必须是字符串
smi2/phpclickhouse 对 port 字段做的是字符串拼接（http_build_query），传整数如 8123 会被转成空字符串，导致 URL 变成 http://host:/，最终连接失败且无明确错误提示。
立即学习“PHP免费学习笔记（深入）”；
最小可用配置示例（注意引号）：
$client = new \ClickHouseDB\Client([ 'host' => '192.168.5.10', 'port' => '8123', // ← 必须加引号 'username' => 'tp51_app', 'password' => 'StrongPassw0rd!2026', 'database' => 'analytics_db', 'timeout' => 30, ]);
-
database不是连接时自动 USE 的库，而是后续所有select()/insert()的默认作用库；不设会报Database not specified -
timeout建议 ≥30 秒——大查询或首次建表可能耗时较长，设太短会误判为超时 - 如果 ClickHouse 启用了
user.xml中的<networks>白名单，确保 PHP 服务器 IP 在允许范围内，否则ping()返回false但不报错
HTTPS 连接不能只开 https => true
仅在配置中加 'https' => true 是不够的。它只切换协议，不处理证书校验。常见错误 cURL error 60: SSL certificate problem 就是因为服务端开了 HTTPS 但客户端没配 CA 或禁用了验证。
三种等效启用方式（任选其一）：
// 方法一：调用方法 $client->https(); <p>// 方法二：设置对象 $client->settings()->https();</p><p>// 方法三：配置数组里声明 $config['https'] = true;
但真正要跑通，还得补上证书路径或关闭验证（仅限调试）：
- 正式环境：加
'sslCA' => '/path/to/certificate.pem' - 临时调试：加
'verify' => false，但上线前必须删掉
别只靠 ping() 判断连接成功
$client->ping() 只检测 HTTP 端口是否可达，完全不校验鉴权、数据库权限、网络策略。线上高频问题是：端口通、用户能登录、SELECT 1 成功，但查具体表时报 Cannot read from table —— 因为账号没被授予目标库的 SELECT 权限。
建议连通性验证至少包含两步：
- 执行
$client->ping()（确认服务在线） - 执行
$client->select('SELECT 1 FROM system.tables LIMIT 1')（确认账号有基本读权限）
尤其在 ThinkPHP 等框架里集成时，容易忽略权限粒度——tp51_app 这类专用账号必须显式 GRANT SELECT, INSERT ON analytics_db.* TO tp51_app，不能只给 default 库权限。
