萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP Imagick 將 PDF 轉 PNG 縮圖:兩種方法完整實作與效能優化

前置需求

  • 安裝 ImageMagick:`apt-get install imagemagick` / `brew install imagemagick`
  • 安裝 PHP 擴展:`pecl install imagick` 或 `apt-get install php-imagick`
  • 驗證:`php -m | grep imagick`、`php -r 'phpinfo();' | grep imagick`
  • 策略檔權限:`/etc/ImageMagick-6/policy.xml` 需允許 PDF 讀取 (``)

方法一:指定頁碼讀取 (適合單頁/首頁縮圖)

<?php
/**
 * PDF 指定頁面轉 PNG 縮圖
 * @param string $pdfPath  PDF 檔案路徑
 * @param string $outDir   輸出目錄
 * @param int    $page     頁碼 (0=第一頁, -1=所有頁)
 * @param int    $width    縮圖寬度
 * @param int    $height   縮圖高度
 * @return string|array|false 成功回傳檔案路徑,失敗 false
 */
function pdfToPng(string $pdfPath, string $outDir, int $page = 0, int $width = 200, int $height = 150): string|array|false {
    if (!extension_loaded('imagick')) {
        error_log('Imagick extension not loaded');
        return false;
    }
    if (!is_file($pdfPath)) {
        error_log("PDF not found: $pdfPath");
        return false;
    }
    if (!is_dir($outDir) && !mkdir($outDir, 0755, true)) {
        error_log("Cannot create output dir: $outDir");
        return false;
    }

    try {
        $im = new Imagick();
        $im->setResolution(150, 150);        // 解析度 DPI,影響清晰度
        $im->setCompressionQuality(85);      // JPEG/PNG 品質 0-100
        $im->readImage($pdfPath . "[$page]"); // 關鍵:[0] 讀第一頁

        // 縮放模式:保持比例
        $im->thumbnailImage($width, $height, true, true);

        // 去除透明背景 (可選)
        $im->setImageBackgroundColor('white');
        $im->setImageAlphaChannel(Imagick::ALPHACHANNEL_REMOVE);
        $im->mergeImageLayers(Imagick::LAYERMETHOD_FLATTEN);

        $filename = $outDir . '/' . basename($pdfPath, '.pdf') . '_page' . ($page+1) . '_' . time() . '.png';
        if ($im->writeImage($filename)) {
            $im->clear();
            $im->destroy();
            return $filename;
        }
        return false;
    } catch (ImagickException $e) {
        error_log("Imagick error: " . $e->getMessage());
        return false;
    }
}

// 使用
$thumb = pdfToPng('documents/report.pdf', 'thumbnails', 0, 300, 200);
if ($thumb) echo "<img src='$thumb'>";

方法二:逐頁迭代轉換 (適合多頁文檔全轉圖)

<?php
/**
 * PDF 所有頁面轉 PNG 陣列
 * @return string[]|false 成功回傳檔案路徑陣列
 */
function pdfToPngAll(string $pdfPath, string $outDir, int $width = 800, int $height = 0): array|false {
    if (!extension_loaded('imagick') || !is_file($pdfPath)) return false;
    if (!is_dir($outDir) && !mkdir($outDir, 0755, true)) return false;

    try {
        $im = new Imagick();
        $im->setResolution(150, 150);
        $im->setCompressionQuality(90);
        $im->readImage($pdfPath); // 讀取全部頁面

        $results = [];
        foreach ($im as $index => $frame) {
            // 每頁獨立處理
            $frame->setImageFormat('png');
            $frame->thumbnailImage($width, $height, true, true);
            $frame->setImageBackgroundColor('white');
            $frame->mergeImageLayers(Imagick::LAYERMETHOD_FLATTEN);

            $filename = $outDir . '/' . basename($pdfPath, '.pdf') . '_p' . ($index+1) . '_' . md5($frame->getImageSignature()) . '.png';
            if ($frame->writeImage($filename)) {
                $results[] = $filename;
            }
        }
        $im->clear();
        $im->destroy();
        return $results ?: false;
    } catch (ImagickException $e) {
        error_log("Imagick error: " . $e->getMessage());
        return false;
    }
}

