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

تابع wp_generate_attachment_metadata() یکی از توابع مهم وردپرس برای تولید متادیتای پیوست‌ها (attachments) است. این تابع معمولاً پس از آپلود فایل فراخوانی می‌شود و برای فایل‌های تصویری، نسخه‌های متوسط و کوچک (intermediate sizes)، اطلاعات ابعادی و متادیتاهای EXIF/IPP را تولید می‌کند. در این مقاله به صورت عملی و حرفه‌ای این تابع، پارامترها، ساختار خروجی، استفاده‌های رایج و نکات عیب‌یابی را بررسی می‌کنیم.

امکان‌سنجی و سینتکس تابع

سینتکس اصلی:

$metadata = wp_generate_attachment_metadata( $attachment_id, $file = null );

پارامترها:

• $attachment_id: شناسه پست پیوست (attachment post ID).
• $file: مسیر فایل فیزیکی در سیستم فایل (اختیاری). اگر مشخص نشود، تابع از get_attached_file() استفاده می‌کند.

چه خروجی‌ای برمی‌گرداند؟

خروجی یک آرایهٔ ساختاریافته است که برای تصویر شامل اطلاعاتی مانند فایل اصلی، عرض و ارتفاع، آرایه sizes و image_meta می‌شود. برای فایل‌های غیر‌تصویری معمولاً فقط مقدار ‘file’ بازگردانده شده و آرایه sizes خالی یا محدود است.

نمونهٔ کاربرد: تولید دستی متادیتا و ذخیره

$file = get_attached_file( $attachment_id );
$metadata = wp_generate_attachment_metadata( $attachment_id, $file );

if ( ! is_wp_error( $metadata ) && ! empty( $metadata ) ) {
    wp_update_attachment_metadata( $attachment_id, $metadata );
}

این کد مسیر فایل را گرفته، metadata تولید می‌کند و سپس با wp_update_attachment_metadata آن را در پایگاه‌داده ذخیره می‌کند. کاربرد معمول: بازتولید اندازه‌ها بعد از اضافه کردن image size جدید یا پس از تبدیل فرمت.

مثال عملی‌تر: بازتولید برای تمام پیوست‌ها

$attachments = get_posts( array(
  'post_type'      => 'attachment',
  'posts_per_page' => -1,
  'post_status'    => 'inherit',
) );

foreach ( $attachments as $attachment ) {
  $id   = $attachment->ID;
  $file = get_attached_file( $id );

  // تولید متادیتا
  $meta = wp_generate_attachment_metadata( $id, $file );

  if ( ! is_wp_error( $meta ) && is_array( $meta ) ) {
    wp_update_attachment_metadata( $id, $meta );
  }
}

این اسکریپت برای زمانی مفید است که size جدیدی اضافه کرده‌اید و می‌خواهید همه تصاویر اندازه‌های جدید را داشته باشند. احتیاط: اجرا روی سایت‌های بزرگ می‌تواند مصرف حافظه و زمان زیادی داشته باشد؛ بهتر است آن را در خط فرمان (WP-CLI) یا به صورت پردازش دسته‌ای اجرا کنید.

هوک‌ها و فیلترها

• فیلتر wp_generate_attachment_metadata امکان دستکاری آرایه metadata قبل از ذخیره را می‌دهد: add_filter(‘wp_generate_attachment_metadata’, ‘my_modify_meta’, 10, 2);
• در داخل تولید اندازه‌ها از فیلتر‌های مربوط به image editors و intermediate image sizes نیز استفاده می‌شود.

add_filter( 'wp_generate_attachment_metadata', 'my_add_webp_sizes', 10, 2 );
function my_add_webp_sizes( $metadata, $attachment_id ) {
    if ( empty( $metadata['sizes'] ) ) {
        return $metadata;
    }

    foreach ( $metadata['sizes'] as $size_name => $size_data ) {
        $orig_file = dirname( get_attached_file( $attachment_id ) ) . '/' . $size_data['file'];
        $webp_file = preg_replace( '/.(jpe?g|png)$/i', '.webp', $orig_file );

        // تبدیل ساده با imagick (نمونه)
        if ( class_exists( 'Imagick' ) ) {
            $img = new Imagick( $orig_file );
            $img->setImageFormat( 'webp' );
            $img->writeImage( $webp_file );
            $metadata['sizes'][ $size_name ]['file_webp'] = basename( $webp_file );
        }
    }

    return $metadata;
}

توضیح: این فیلتر پس از تولید متادیتا اجرا می‌شود و برای هر سایز تلاش می‌کند نسخهٔ webp بسازد و نام فایل webp را در متادیتا اضافه کند. توجه کنید که در عمل باید بررسی‌های بیشتری (وجود Imagick، مجوز فایل و حجم) انجام شود.

نکات مهم و عیب‌یابی

• پیش‌نیازها: وجود GD یا Imagick روی سرور برای پردازش تصاویر.
• خطاهای حافظه: پردازش تصاویر بزرگ می‌تواند باعث خطای memory exhausted شود؛ در صورت نیاز از wp_image_editor_using_mime() یا افزایش memory_limit استفاده کنید.
• مجوز فایل‌ها: get_attached_file باید مسیر قابل‌خواندن برگرداند و پوشه uploads باید قابل نوشتن باشد.
• فایل غیرتصویری: برای pdf و فایل‌های صوتی/ویدئویی متادیتا محدود است؛ برای تولید کاور pdf نیاز به پشتیبانی imagick دارید.
• ردیابی خطا: از is_wp_error() و بررسی لاگ خطا استفاده کنید.

بهینه‌سازی و نکات حرفه‌ای

• برای سایت‌های بزرگ، عملیات بازتولید را با WP-CLI انجام دهید تا از زمان اجرا و حافظهٔ مرورگر مستقل باشد.
• اگر نیاز ندارید همه اندازه‌ها تولید شوند، می‌توانید با فیلتر intermediate_image_sizes_advanced سایزها را موقتا حذف کنید تا فقط سایزهای موردنظر ساخته شوند.
• برای اضافه کردن فرمت‌های جدید (مثل webp یا avif) از فیلتر wp_generate_attachment_metadata برای افزودن مسیرهای جدید و از image editor مناسب برای تبدیل استفاده کنید.

خلاصه

تابع wp_generate_attachment_metadata() ابزاری کلیدی برای تولید و بازتولید اطلاعات پیوست‌ها در وردپرس است. استفادهٔ صحیح از آن همراه با wp_update_attachment_metadata و فیلترهای مناسب، کنترل کامل روی اندازه‌ها و فرمت‌های خروجی تصاویر را به توسعه‌دهنده می‌دهد. هنگام اجرای دسته‌ای یا روی تصاویر بزرگ به منابع سرور و خطاهای احتمالی توجه کنید و از ابزارهایی مانند WP-CLI استفاده کنید تا فرایند پایاتر و سریع‌تر انجام شود.

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

ارسال