آموزش تابع wp_handle_upload() در وردپرس و کاربرد آن

تابع wp_handle_upload() یکی از ابزارهای اصلی وردپرس برای پردازش آپلود فایل‌هاست. این تابع فایل ارسالی از فرم (مثلاً از طریق $_FILES) را دریافت، اعتبارسنجی، نام‌گذاری امن و به مسیر آپلود انتقال می‌دهد و در نهایت اطلاعات مسیر و آدرس فایل را برمی‌گرداند. در این مقاله به شکل دقیق، مثال‌های کاربردی، نکات امنیتی و روش‌های توسعه آن می‌پردازیم.

مختصر: چه چیزی برمی‌گردد و پارامترها

امضای تابع:

wp_handle_upload( $file, $overrides = array(), $time = null )

توضیح پارامترها:

• $file: معمولاً یکی از اعضای $_FILES مانند $_FILES['myfile'].
• $overrides: آرایه‌ای برای تغییر رفتار پیش‌فرض (مانند test_form، mimes). مثال: array('test_form' => false).
• $time: اگر بخواهید پوشه تاریخ آپلود (yyyy/mm) متفاوت باشد می‌توانید مقدار زمان دلخواه بدهید.

مقدار بازگشتی: در صورت موفقیت آرایه‌ای با کلیدهای file (مسیر سرور)، url (آدرس قابل دسترسی) و type (MIME) و در صورت خطا کلید error را خواهید داشت.

مثال پایه: آپلود از فرم در فرانت‌اند

if ( ! function_exists( 'wp_handle_upload' ) ) {
    require_once( ABSPATH . 'wp-admin/includes/file.php' );
}

$uploadedfile = $_FILES['my_file'];

$upload_overrides = array( 'test_form' => false );

$movefile = wp_handle_upload( $uploadedfile, $upload_overrides );

if ( $movefile && ! isset( $movefile['error'] ) ) {
    echo "File is valid, and was successfully uploaded.n";
    echo "URL: " . $movefile['url'];
} else {
    echo $movefile['error'];
}

توضیح: در این کد ابتدا مطمئن می‌شویم فایل‌های مدیریت آپلود لود شده‌اند. سپس با تعیین test_form روی false از محدودیت بررسی فرم جلوگیری می‌کنیم (برای پردازش‌های برنامه‌نویسی و فرم‌های فرانت‌اند که ممکن است nonce متفاوت باشد). پس از اجرای تابع، یا مسیر و آدرس فایل را می‌گیریم یا پیام خطا را نمایش می‌دهیم.

اتصال فایل به کتابخانه رسانه (Attachment)

معمولاً بعد از آپلود می‌خواهید فایل را به عنوان رسانه ثبت کنید تا در کتابخانه نمایش داده شود. نمونه کامل زیر روند آپلود، درج اتچمنت و تولید متادیتا را نشان می‌دهد:

require_once( ABSPATH . 'wp-admin/includes/file.php' );
require_once( ABSPATH . 'wp-admin/includes/image.php' );
require_once( ABSPATH . 'wp-admin/includes/media.php' );

$uploadedfile = $_FILES['my_file'];
$upload_overrides = array( 'test_form' => false );

$movefile = wp_handle_upload( $uploadedfile, $upload_overrides );

if ( isset( $movefile['error'] ) ) {
    // handle error
} else {
    $file_path = $movefile['file'];
    $file_url  = $movefile['url'];
    $file_type = wp_check_filetype( basename( $file_path ), null );

    $attachment = array(
        'guid'           => $file_url,
        'post_mime_type' => $file_type['type'],
        'post_title'     => sanitize_file_name( basename( $file_path ) ),
        'post_content'   => '',
        'post_status'    => 'inherit'
    );

    $attach_id = wp_insert_attachment( $attachment, $file_path );
    $attach_data = wp_generate_attachment_metadata( $attach_id, $file_path );
    wp_update_attachment_metadata( $attach_id, $attach_data );
}