// 使用
$thumbs = pdfToPngAll('documents/manual.pdf', 'thumbnails', 1024);
if ($thumbs) {
    foreach ($thumbs as $t) echo "<img src='$t' style='max-width:300px'>";
}

關鍵參數詳細說明

方法用途建議值
setResolution(x, y)渲染解析度 (DPI)150-300 (螢幕 72, 列印 300)
setCompressionQuality(q)輸出品質80-95 (PNG 無損但影響壓縮速度)
readImage("file.pdf[0]")讀取指定頁 (0-based)單頁模式關鍵
thumbnailImage(w, h, true, true)等比縮放、縮小不放大最佳縮圖方法
scaleImage(w, h, true)強制尺寸 (可能變形)需固定尺寸時
setImageBackgroundColor透明背景填充色'white' 或 '#FFFFFF'
mergeImageLayers(FLATTEN)合併圖層移除透明配合背景色使用

效能優化策略

  1. 降低解析度:縮圖用 72-150 DPI 即可,300 DPI 僅供列印級
  2. 限制記憶體:`$im->setResourceLimit(Imagick::RESOURCETYPE_MEMORY, 256 * 1024 * 1024)` (256MB)
  3. 使用臨時檔:`$im->setResourceLimit(Imagick::RESOURCETYPE_DISK, 1024 * 1024 * 1024)` (1GB 磁碟快取)
  4. 平行處理:多 PDF 同時轉換用 `pcntl_fork` 或佇列工作者
  5. 快取縮圖:以 PDF 檔案 hash + 頁碼 + 尺寸為 key 存 Redis/檔案

常見錯誤與解決

替代方案:無 Imagick 環境

<?php
// 方案 1:呼叫系統指令 (需安裝 poppler-utils: pdftoppm)
function pdfToPpm(string $pdf, string $outDir, int $page = 1): string|false {
    $outPrefix = $outDir . '/' . basename($pdf, '.pdf');
    $cmd = "pdptoppm -png -f $page -l $page -scale-to 800 " . escapeshellarg($pdf) . ' ' . escapeshellarg($outPrefix);
    exec($cmd . ' 2>&1', $output, $code);
    if ($code === 0 && ($file = glob($outPrefix . '*.png')[0] ?? null)) return $file;
    return false;
}

// 方案 2:使用 spatie/pdf-to-image (Composer 套件,內部封裝 Imagick/pdftoppm)
/*
composer require spatie/pdf-to-image
use Spatie\PdfToImage\Pdf;
$pdf = new Pdf($pdfPath);
$pdf->saveImage($outPath); // 預設第一頁
$pdf->getAllPages()->saveImages($outDir); // 所有頁
*/

安全性提醒

  • **嚴格驗證上傳檔案**:MIME、副檔名、檔案頭 (magic bytes `%PDF`)
  • **限制檔案大小**:`ini_set('upload_max_filesize', '10M')`
  • **隔離執行環境**:容器化、禁用網路、唯讀根目錄
  • **清理臨時檔**:`register_shutdown_function` 確保刪除

Imagick 是 PHP 處理 PDF 轉圖的標準選擇,掌握兩種讀取模式與關鍵參數,即可穩定產出高品質縮圖。

copyright © 萬盛學電腦網 all rights reserved
錯誤原因解決
PDFDelegateFailedGhostscript 未安裝或 policy.xml 禁止 PDF安裝 gs;修改 policy.xml 允許 PDF
Unable to open image路徑錯誤、權限不足、檔案損壞檢查 realpath、chmod 644
Memory allocation failed大 PDF 解析超過 memory_limit調高 php.ini memory_limit、Imagick resource limit
輸出全黑/空白色彩空間 CMYK、透明層疊加setImageColorSpace(sRGB)、flatten
中文檔名亂碼檔案系統編碼問題用 md5/時間戳命名、urlencode