Yii不直接支持PDF解析，需通过Composer安装smalot/pdfparser等第三方库，并在控制器中安全调用、处理异常；注意中文乱码、扫描件OCR需求及PHP扩展依赖。
Yii框架本身不直接支持PDF解析，报错通常是因为未正确集成第三方PDF解析库，或调用方式不符合Yii的环境规范。核心问题不在Yii，而在PDF处理组件的引入、配置与使用方式。
确认PDF解析库是否已正确安装
Yii项目中常用 smalot/pdfparser 或 setasign/fpdi（侧重合并/写入）配合 tcpdf，但纯文本提取推荐 smalot/pdfparser。需通过Composer安装：
- 错误做法：手动复制类文件或仅下载ZIP解压到vendor目录 —— 会导致autoload失败、类找不到
-
正确做法：在项目根目录执行：
composer require smalot/pdfparser - 安装后检查
vendor/autoload.php是否被Yii入口文件（如web/index.php）正确引入
在Yii控制器或服务中安全调用PDF解析器
避免在全局作用域或未初始化时直接 new Parser()。应在方法内实例化，并捕获常见异常：
- PDF文件路径必须是服务器可读的绝对路径（非URL），例如：
$pdfPath = Yii::getAlias('@app') . '/uploads/sample.pdf'; - 添加基础异常处理，防止因加密PDF、损坏文件或空内容崩溃：
use Smalot\PdfParser\Parser;
<p>try {
$parser = new Parser();
$pdf = $parser->parseFile($pdfPath);
$text = $pdf->getText(); // 获取全部文本
} catch (\Smalot\PdfParser\Exception\ParseException $e) {
Yii::error('PDF解析失败: ' . $e->getMessage(), 'pdf-parser');
throw new BadRequestHttpException('无法读取该PDF文件，请检查格式或权限。');
} catch (\Exception $e) {
Yii::error('未知PDF处理错误: ' . $e->getMessage(), 'pdf-parser');
throw new RuntimeException('PDF处理异常');
}注意中文乱码与字体嵌入问题
smalot/pdfparser 默认对未嵌入字体的中文PDF提取效果差，可能返回空字符串或乱码。这不是Yii问题，而是PDF源文件本身限制：
- 优先确认PDF是否由Word/Office导出并勾选了“嵌入字体”；若为扫描件（图片型PDF），该库完全无法提取文字 —— 需换用OCR方案（如Tesseract + imagick）
- 若PDF含嵌入中文字体但仍乱码，可尝试升级到
smalot/pdfparser ^2.0（支持更多编码），并在解析前设置默认编码（部分版本支持）：$parser->setEncoding('UTF-8'); - 调试建议：先用命令行工具
pdftotext sample.pdf -（Poppler套件）验证能否提取，再比对PHP结果
Yii模块化封装建议（提升复用性）
将PDF解析逻辑抽成独立组件，便于在多个Controller中调用且统一处理日志、缓存和错误：
- 新建
components/PdfTextExtractor.php，继承\yii\base\Component - 在
config/web.php中注册为应用组件：'pdfExtractor' => ['class' => 'app\components\PdfTextExtractor'], - 组件内部封装路径校验、大小限制（如
if (filesize($path) > 20 * 1024 * 1024) throw new InvalidArgumentException('PDF不能超过20MB');）
不复杂但容易忽略：确保PHP开启 mbstring 扩展（smalot依赖它处理多字节字符），且临时目录（sys_get_temp_dir()）有写权限 —— 否则解析大PDF时可能静默失败。
