PHP-Epub 不支持 Composer 安装，因未注册 Packagist、无标准命名空间及 composer.json；需手动引入并配置 autoload，或改用 zengabor/php-epub 等替代方案。
确认 PHP-Epub 库是否支持 Composer 安装
PHP-Epub 并非 Packagist 官方收录的主流库，composer require php-epub/php-epub 会失败——它没有注册命名空间、未托管在 GitHub/GitLab 的标准组织路径下，也没有 composer.json 元数据。直接运行安装命令只会返回 Could not find a matching version of package php-epub/php-epub。
实际可用的替代方案是：zengabor/php-epub（GitHub 上较活跃的 fork）或更推荐的 thephpleague/plates 类思路：用轻量解析器 + 手动构造 OPF/NCX/META-INF 等结构。但若坚持用原始 PHP-Epub，需手动引入：
- 从
https://github.com/Edenhill/php-epub（已归档）或镜像仓库下载 ZIP - 解压后将
EPUB.php和EPUBFile.php放入项目lib/目录 - 在
composer.json中添加 autoload 映射："autoload": { "psr-4": { "EPUB\": "lib/" } } - 执行
composer dump-autoload生效
加载 EPUB 文件时常见 ZipArchive::open() 失败
PHP-Epub 依赖 ZipArchive 解包 EPUB（本质是 ZIP），但默认不检查扩展是否启用或 ZIP 文件完整性。遇到 Warning: ZipArchive::open(): Invalid or uninitialized Zip object，大概率是以下之一：
-
extension=zip未在php.ini中启用（CLI 和 Web SAPI 配置可能不同，用php -m | grep zip和phpinfo()分别确认） - 传入的 EPUB 文件路径错误，或文件权限不足（
is_readable()返回 false） - EPUB 文件本身损坏（可用系统
unzip -t file.epub验证） - PHP-Epub 构造函数中硬编码了
new ZipArchive()，未捕获open()返回值；建议封装一层校验：$zip = new ZipArchive(); if ($zip->open($epubPath) !== TRUE) { throw new RuntimeException("Failed to open EPUB: $epubPath"); }
动态生成 EPUB 时必须手动处理 MIME 类型和容器结构
PHP-Epub 不自动生成 MIMETYPE 文件（EPUB 规范强制要求它必须是 ZIP 中第一个条目、无压缩、内容为 application/epub+zip），也未自动写入 container.xml。漏掉这些会导致多数阅读器拒绝打开。
立即学习“PHP免费学习笔记（深入）”；
生成流程关键点：
- 先用
ZipArchive::addFromString('mimetype', 'application/epub+zip')写入首条目 - 再添加
META-INF/container.xml，内容需包含<rootfiles><rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/></rootfiles> -
content.opf必须声明unique-identifier，且对应dc:identifier值要与package标签的unique-identifier属性一致 - 所有 HTML 内容需 UTF-8 编码，且
<html>标签带xmlns="http://www.w3.org/1999/xhtml"
否则 Calibre 或 Apple Books 会报 OPF file missing required identifier 或直接静默失败。
解析 EPUB 元数据时 getMetadata() 返回空数组
PHP-Epub 的 getMetadata() 方法只解析 content.opf 中 <metadata> 下的 dc: 前缀字段，但很多 EPUB（尤其自动生成的）把 dc:title 写成 <dc:title xmlns:dc="http://purl.org/dc/elements/1.1/"> —— 这种嵌套命名空间会导致 SimpleXML 解析失败。
临时修复方式：
- 在调用前对
content.opf字符串做预处理：$opf = str_replace('xmlns:dc="http://purl.org/dc/elements/1.1/"', '', $opf); - 或改用 DOMDocument + XPath 更可靠：
$dom = new DOMDocument(); $dom->loadXML($opf); $xpath = new DOMXPath($dom); $xpath->registerNamespace('dc', 'http://purl.org/dc/elements/1.1/'); $title = $xpath->query('//dc:title')->item(0)?->textContent; - 注意：PHP-Epub 不处理
meta标签中的property（如 EPUB 3 的dcterms:modified），这类字段需单独提取
EPUB 规范碎片化严重，同一本电子书在不同生成工具下结构差异很大，硬依赖单一解析库容易在边缘 case 上卡住。真正稳定的方案是：用 ZipArchive 手动读取核心文件 + 正则/XPath 按需提取，而非寄希望于封装层覆盖全部变体。
