کلاس Upload چیست؟

کلاس Upload مدیریت آپلود فایل‌ها در پروژه‌های PHP را بسیار ساده می‌کند. این کلاس به شما اجازه می‌دهد تا فایل‌های آپلود شده، مخصوصاً تصاویر را، به راحتی پردازش، تغییر اندازه، کراپ، فیلترگذاری، اضافه کردن واترمارک و بسیاری تغییرات دیگر اعمال کنید.

فرمت‌های پشتیبانی شده: PNG، JPG، GIF، WEBP و BMP.

سازگار با PHP 5.3+, PHP 7 و PHP 8.

نحوه استفاده

ایجاد فرم آپلود فایل:

< form enctype="multipart/form-data" method="post" action="upload.php" >
 <  input type="file" size="32" name="image_field" value="" >
  <  input type="submit" name="Submit" value="upload" >
< /form>
    

کد PHP برای پردازش آپلود:

$handle = new \Verot\Upload\Upload($_FILES['image_field']);

if ($handle->uploaded) {
    $handle->file_new_name_body = 'image_resized';
    $handle->image_resize = true;
    $handle->image_x = 100;
    $handle->image_ratio_y = true;

    $handle->process(PUPATH.'/files/');

    if ($handle->processed) {
        echo 'image resized';
        $handle->clean();
    } else {
        echo 'error: ' . $handle->error;
    }
}
    

چگونه کار می‌کند؟

• ابتدا کلاس را با آرایه $_FILES یا یک فایل محلی instantiate می‌کنید.
• سپس متغیرهای پردازش مانند تغییر اندازه، تغییر نام یا فیلترگذاری را تنظیم می‌کنید.
• متد process() را برای انجام عملیات فراخوانی می‌کنید.
• پس از پردازش می‌توانید فایل را پاک کنید با استفاده از clean().
• هر بار که process() را فراخوانی می‌کنید، تغییرات جدید اعمال می‌شود.

توجه: اگر هیچ متغیر پردازشی تنظیم نکنید، فایل به صورت ساده کپی می‌شود.

استفاده از Namespacing

این کلاس در فضای نام Verot\Upload قرار دارد.

نمونه استفاده:

use Verot\Upload\Upload;

$handle = new Upload($_FILES['image_field']);
    

یا به صورت مستقیم:

$handle = new \Verot\Upload\Upload($_FILES['image_field']);
    

پردازش فایل‌های محلی

برای کار با فایل‌های موجود روی سرور، کافی است مسیر فایل را به کلاس بدهید:

$handle = new Upload(PUPATH.'/user/myfile.jpg');
    

آپلود با XMLHttpRequest

برای فایل‌هایی که با Ajax یا XHR آپلود می‌شوند:

$handle = new Upload('php:' . $_SERVER['HTTP_X_FILE_NAME']);
    

با پیشوند php: داده‌ها مستقیماً از php://input دریافت می‌شود.

لینک‌های مرتبط

• صفحه اصلی کلاس Upload
• دموها و نمونه کدها
• حمایت مالی از توسعه‌دهنده
• اطلاعات مجوز استفاده تجاری

چگونه یک فایل آپلود شده از طریق XMLHttpRequest را پردازش کنیم؟

برای پردازش فایلی که از طریق XMLHttpRequest آپلود شده، ابتدا کلاس را با استفاده از کلیدواژه خاص php: نمونه‌سازی کنید. به این صورت:

$handle = new Upload('php:' . $_SERVER['HTTP_X_FILE_NAME']);
        

پیشوند php: به کلاس می‌گوید که داده‌های آپلود شده را از php://input دریافت کند و بقیه مسیر فایل معمولاً در $_SERVER['HTTP_X_FILE_NAME'] قرار دارد. البته می‌توانید از هر نامی که مناسب می‌بینید استفاده کنید:

$handle = new Upload('php:mycustomname.ext');
        

چگونه داده‌های خام فایل را پردازش کنیم؟

برای پردازش داده‌های خام فایل، کلاس را با استفاده از کلیدواژه data: نمونه‌سازی کنید. به این صورت:

$handle = new Upload('data:' . $file_contents);
        

