PHP原生不支持HDF5，需编译安装hdf5 C库及第三方HSF/hdf5扩展；通过HDF5File和HDF5Dataset类读写数据，须显式声明类型与空间，注意手动关闭句柄、路径规范及系统兼容性。
PHP本身不支持HDF5，必须依赖外部扩展
PHP标准库完全不提供HDF5读写能力，file_get_contents或fopen只能读取二进制字节，无法解析HDF5的层级结构、数据类型、压缩元信息。硬解析会直接失败，且极易损坏文件。
目前唯一成熟可用的方案是编译安装 hdf5 C库 + PHP扩展 hdf5（非PECL官方扩展，而是由第三方维护的 HSF/hdf5 项目）。它封装了HDF5 C API，提供类面向对象接口。
- 必须先在系统级安装 HDF5 C 库（如 Ubuntu：
sudo apt-get install libhdf5-dev） - 然后从源码编译 PHP 扩展：
phpize && ./configure && make && sudo make install - 启用扩展需在
php.ini中添加extension=hdf5.so，重启 PHP 进程 -
php -m | grep hdf5能看到输出才算成功加载
用 HDF5File 打开并读取 dataset
扩展提供 HDF5File 类管理文件句柄，HDF5Dataset 类操作具体数据集。读取前必须确认路径、数据类型和维度是否匹配，否则 read() 会返回空或触发警告。
常见错误现象：Warning: HDF5Dataset::read(): Failed to read dataset —— 多因路径写错（HDF5路径区分大小写）、dataset不存在、或当前PHP进程无读权限。
立即学习“PHP免费学习笔记（深入）”；
- 打开只读文件：
$file = new HDF5File('/path/to/data.h5', 'r'); - 获取 dataset 对象：
$ds = $file->openDataset('/group1/dataset_a'); - 读取为 PHP 数组（自动转换类型）：
$data = $ds->read(); - 若 dataset 是二维浮点型，
$data就是嵌套数组，如[[1.2, 3.4], [5.6, 7.8]] - 大文件慎用
read()，它会一次性加载全部数据到内存；可改用readChunk()分块读
写入 dataset 要显式指定类型与尺寸
HDF5是强类型格式，PHP数组没有原生类型标记，写入时必须手动传入 HDF5Type 和 HDF5Dataspace，否则扩展无法构造底层数据结构，直接报错 Failed to create dataset。
典型场景：你有一个 float[][] 的 PHP 数组，想存为压缩的 float32 dataset。不能直接 $file->createDataset(..., $array) —— 必须拆解声明。
- 定义数据空间（例如 100×200 的二维）：
$space = new HDF5Dataspace([100, 200]); - 指定类型（对应 C 的
float）：$type = new HDF5Type('float32'); - 创建 dataset：
$ds = $file->createDataset('my_data', $type, $space); - 写入数据：
$ds->write($php_2d_array); - 支持压缩：
$ds->setCompression(6);（1–9，6 是常用平衡值）
注意资源释放与 Windows 兼容性
扩展未实现自动析构，HDF5File 和 HDF5Dataset 对象持有 C 层句柄，不手动关闭会导致文件被锁、后续读写失败，甚至 PHP 进程崩溃。
Windows 下问题更突出：HDF5 C 库对路径分隔符敏感，\ 可能被误解析为转义字符；且多数预编译的 hdf5.so 仅提供 Linux/macOS 版本，Windows 用户几乎必须自己用 MSVC 编译，成功率低。
- 务必显式调用：
$ds->close(); $file->close(); - 路径统一用正斜杠：
/group/subgroup/data，避免\ - 生产环境强烈建议在 Linux 容器中运行，避开 Windows HDF5 支持缺陷
- 调试时用
h5dump -H file.h5（HDF5 官方命令行工具）验证结构，比 PHP 报错信息更准确
