PHP 縮略圖生成類 PicThumb：支援 ImageMagick/GD、等比縮放/裁切/水印完整實作

功能特性

• 兩種引擎：ImageMagick (推薦，效能好、格式支援全) / GD (純 PHP，無外部依賴)。
• 兩種模式：fit 等比縮放含填充背景 / crop 等比縮放後裁切指定區域。
• 水印支援：位置 (9 宮格)、透明度 (ImageMagick)、邊距。
• 品質控制：輸出品質 1-100 可調。
• 自動建立目錄、日誌記錄、錯誤處理。

核心類別結構 (PicThumb.class.php)

<?php
class PicThumb {
    private $_log, $_handler, $_type, $_source, $_dest;
    private $_watermark, $_opacity, $_gravity, $_geometry, $_croppos;
    private $_bgcolor, $_quality, $_width, $_height;

    public function __construct($logfile = '') { /* 初始化日誌 */ }

    public function set_config(array $param) { /* 設定所有參數 */ }

    public function create_thumb($source, $dest) {
        // 1. 檢查 handler 可用性
        // 2. 驗證寬高參數
        // 3. 檢查源檔存在
        // 4. 建立目標目錄
        // 5. 分派 fit/crop → imagemagick/gd 四種組合
        // 6. 完成後加浮水印
    }

    // 私有方法：fit、crop、gd_fit、gd_crop、get_size、get_crop_offset
    // 水印：add_watermark (imagemagick: composite / gd: imagecopy)
    // 工具：check_handler、create_dirs、exists、to_log、hex2rgb、get_file_ext
}

關鍵演算法細節

等比縮放尺寸計算 (get_size)

// fit 模式：寬優先，若高超限則改以高為基準
$pic_w = $width;
$pic_h = (int)($pic_w * $oheight / $owidth);
if ($pic_h > $height) {
    $pic_h = $height;
    $pic_w = (int)($pic_h * $owidth / $oheight);
}

// crop 模式：以較長邊為基準縮放，確保覆蓋目標區域
if ($owidth > $oheight) {
    $pic_h = $height;
    $pic_w = (int)($pic_h * $owidth / $oheight);
} else {
    $pic_w = $width;
    $pic_h = (int)($pic_w * $oheight / $owidth);
}

裁切偏移量 (get_crop_offset) — 9 宮格對齊

// TL TM TR
// ML MM MR
// BL BM BR
switch (strtoupper($this->_croppos)) {
    case 'TL': $offset_w=0; $offset_h=0; break;
    case 'MM': $offset_w=($pic_w-$width)/2; $offset_h=($pic_h-$height)/2; break;
    case 'BR': $offset_w=$pic_w-$width; $offset_h=$pic_h-$height; break;
    // ... 其他 6 種
}

使用範例

$thumb = new PicThumb('/var/log/thumb.log');
$thumb->set_config([
    'handler' => 'imagemagick',
    'type' => 'crop',
    'width' => 300,
    'height' => 200,
    'watermark' => '/path/logo.png',
    'opacity' => 70,
    'gravity' => 'SouthEast',
    'geometry' => '+10+10',
    'croppos' => 'MM',
    'bgcolor' => '#FFFFFF',
    'quality' => 90
]);
$thumb->create_thumb('/data/upload/photo.jpg', '/data/supload/photo_thumb.jpg');

ImageMagick vs GD 選擇指南

建議：生產環境優先 ImageMagick；共享主機或禁用 exec() 環境退而求其次用 GD。

常見坑點與修正

• width/height 傳入非數值或 ≤0 → 驗證攔截。
• 源圖色彩空間非 RGB (如 CMYK) → ImageMagick 加 -colorspace RGB 強制轉換。
• GIF 裁切出現透明殘留 → 加 +repage 重置畫布。
• 大圖 GD 記憶體溢出 → 改用 ImageMagick 或分塊處理。

結語

PicThumb 以單一類別封裝雙引擎、雙模式、水印、日誌等完整功能，配置驅動介面極易整合。掌握其尺寸計算與裁切邏輯，可快速構建高效穩定的圖片處理服務。