اگر داده‌های شما base64 کدگذاری شده باشند، کلاس یک کلیدواژه ساده base64: را فراهم کرده است که داده‌های شما را قبل از استفاده رمزگشایی می‌کند:

$handle = new Upload('base64:' . $base64_file_contents);
        

چگونه زبان را تنظیم کنیم؟

برای تنظیم زبان، کلاس را با یک آرگومان دوم که کد زبان است، نمونه‌سازی کنید:

$handle = new Upload($_FILES['image_field'], 'fr_FR');
$handle = new Upload('/home/user/myfile.jpg', 'fr_FR');
        

چگونه فایل یا تصویر نتیجه را مستقیماً به مرورگر خروجی دهیم؟

برای این کار، کافی است متد process() را بدون آرگومان (یا با مقدار null به عنوان آرگومان اول) فراخوانی کنید:

$handle = new Upload($_FILES['image_field']);
header('Content-type: ' . $handle->file_src_mime);
echo $handle->process();
die();
        

اگر می‌خواهید دانلود فایل را اجباری کنید:

$handle = new Upload($_FILES['image_field']);
header('Content-type: ' . $handle->file_src_mime);
header("Content-Disposition: attachment; filename=" . rawurlencode($handle->file_src_name) . ";");
echo $handle->process();
die();
        

هشدار امنیتی

به طور پیش‌فرض، کلاس به شناسایی نوع MIME برای ارزیابی این که آیا فایل می‌تواند آپلود شود یا خیر، متکی است. چندین روش شناسایی MIME بسته به تنظیمات سرور استفاده می‌شود. این کلاس به یک لیست سیاه از پسوندهای فایل خطرناک برای جلوگیری از آپلود (یا تغییر نام اسکریپت‌های خطرناک به فایل‌های متنی) و یک لیست سفید از انواع MIME پذیرفته شده، متکی است.

اما هدف این کلاس انجام بررسی‌های عمیق و شناسایی فایل‌های مخرب نیست. به عنوان مثال، یک حمله‌کننده می‌تواند فایلی ایجاد کند که نوع MIME صحیحی داشته باشد، اما حاوی بار مخرب باشد، مانند یک فایل GIF معتبر که شامل کدی باشد که منجر به آسیب‌پذیری XSS می‌شود. اگر این فایل GIF دارای پسوند .html باشد، ممکن است آپلود شود (بسته به تنظیمات کلاس) و یک آسیب‌پذیری XSS را نشان دهد.

با این حال، شما می‌توانید این مسئله را با محدود کردن نوع فایل‌هایی که می‌توانند آپلود شوند، با استفاده از allowed و forbidden بر اساس نوع MIME یا پسوند فایل، برطرف کنید. امن‌ترین گزینه این است که فقط پسوندهای مورد نظر خود را در لیست سفید قرار دهید و اطمینان حاصل کنید که سرور همیشه فایل‌ها را با نوع محتوا بر اساس پسوند فایل ارسال می‌کند.

$handle->allowed = array('html');
$handle->forbidden = array();
$handle->no_script = false;
        

در نهایت، مسئولیت شماست که مطمئن شوید فایل‌های صحیح آپلود می‌شوند. اما مهم‌تر از همه، مسئولیت شماست که فایل‌های آپلود شده را به درستی ارائه دهید، مثلاً با اجبار سرور برای همیشه ارائه نوع محتوا بر اساس پسوند فایل.

عیب‌یابی

اگر کلاس آنطور که می‌خواهید عمل نمی‌کند، می‌توانید لاگ را نمایش دهید تا جزئیات دقیق‌تری از عملکرد کلاس مشاهده کنید. برای به دست آوردن لاگ، فقط این خط را در انتهای کد خود اضافه کنید:

echo $handle->log;
        

ممکن است مشکل شما قبلاً در سوالات متداول مورد بحث قرار گرفته باشد.

در غیر این صورت، می‌توانید در فروم‌ها جستجو کرده و سوال خود را بپرسید. لطفاً از مطرح کردن سوالات در مسائل GitHub خودداری کنید.

مدیریت فایل (File handling)

• file_new_name_body
  بدنه‌ی نام فایل را جایگزین می‌کند (پیش‌فرض: null)

  $handle->file_new_name_body = 'new name';