توضیح: پس از آپلود، با wp_insert_attachment یک رکورد رسانه جدید ساخته و سپس با wp_generate_attachment_metadata تصاویر بندانگشتی و متادیتا را تولید و ذخیره می‌کنیم. این روش باعث می‌شود فایل در کتابخانه وردپرس قابل مدیریت باشد.

فیلترها و تغییر رفتار: wp_handle_upload_prefilter و wp_handle_upload

دو فیلتر مهم وجود دارد:

• wp_handle_upload_prefilter: قبل از انتقال فایل اجرا می‌شود و می‌توانید فایل را تغییر دهید یا رد کنید.
• wp_handle_upload: پس از جابجایی فایل اجرا می‌شود و آرایه نتیجه قابل تغییر است.

add_filter( 'wp_handle_upload_prefilter', 'my_upload_prefilter' );
function my_upload_prefilter( $file ) {
    // منع آپلود فایل‌های بزرگ‌تر از 2MB
    if ( $file['size'] > 2 * 1024 * 1024 ) {
        $file['error'] = 'File is too large.';
    }
    return $file;
}

توضیح: این کد از طریق فیلتر پیش از انتقال، اندازه فایل را بررسی و در صورت بزرگ بودن خطا اضافه می‌کند. اگر $file['error'] تنظیم شود فرایند متوقف می‌شود.

ملاحظات امنیتی و بهترین شیوه‌ها

• همیشه اعتبارسنجی و بررسی حقوق کاربر را انجام دهید (مثلاً current_user_can('upload_files') یا بررسی nonce).
• از wp_check_filetype() برای بررسی نوع فایل و جلوگیری از آپلود اسکریپت‌های مخرب استفاده کنید.
• فایل‌ها را با sanitize_file_name() یا توابع مشابه پاک‌سازی کنید و از اجرای PHP در پوشه uploads جلوگیری کنید (تنظیم وب‌سرور یا فایل .htaccess).
• محدودیت اندازه و نوع MIME را اعمال کنید. به خاطر داشته باشید MIME توسط کاربر قابل دستکاری است؛ پس از سرور نیز بررسی سطح بالاتر انجام دهید.
• برای آپلودهای برنامه‌ای یا API، 'test_form' => false را استفاده کنید اما جایگزین‌های امنیتی (توکن، کلید API) قرار دهید.

نمونه: اعمال لیست MIME مجاز

$allowed_mimes = array(
    'jpg|jpeg|jpe' => 'image/jpeg',
    'png' => 'image/png',
    'gif' => 'image/gif',
    'pdf' => 'application/pdf'
);

$upload_overrides = array(
    'test_form' => false,
    'mimes'     => $allowed_mimes
);

$movefile = wp_handle_upload( $_FILES['my_file'], $upload_overrides );

توضیح: با تعیین mimes، وردپرس تنها فرمت‌های مشخص‌شده را می‌پذیرد. این کار امنیت را افزایش می‌دهد و برای فرم‌های محدود مفید است.

خلاصه و نکات تکمیلی

• wp_handle_upload() یک راه مطمئن و استاندارد برای انتقال فایل به پوشه uploads و دریافت اطلاعات آن است.
• برای ادغام با کتابخانه رسانه، پس از آپلود از wp_insert_attachment و wp_generate_attachment_metadata استفاده کنید.
• همیشه کنترل دسترسی، بررسی MIME و محدودیت اندازه را در نظر بگیرید.
• از فیلترهای ارائه‌شده برای سفارشی‌سازی رفتار آپلود استفاده کنید.

جدول: کلیدهای بازگشتی رایج

با درک دقیق ورودی‌ها، فیلترها و رفتار پیش‌فرض، می‌توانید از wp_handle_upload() برای ساخت فرم‌های آپلود امن، پردازش فایل در پلاگین‌ها و ادغام با کتابخانه رسانه استفاده کنید.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال