تابع wp_update_attachment_metadata در وردپرس

تابع wp_update_attachment_metadata() یکی از توابع کلیدی وردپرس برای مدیریت متادیتای فایل‌های ضمیمه (attachments) است. این تابع وقتی کاربرد دارد که پس از آپلود یا پردازش تصویر بخواهیم اطلاعات مربوط به اندازه‌ها، مسیر فایل‌ها و سایر متادیتاها را در پایگاه‌داده ذخیره یا به‌روز کنیم.

چرا متادیتای ضمیمه مهم است؟

وردپرس برای تصاویر چند اندازه (thumbnail، medium، large و اندازه‌های تعریف‌شده توسط پوسته یا افزونه) ایجاد می‌کند. اطلاعات مربوط به این اندازه‌ها و فایل‌ها در فیلد متا با کلید _wp_attachment_metadata ذخیره می‌شود. بسیاری از توابع نمایش تصویر مثل wp_get_attachment_image_src() یا wp_get_attachment_image() از این متادیتا استفاده می‌کنند.

تعریف کلی تابع

تابع:

wp_update_attachment_metadata( int $attachment_id, array $data ) : array|false

پارامترها:

$attachment_id: شناسه پست از نوع attachment.
$data: آرایه متادیتای تولیدشده معمولاً توسط wp_generate_attachment_metadata().

خروجی: آرایه متادیتای ذخیره‌شده در صورت موفقیت یا false در صورت شکست.

ساختار متادیتا (نمونه)

کلید	توضیح
file	مسیر نسبی فایل اصلی نسبت به uploads
width / height	ابعاد تصویر اصلی
sizes	آرایه‌ای از اندازه‌های تولیدشده؛ شامل file, width, height, mime-type
image_meta	اطلاعات EXIF/ایجاد دوربین مانند aperture, focal_length و غیره

نمونه کاربرد ساده

// 1. فرض: فایل آپلود شده و شناسه ضمیمه $attachment_id موجود است.
// 2. تولید متادیتا با استفاده از wp_generate_attachment_metadata
$metadata = wp_generate_attachment_metadata( $attachment_id, get_attached_file( $attachment_id ) );

// 3. ذخیره یا به‌روزرسانی متادیتا در پایگاه‌داده
wp_update_attachment_metadata( $attachment_id, $metadata );

توضیح: این کد ابتدا متادیتا را با تابع wp_generate_attachment_metadata می‌سازد (که اندازه‌های مختلف تصویر را ایجاد و آرایه متادیتا را برمی‌گرداند). سپس با wp_update_attachment_metadata این آرایه در جدول postmeta ذخیره می‌شود.

حالت‌های پیشرفته و نمونه‌های واقعی

بازسازی اندازه‌ها به‌صورت برنامه‌ای:اگر پس از تغییر اندازه‌های تعریف‌شده در theme یا افزودن سایز جدید بخواهید برای تصاویر قبلی thumbnail جدید تولید کنید، می‌توانید برای هر attachment این مراحل را اجرا کنید:
```
// بازسازی تصاویر برای یک attachment مشخص
if ( wp_attachment_is_image( $attachment_id ) ) {
    $file = get_attached_file( $attachment_id );
    // تولید متادیتا جدید و ایجاد اندازه‌ها
    $metadata = wp_generate_attachment_metadata( $attachment_id, $file );
    // ذخیره متادیتا جدید
    wp_update_attachment_metadata( $attachment_id, $metadata );
}
```
این کد ابتدا بررسی می‌کند که فایل یک تصویر باشد، سپس فایل را پردازش و متادیتای جدید را ذخیره می‌کند.

حذف یک اندازه خاص و به‌روزرسانی متادیتا:

// حذف اندازه 'medium' از متادیتا و حذف فایل مربوطه
$meta = wp_get_attachment_metadata( $attachment_id );

if ( isset( $meta['sizes']['medium'] ) ) {
    $uploads = wp_get_upload_dir();
    $medium_file = path_join( $uploads['basedir'], dirname( $meta['file'] ) . '/' . $meta['sizes']['medium']['file'] );

    if ( file_exists( $medium_file ) ) {
        unlink( $medium_file );
    }

    unset( $meta['sizes']['medium'] );
    wp_update_attachment_metadata( $attachment_id, $meta );
}

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

نکات امنیتی و مجوزها

قبل از ویرایش فایل‌های آپلود، مطمئن شوید که کاربر مجوزهای لازم را دارد (مثلاً capabilityهایی مانند edit_post یا upload_files).
بررسی کنید فایل‌های حذف‌شده واقعاً در مسیر uploads باشند تا از حذف ناخواسته فایل‌های سیستمی جلوگیری شود.
تابع wp_update_attachment_metadata فقط متادیتا در دیتابیس را بروز می‌کند؛ تغییر فایل‌های روی دیسک نیاز به عملیات فایل‌سیستمی دارد و خطاهای I/O باید مدیریت شوند.

بهینه‌سازی و نکات عملکرد

برای بازسازی تصاویر در سایت‌های بزرگ، از پردازش دسته‌ای (batch) استفاده کنید تا مصرف حافظه و زمان اجرا کنترل شود.
فونکشن wp_generate_attachment_metadata ممکن است از کتابخانه‌های تصویر (GD یا ImageMagick) استفاده کند؛ بررسی کنید سرور تنظیمات لازم را دارد.
در افزونه‌ها، از فیلترها و اکشن‌های مرتبط مثل intermediate_image_sizes_advanced و image_make_intermediate_size برای کنترل خروجی استفاده کنید.

ادغام با عملیات آپلود سفارشی

اگر از فیلترها یا اکشن‌های سفارشی در زمان آپلود استفاده می‌کنید، می‌توانید پس از بارگذاری فایل متادیتا را بسازید و ذخیره کنید:

add_filter( 'wp_handle_upload', 'my_handle_upload', 10, 2 );
function my_handle_upload( $upload, $context ) {
    if ( ! empty( $upload['file'] ) && isset( $context['id'] ) ) {
        $id = $context['id'];
        // اگر فایل یک تصویر باشد متادیتا تولید و ذخیره شود
        if ( wp_attachment_is_image( $id ) ) {
            $metadata = wp_generate_attachment_metadata( $id, $upload['file'] );
            wp_update_attachment_metadata( $id, $metadata );
        }
    }
    return $upload;
}

توضیح: این کد از فیلتر wp_handle_upload استفاده می‌کند تا بعد از آپلود فایل برای attachment مربوطه متادیتای تصویر را تولید و ذخیره کند.

سخن پایانی و نکات تخصصی

تابع wp_update_attachment_metadata() ابزار ساده اما حیاتی برای همگام‌سازی اطلاعات دیتابیسی با فایل‌های سیستم است. در پروژه‌های پیچیده‌تر، ترکیب آن با wp_generate_attachment_metadata، مدیریت فایل‌ها و کنترل دسترسی‌ها باعث می‌شود فرایند مدیریت رسانه در وردپرس پایدار و قابل اتکا باشد.

در صورتی که نیاز به نمونه‌کد خاص برای سناریوی شما (مثلاً بازسازی تمام تصاویر یک دسته یا ادغام با CDN) دارید، می‌توان کدهای نمونه و نکات پیاده‌سازی را دقیق‌تر بررسی کرد.

آیا این مطلب برای شما مفید بود ؟

خیر

بله