PHP 多功能圖片處理類：縮略圖、水印、裁切、翻轉、邊框一站式解決

前言

在 CMS、電商、用戶頭像系統中，圖片處理是高頻剛需：生成多規格縮略圖、添加品牌水印、智能裁切、格式轉換等。本文分享一個功能完整的 ThumbHandler 類，基於 GD 庫封裝，支援：

• 等比縮放 / 固定寬高 / 自動裁切 / 手動裁切
• 文字水印（支援 TTF 字體、顏色、透明度、九宮格定位）
• 圖片水印（支援透明度合成、自動縮放適配）
• 圖片翻轉（水平/垂直）、邊框、圖片質量控制
• 多格式輸出（JPG/PNG/GIF/WBMP）

類架構概覽

class ThumbHandler {
    // 核心屬性
    private $h_src, $h_dst, $h_mask;      // GD 資源句柄
    private $src_w, $src_h;               // 源圖尺寸
    private $dst_w, $dst_h;               // 目標尺寸
    private $fill_w, $fill_h;             // 實際繪製區域
    private $copy_w, $copy_h;             // 複製區域
    private $src_x, $src_y;               // 源圖起始座標
    private $start_x, $start_y;           // 目標起始座標
    
    // 水印相關
    private $mask_word, $mask_img;
    private $mask_font, $mask_font_size, $mask_font_color;
    private $mask_position, $mask_offset_x, $mask_offset_y;
    private $mask_img_pct, $mask_txt_pct; // 透明度（0-100，值越大越不透明）
    
    // 其他
    private $cut_type;                    // 0=等比 1=自動裁切 2=手動裁切
    private $img_type;                    // 文件類型
    private $img_border_size, $img_border_color;
    private $_flip_x, $_flip_y;           // 翻轉計數
    
    // 公開方法：setSrcImg, setDstImg, setMaskWord, setMaskImg, setCutType...
    // 核心方法：createImg($width, $height?) -> bool
}

核心功能演示

1. 基本等比縮放（指定寬度，高度自適應）

require_once 'ThumbHandler.php';

$t = new ThumbHandler();
$t->setSrcImg('uploads/photo.jpg');
$t->setDstImg('thumbs/photo_300.jpg');
// 單參數模式：作為百分比（1-100）或寬度像素
$t->createImg(300); // 生成寬 300px，高度等比縮放

2. 固定寬高（可能變形）

$t->createImg(200, 200); // 強制 200x200

3. 自動智能裁切（從中心裁切最大正方形再縮放）

$t->setSrcImg('uploads/photo.jpg');
$t->setDstImg('thumbs/photo_square.jpg');
$t->setCutType(1); // 關鍵：啟用自動裁切
$t->createImg(150, 150); // 輸出 150x150 正方形

4. 手動指定裁切區域

$t->setSrcImg('uploads/large.jpg');
$t->setDstImg('thumbs/crop.jpg');
$t->setCutType(2);           // 手動裁切模式
$t->setSrcCutPosition(100, 50); // 源圖起始座標
$t->setRectangleCut(400, 300);  // 裁切寬高
$t->createImg(400, 300);       // 目標尺寸同裁切尺寸

5. 添加文字水印

$t->setSrcImg('uploads/photo.jpg');
$t->setDstImg('watermarked/photo.jpg');
$t->setMaskFont('fonts/simhei.ttf'); // TTF 字體路徑
$t->setMaskFontSize(24);
$t->setMaskFontColor('#FFFFFF');
$t->setMaskTxtPct(30);        // 30% 不透明度（較淡）
$t->setMaskPosition(4);       // 1=左上 2=左下 3=右上 4=右下
$t->setMaskOffsetX(10);
$t->setMaskOffsetY(10);
$t->setMaskWord('© MySite 2024');
$t->createImg(800, 600);

6. 添加圖片水印（Logo）

$t->setSrcImg('uploads/photo.jpg');
$t->setDstImg('watermarked/photo.jpg');
$t->setMaskImg('assets/logo.png'); // 建議 PNG 透明背景
$t->setMaskPosition(4);            // 右下角
$t->setMaskImgPct(50);             // 50% 透明度
$t->setMaskOffsetX(15);
$t->setMaskOffsetY(15);
$t->createImg(800);

7. 圖片翻轉 + 邊框

$t->setSrcImg('uploads/photo.jpg');
$t->setDstImg('processed/photo.jpg');
$t->flipH();                    // 水平翻轉
$t->flipV();                    // 垂直翻轉（連續調用可疊加）
$t->setDstImgBorder(5, '#DDDDDD'); // 5px 灰色邊框
$t->createImg(600);

8. 中文水印編碼處理

$text = "版權所有";
$str = mb_convert_encoding($text, "UTF-8", "gb2312"); // 視源文件編碼而定
$t->setMaskWord($str);
// 或確保 PHP 文件本身為 UTF-8 無 BOM，直接寫中文

關鍵參數速查表

常見問題與避坑指南

• GD 未安裝：php -m | grep gd 檢查，需編譯 --with-gd 或安裝 php-gd 包
• 中文亂碼：PHP 文件保存為 UTF-8 無 BOM，TTF 字體支援中文，mb_convert_encoding 處理編碼轉換
• 水印過大：類內部會自動檢測，若水印超過目標區域會報錯「水印圖片尺寸大於原圖」，解決：縮小水印或降低 setMaskImgPct 觸發自動縮放邏輯
• 記憶體溢出：處理超大圖（>5000px）時調大 memory_limit，或分塊處理
• imagedestroy() 已在 createImg() 末尾自動釋放資源，無需手動調用

擴展建議

1. 整合 Intervention/Image（Composer 包）獲得更現代化 API（鏈式調用、Laravel 集成）
2. 添加 WebP/AVIF 輸出支援（需 GD 2.1+ / imagick）
3. 引入圖片壓縮優化（如 TinyPNG API、mozjpeg）
4. 增加圖片驗證（MIME、魔數、尺寸限制）防止惡意上傳

總結

ThumbHandler 以單文件、零依賴（僅需 GD）、功能全面著稱，適合中小型項目快速集成。掌握「設置源→配置參數→createImg()」三步流程，即可輕鬆實現縮略圖生成、水印保護、智能裁切等核心圖片處理需求。