• file_name_body_add
  به انتهای بدنه‌ی نام فایل اضافه می‌کند (پیش‌فرض: null)

  $handle->file_name_body_add = '_uploaded';

• file_name_body_pre
  به ابتدای بدنه‌ی نام فایل اضافه می‌کند (پیش‌فرض: null)

  $handle->file_name_body_pre = 'thumb_';

• file_new_name_ext
  پسوند فایل را جایگزین می‌کند (پیش‌فرض: null)

  $handle->file_new_name_ext = 'txt';

• file_safe_name
  نام فایل را فرمت‌گذاری می‌کند (تبدیل فاصله به زیرخط، حذف نویسه‌های خاص و...)
  (پیش‌فرض: true)

  $handle->file_safe_name = true;

• file_force_extension
  در صورت نبودن پسوند، آن را به‌اجبار اضافه می‌کند (پیش‌فرض: true)

  $handle->file_force_extension = true;

• file_overwrite
  رفتار در صورت وجود فایل همنام را تعیین می‌کند (بازنویسی یا خیر) (پیش‌فرض: false)

  $handle->file_overwrite = true;

• file_auto_rename
  در صورت تکراری بودن نام، فایل را به‌صورت خودکار تغییر نام می‌دهد (پیش‌فرض: true)

  $handle->file_auto_rename = true;

• dir_auto_create
  اگر پوشه مقصد وجود نداشته باشد، آن را به‌صورت خودکار ایجاد می‌کند (پیش‌فرض: true)

  $handle->dir_auto_create = true;

• dir_auto_chmod
  اگر پوشه مقصد غیرقابل‌نوشتن باشد، تلاش می‌کند سطح دسترسی را تغییر دهد (پیش‌فرض: true)

  $handle->dir_auto_chmod = true;

• dir_chmod
  سطح دسترسی استفاده‌شده هنگام ایجاد پوشه (پیش‌فرض: 0777)

  $handle->dir_chmod = 0777;

• file_max_size
  حداکثر اندازه مجاز برای آپلود فایل (پیش‌فرض: مقدار تنظیم‌شده در php.ini)

  $handle->file_max_size = '1024'; // معادل 1KB

• mime_check
  مشخص می‌کند آیا نوع MIME بررسی شود یا نه (پیش‌فرض: true)

  $handle->mime_check = true;

• no_script
  اگر فعال باشد، فایل‌های دارای اسکریپت را به فایل متنی تبدیل می‌کند (پیش‌فرض: true)

  $handle->no_script = false;

