PHPThumb 圖片處理庫完整使用指南

前言

PHPThumb (GitHub: masterexploder/PHPThumb) 是一個輕量、鏈式呼叫的 PHP 圖片處理庫，支援 GD/Imagick 雙引擎。注意區分同名但大小寫不同的 phpThumb (SourceForge 專案)，兩者 API 不同。

安裝與載入

# Composer 安裝 (推薦)
composer require phpthumb/phpthumb

# 或手動下載
require_once 'path/to/ThumbLib.inc.php';

核心功能速查表

實戰範例

基本縮圖流程

<?php
use PHPThumb\GD; // 或 PHPThumb\Imagick

// 1. 載入圖片 (支援本地路徑、URL、資料流)
$thumb = GD::create(__DIR__ . '/uploads/photo.jpg');

// 2. 等比縮放至最大 800x600
$thumb->resize(800, 600);

// 3. 加入浮水印 (需 GD 支援)
$watermark = GD::create(__DIR__ . '/assets/watermark.png');
$thumb->watermark($watermark, 'bottom-right', 10, 50); // 位置、邊距、透明度

// 4. 儲存為 JPEG 品質 85%
$thumb->save(__DIR__ . '/thumbs/photo_800w.jpg', 'jpg', 85);

// 5. 釋放記憶體 (大量處理時重要)
unset($thumb, $watermark);
?>

產生多種規格縮圖 (電商常見)

<?php
$specs = [
    'thumb'  => ['w' => 150, 'h' => 150, 'mode' => 'adaptive'], // 正方形裁切
    'medium' => ['w' => 600, 'h' => 400, 'mode' => 'resize'],   // 等比縮放
    'large'  => ['w' => 1200, 'h' => 800, 'mode' => 'resize'],
];

$source = '/var/www/images/product_raw.jpg';
$baseName = 'product_123';

foreach ($specs as $key => $spec) {
    $thumb = GD::create($source);

    if ($spec['mode'] === 'adaptive') {
        $thumb->adaptiveResize($spec['w'], $spec['h']);
    } else {
        $thumb->resize($spec['w'], $spec['h']);
    }

    $outPath = "/var/www/images/{$baseName}_{$key}.jpg";
    $thumb->save($outPath, 'jpg', 90);
}
?>

進階：濾鏡與特效

<?php
$thumb = GD::create('photo.jpg');

// 灰階
$thumb->filter('grayscale');

// 銳化
$thumb->filter('sharpen', 10); // 強度 0-100

// 高斯模糊
$thumb->filter('blur', 5);

// 色彩調整
$thumb->filter('brightness', 20);  // 亮度 -100~100
$thumb->filter('contrast', 15);    // 對比度 -100~100

// 圓角 (需 GD 2.0.1+)
$thumb->filter('rounded_corners', 15); // 半徑 15px

$thumb->save('styled.jpg');
?>

效能與記憶體優化

• 大圖處理：預設 GD 會將完整圖片載入記憶體。處理 >10MP 圖片時，建議增加 memory_limit 或改用 Imagick 引擎 (串流處理)。
• 批次處理：迴圈中及時 unset($thumb) 釋放資源，避免記憶體洩漏。
• 快取策略：產生的縮圖應快取至儲存層 (CDN/物件儲存)，避免重複運算。

常見問題

替代方案比較