• allowed
  لیستی از MIMEهای مجاز یا پسوندها (به‌صورت آرایه یا رشته) – پشتیبانی از wildcard مانند image/* (پیش‌فرض: باید تعریف شود)

  $handle->allowed = array('application/pdf','application/msword', 'image/*');

• forbidden
  لیستی از MIMEهای ممنوع یا پسوندهای غیرمجاز (پیش‌فرض: باید تعریف شود)

  $handle->forbidden = array('application/*');

مدیریت تصویر (Image handling)

• image_convert
  اگر مقداردهی شود، تصویر به فرمتی دیگر تبدیل می‌شود (مقادیر مجاز: 'png', 'webp', 'jpeg', 'gif', 'bmp') (پیش‌فرض: '')

  $handle->image_convert = 'jpg';

• image_background_color
  اگر مقداردهی شود، نواحی شفاف تصویر با رنگ مشخص‌شده پر می‌شوند (در قالب Hex) (پیش‌فرض: null)

  $handle->image_background_color = '#FF00FF';

• image_default_color
  رنگ پس‌زمینه پیش‌فرض برای فرمت‌هایی که شفافیت ندارند مانند JPEG یا BMP (پیش‌فرض: #FFFFFF)

  $handle->image_default_color = '#FF00FF';

• png_compression
  سطح فشرده‌سازی برای تصاویر PNG (بین 1 تا 9 – 1 سریع‌تر، 9 کم‌حجم‌تر) (پیش‌فرض: null یعنی مقدار Zlib)

  $handle->png_compression = 9;

• webp_quality
  کیفیت فشرده‌سازی تصاویر WebP (پیش‌فرض: 85)

  $handle->webp_quality = 50;

• jpeg_quality
  کیفیت فشرده‌سازی تصاویر JPEG (پیش‌فرض: 85)

  $handle->jpeg_quality = 50;

• jpeg_size
  اگر مقداردهی شود، کیفیت JPEG طوری تنظیم می‌شود که حجم تصویر خروجی از مقدار مشخص‌شده بیشتر نباشد (برحسب بایت)

  $handle->jpeg_size = 3072;

• image_interlace
  اگر مقدار true داشته باشد، تصویر به‌صورت progressive ذخیره می‌شود (مخصوص JPEG) (پیش‌فرض: false)

  $handle->image_interlace = true;

بررسی تصویر (Image Checking)

⚠️ نکته: استفاده از این تنظیمات ممکن است در صورت فعال بودن محدودیت open_basedir در PHP، عمل نکند.

• image_max_width
  اگر مقداردهی شود، در صورتی که عرض تصویر بیشتر از این مقدار باشد، آپلود نامعتبر خواهد بود.

  $handle->image_max_width = 200;

  
  (پیش‌فرض: null)

• image_max_height
  اگر مقداردهی شود، در صورتی که ارتفاع تصویر بیشتر از این مقدار باشد، آپلود نامعتبر خواهد بود.

  $handle->image_max_height = 100;

  
  (پیش‌فرض: null)

• image_max_pixels
  اگر مقداردهی شود، در صورتی که تعداد پیکسل‌های تصویر بیشتر از این مقدار باشد، آپلود نامعتبر خواهد بود.

  $handle->image_max_pixels = 50000;

  
  (پیش‌فرض: null)

• image_max_ratio
  اگر نسبت ابعاد (عرض/ارتفاع) تصویر بیشتر از این مقدار باشد، آپلود نامعتبر خواهد بود.

  $handle->image_max_ratio = 1.5;

  
  (پیش‌فرض: null)

• image_min_width
  اگر عرض تصویر کمتر از این مقدار باشد، آپلود نامعتبر خواهد بود.

  $handle->image_min_width = 100;

  
  (پیش‌فرض: null)

• image_min_height
  اگر ارتفاع تصویر کمتر از این مقدار باشد، آپلود نامعتبر خواهد بود.

  $handle->image_min_height = 500;

  
  (پیش‌فرض: null)

• image_min_pixels
  اگر تعداد پیکسل‌های تصویر کمتر از این مقدار باشد، آپلود نامعتبر خواهد بود.

  $handle->image_min_pixels = 20000;

  
  (پیش‌فرض: null)

• image_min_ratio
  اگر نسبت ابعاد تصویر کمتر از این مقدار باشد، آپلود نامعتبر خواهد بود.

  $handle->image_min_ratio = 0.5;

  
  (پیش‌فرض: null)

تغییر اندازه تصویر (Image Resizing)

• image_resize
  مشخص می‌کند که آیا تصویر تغییر اندازه داده شود یا نه.

  $handle->image_resize = true;

  
  (پیش‌فرض: false)

⚙️ اگر image_resize فعال باشد، تنظیمات زیر نیز قابل استفاده خواهند بود:

• image_x
  عرض تصویر خروجی (برحسب پیکسل)

  $handle->image_x = 100;

  
  (پیش‌فرض: 150)

• image_y
  ارتفاع تصویر خروجی (برحسب پیکسل)

  $handle->image_y = 200;

  
  (پیش‌فرض: 150)

کنترل نسبت‌ها هنگام تغییر اندازه

• image_ratio
  اگر فعال باشد، نسبت ابعاد اصلی حفظ شده و image_x و image_y به عنوان حداکثر اندازه استفاده می‌شوند.

  $handle->image_ratio = true;

  
  (پیش‌فرض: false)

• image_ratio_crop
  تصویر با حفظ نسبت اصلی تغییر اندازه داده می‌شود و برای پر کردن فضا، اضافات بریده می‌شود.
  می‌توان از حروف T, B, L, R برای مشخص کردن اولویت برش استفاده کرد.

  $handle->image_ratio_crop = true;

  
  (پیش‌فرض: false)

• image_ratio_fill
  تصویر با حفظ نسبت اصلی تغییر اندازه داده می‌شود و فضای باقی‌مانده با رنگ پر می‌شود.
  می‌توان مشخص کرد تصویر در کدام بخش قرار گیرد (T, B, L, R).

  $handle->image_ratio_fill = true;

  
  (پیش‌فرض: false)

• image_ratio_x
  اگر فعال باشد، image_x به‌صورت خودکار از روی image_y محاسبه می‌شود.

  $handle->image_ratio_x = true;

  
  (پیش‌فرض: false)

• image_ratio_y
  اگر فعال باشد، image_y به‌صورت خودکار از روی image_x محاسبه می‌شود.

  $handle->image_ratio_y = true;

  
  (پیش‌فرض: false)

• image_ratio_pixels
  با تعیین تعداد پیکسل کلی، اندازه تصویر طوری تنظیم می‌شود که تعداد پیکسل خروجی مطابق با مقدار مشخص‌شده باشد.

  $handle->image_ratio_pixels = 25000;

  
  (پیش‌فرض: false)

جلوگیری از بزرگ یا کوچک شدن بیش‌ازحد تصویر

• image_no_enlarging
  اگر فعال باشد، از بزرگ‌نمایی تصویر هنگام تغییر اندازه جلوگیری می‌شود.

  $handle->image_no_enlarging = true;

  
  (پیش‌فرض: false)

• image_no_shrinking
  اگر فعال باشد، از کوچک‌ شدن بیش‌ازحد تصویر هنگام تغییر اندازه جلوگیری می‌شود.

  $handle->image_no_shrinking = true;

  
  (پیش‌فرض: false)

🎨 افکت‌های تصویر (Image Effects)

⚠️ این افکت‌ها نیاز به کتابخانه GD2 در PHP دارند.

• image_brightness
  تنظیم روشنایی تصویر. مقدار بین -127 تا 127

  $handle->image_brightness = 40;

  
  (پیش‌فرض: null)

• image_contrast
  تنظیم کنتراست تصویر. مقدار بین -127 تا 127

  $handle->image_contrast = 50;

  
  (پیش‌فرض: null)

• image_opacity
  تنظیم میزان شفافیت کل تصویر. مقدار بین 0 تا 100

  $handle->image_opacity = 50;

  
  (پیش‌فرض: null)

• image_tint_color
  رنگ‌دهی کلی به تصویر با استفاده از رنگ (هگزادسیمال)

  $handle->image_tint_color = '#FF0000';

  
  (پیش‌فرض: null)

• image_overlay_color
  قرار دادن لایهٔ رنگی روی تصویر (رنگ به صورت هگزادسیمال)

  $handle->image_overlay_color = '#FF0000';

  
  (پیش‌فرض: null)

• image_overlay_opacity
  تعیین میزان شفافیت برای لایهٔ رنگی افزوده‌شده

  $handle->image_overlay_opacity = 20;

  
  (پیش‌فرض: 50)

• image_negative
  معکوس‌کردن رنگ‌ها (نگاتیو)

  $handle->image_negative = true;

  
  (پیش‌فرض: false)

• image_greyscale
  تبدیل تصویر به سیاه‌ و سفید

  $handle->image_greyscale = true;

  
  (پیش‌فرض: false)

• image_threshold
  اعمال فیلتر آستانه. مقدار بین -127 تا 127

  $handle->image_threshold = 20;

  
  (پیش‌فرض: null)

• image_pixelate
  پیکسلی کردن تصویر. مقدار برابر با اندازه بلوک‌ها

  $handle->image_pixelate = 10;

  
  (پیش‌فرض: null)

• image_unsharp
  فعال‌کردن ماسک unsharp برای افزایش وضوح تصویر

  $handle->image_unsharp = true;

  
  (پیش‌فرض: false)

• image_unsharp_amount
  شدت ماسک Unsharp. مقدار معمول بین 50 تا 200

  $handle->image_unsharp_amount = 120;

  
  (پیش‌فرض: 80)

• image_unsharp_radius
  شعاع ماسک Unsharp. مقدار معمول بین 0.5 تا 1

  $handle->image_unsharp_radius = 1;

  
  (پیش‌فرض: 0.5)

• image_unsharp_threshold
  آستانهٔ ماسک Unsharp. مقدار معمول بین 0 تا 5

  $handle->image_unsharp_threshold = 0;

  
  (پیش‌فرض: 1)

✍️ نوشتن متن روی تصویر (Image Text)

• image_text
  اضافه‌کردن متن روی تصویر. مقدار یک رشته (string) است

  $handle->image_text = 'test';

  
  (پیش‌فرض: null)

• image_text_direction
  جهت متن: 'h' برای افقی و 'v' برای عمودی

  $handle->image_text_direction = 'v';

  
  (پیش‌فرض: 'h')

• image_text_color
  رنگ متن به صورت کد هگزادسیمال

  $handle->image_text_color = '#FF0000';

  
  (پیش‌فرض: #FFFFFF)

• image_text_opacity
  میزان شفافیت متن. عددی بین 0 تا 100

  $handle->image_text_opacity = 50;

  
  (پیش‌فرض: 100)

• image_text_background
  رنگ پس‌زمینه متن. مقدار هگزادسیمال

  $handle->image_text_background = '#FFFFFF';

  
  (پیش‌فرض: null)

• image_text_background_opacity
  شفافیت پس‌زمینه متن. عدد بین 0 تا 100

  $handle->image_text_background_opacity = 50;

  
  (پیش‌فرض: 100)

• image_text_font
  فونت داخلی بین 1 تا 5، یا مسیر یک فونت TrueType یا GDF

  $handle->image_text_font = 4;
  مثال: './font.ttf'

• image_text_size
  اندازه فونت (در پیکسل یا پوینت برای فونت‌های TrueType)

  $handle->image_text_size = 24;

  
  (پیش‌فرض: 16)

• image_text_angle
  زاویه متن (درجه)، صفر به معنای متن از چپ به راست است

  $handle->image_text_angle = 45;

  
  (پیش‌فرض: null)

• image_text_x
  موقعیت افقی مطلق متن از لبه چپ تصویر. می‌تواند منفی باشد

  $handle->image_text_x = 5;

  
  (پیش‌فرض: null)

• image_text_y
  موقعیت عمودی مطلق متن از لبه بالا. می‌تواند منفی باشد

  $handle->image_text_y = 5;

  
  (پیش‌فرض: null)

• image_text_position
  موقعیت نسبی متن در تصویر. ترکیبی از حروف 'TBLR'

  $handle->image_text_position = 'LR';

  
  (پیش‌فرض: null)

• image_text_padding
  فاصله (padding) کلی متن از کناره‌ها (پیکسل)

  $handle->image_text_padding = 5;

  
  (پیش‌فرض: 0)

• image_text_padding_x
  فاصله افقی اختصاصی متن

  $handle->image_text_padding_x = 2;

  
  (پیش‌فرض: null)

• image_text_padding_y
  فاصله عمودی اختصاصی متن

  $handle->image_text_padding_y = 10;

  
  (پیش‌فرض: null)

• image_text_alignment
  ترازبندی متن چند خطی: 'L' (چپ)، 'C' (وسط)، 'R' (راست)

  $handle->image_text_alignment = 'R';

  
  (پیش‌فرض: 'C')

• image_text_line_spacing
  فاصله بین خطوط در متن چندخطی (پیکسل)

  $handle->image_text_line_spacing = 3;

  
  (پیش‌فرض: 0)

🔄 تبدیلات تصویر (Image Transformations)

• image_auto_rotate
  چرخش خودکار تصویر براساس اطلاعات EXIF (فقط JPEG)
  $handle->image_auto_rotate = false;
  (پیش‌فرض: true)

• image_flip
  برعکس کردن تصویر: 'h' برای افقی، 'v' برای عمودی
  $handle->image_flip = 'h';
  (پیش‌فرض: null)

• image_rotate
  چرخش تصویر. مقادیر مجاز: ۹۰، ۱۸۰، ۲۷۰ درجه

  $handle->image_rotate = 90;

  
  (پیش‌فرض: null)

• image_crop
  برش تصویر. می‌توان به صورت آرایه یا رشته وارد کرد (مثلاً: 'T R B L' یا '20%' یا array(10, 20, 10, 20))

  $handle->image_crop = array(50,40,30,20);

• image_precrop
  برش تصویر پیش از تغییر اندازه. فرمت مشابه image_crop

  $handle->image_precrop = '-20 20%';

🖼️ قاب و کادر تصویر (Image Borders)

• image_bevel
  افزودن قاب بُرآمده (bevel). مقدار برابر با ضخامت قاب به پیکسل

  $handle->image_bevel = 20;

• image_bevel_color1
  رنگ بالایی و چپ قاب بُرآمده (hex)

  $handle->image_bevel_color1 = '#FFFFFF';

• image_bevel_color2
  رنگ پایین و راست قاب بُرآمده (hex)

  $handle->image_bevel_color2 = '#000000';

• image_border
  افزودن کادر ساده. مقدار می‌تواند یک عدد، درصد یا آرایه باشد

  $handle->image_border = '3px'; یا array(3, 2);

• image_border_color
  رنگ کادر (hex)

  $handle->image_border_color = '#FFFFFF';

• image_border_opacity
  شفافیت کادر. عددی بین 0 تا 100

  $handle->image_border_opacity = 50;

• image_border_transparent
  کادری با محوشدگی تدریجی تا شفاف

  $handle->image_border_transparent = '3px';

• image_frame
  نوع قاب تصویری: 1 = تخت، 2 = ضربدری

  $handle->image_frame = 2;

• image_frame_colors
  رنگ‌های قاب به صورت آرایه یا رشته جدا شده با فاصله

  $handle->image_frame_colors = array('#999999', '#FF0000', '#666666');

• image_frame_opacity
  شفافیت قاب. مقدار بین 0 تا 100

  $handle->image_frame_opacity = 50;

💧 واترمارک تصویر (Image Watermark)

• image_watermark
  افزودن تصویر واترمارک. مقدار باید مسیر فایل محلی باشد

  $handle->image_watermark = 'watermark.png';

• image_watermark_x
  موقعیت افقی واترمارک (پیکسل از سمت چپ). قابل منفی

  $handle->image_watermark_x = 5;

• image_watermark_y
  موقعیت عمودی واترمارک (پیکسل از بالا). قابل منفی

  $handle->image_watermark_y = 5;

• image_watermark_position
  موقعیت واترمارک داخل تصویر. ترکیبی از 'TBLR'

  $handle->image_watermark_position = 'LR';

• image_watermark_no_zoom_in
  جلوگیری از بزرگ‌نمایی واترمارک اگر کوچک‌تر از تصویر باشد

  $handle->image_watermark_no_zoom_in = false;

  
  (پیش‌فرض: true)

• image_watermark_no_zoom_out
  جلوگیری از کوچک‌نمایی واترمارک اگر بزرگ‌تر از تصویر باشد

  $handle->image_watermark_no_zoom_out = true;

  
  (پیش‌فرض: false)

🔁 بازتاب تصویر (Image Reflection)

• image_reflection_height
  فعال‌سازی بازتاب تصویر. مقدار بر حسب پیکسل یا درصد

  $handle->image_reflection_height = '25%';

• image_reflection_space
  فاصله بین تصویر اصلی و بازتاب (قابل منفی)

  $handle->image_reflection_space = 3;

• image_reflection_color
  رنگ پس‌زمینهٔ بازتاب (ترجیحاً از image_default_color استفاده شود)

  $handle->image_default_color = '#000000';

• image_reflection_opacity
  شفافیت ابتدایی بازتاب. عددی بین 0 تا 100

  $handle->image_reflection_opacity = 60;

📥 مقادیر قابل خواندن قبل از process()

📤 مقادیر قابل خواندن بعد از process()

📌 پیش‌نیازها

• بیشتر ویژگی‌های پردازش تصویر نیاز به GD یا GD2 دارند.

• نسخه 1.x با PHP 4، 5 و 7 سازگار است ولی namespaced نیست.

• نسخه 2.x با PHP 5.3+، 7 و 8 کاملاً سازگار است و namespaced می‌باشد.