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

تابع set_theme_mod() یکی از ابزارهای اصلی وردپرس برای ذخیره‌سازی تنظیمات مربوط به یک قالب (theme) است. این تابع بخشی از سیستم Theme Modification API است و به شما اجازه می‌دهد به‌صورت برنامه‌نویسی مقدار یک گزینهٔ قالب (theme mod) را ذخیره یا تغییر دهید. در این مقاله به صورت کامل، کاربردها، تفاوت‌ها با سایر روش‌ها، مثال‌های عملی و نکات امنیتی و بهینه‌سازی را توضیح می‌دهیم.

چه زمانی از set_theme_mod() استفاده کنیم؟

زمانی که می‌خواهید تنظیمات وابسته به قالب را ذخیره کنید (مثل رنگ‌ها، لوگو، چیدمان).
برای مقداردهی اولیه‌ی تنظیمات هنگام فعال‌سازی قالب.
برای تغییر برنامه‌ای یک تنظیم بدون دسترسی مستقیم به Customizer UI.

نحوهٔ کار و ساختار ذخیره‌سازی

تمام theme_modها در دیتابیس در یک رکورد گزینه به نام theme_mods_{stylesheet} ذخیره می‌شوند. به عبارت دیگر تمام تنظیمات قالب در یک آرایهٔ بزرگ تحت یک option قرار می‌گیرند که مزیت آن کاهش تعداد رکوردهاست، ولی باید جوانب کارایی را در نظر گرفت زیرا این option به‌صورت autoload ذخیره می‌شود.

مثال پایه: ذخیره و خواندن مقدار

/* set a theme mod value */set_theme_mod( 'header_bg_color', '#ff0000' );

/* get the value later */$color = get_theme_mod( 'header_bg_color', '#ffffff' );

در این مثال با set_theme_mod مقدار کلید header_bg_color ذخیره می‌شود. سپس با get_theme_mod آن را خوانده‌ایم و اگر مقداری وجود نداشت مقدار پیش‌فرض #ffffff بازگردانده می‌شود.

نمونه: مقداردهی اولیه هنگام فعال کردن قالب

function mytheme_set_default_theme_mods() {
    set_theme_mod( 'header_bg_color', '#1e73be' );
    set_theme_mod( 'show_author_box', true );
    set_theme_mod( 'footer_text', '© ' . date( 'Y' ) . ' MyTheme' );
}
add_action( 'after_switch_theme', 'mytheme_set_default_theme_mods' );

کد بالا هنگام فعال شدن قالب مقدار پیش‌فرض چند تنظیم را می‌گذارد. این روش مناسب است تا کاربران پس از فعال‌سازی یک قالب، مقدمات اولیه را ببینند.

استفاده در Customizer و هماهنگی با set_theme_mod()

در Customizer معمولاً کنترل‌ها با تابع $wp_customize->add_setting() تعریف می‌شوند که به صورت پیش‌فرض از Theme Mod API استفاده می‌کند. برای هماهنگی، هنگام افزودن تنظیمات در فایل functions.php از همان نام کلیدها استفاده کنید تا set_theme_mod و Customizer به یک مقدار اشاره کنند.

function mytheme_customize_register( $wp_customize ) {
    $wp_customize->add_setting( 'header_bg_color', array(
        'default'           => '#1e73be',
        'sanitize_callback' => 'sanitize_hex_color',
        'transport'         => 'postMessage',
    ) );

    $wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'header_bg_color_control', array(
        'label'    => 'Header Background Color',
        'section'  => 'colors',
        'settings' => 'header_bg_color',
    ) ) );
}
add_action( 'customize_register', 'mytheme_customize_register' );

در این کد یک تنظیم در Customizer اضافه شده و sanitize_callback نیز تعیین شده است. زمانی که کاربر رنگ را تغییر می‌دهد، همان کلید در theme_mods تغییر می‌کند و set_theme_mod می‌تواند مقدار را از طریق کد نیز تنظیم کند.

تفاوت set_theme_mod() و update_option()

ویژگی	set_theme_mod()	update_option()
مکان ذخیره	option: theme_mods_{stylesheet}	option: {option_name}
مربوط به قالب	بله	خیر (عمومی)
تغییر با تعویض قالب	هر قالب theme_mods خودش را دارد	همیشه یکسان است

نکات امنیتی و بهترین شیوه‌ها

همیشه قبل از ذخیره از sanitize_callback در Customizer یا توابع sanitize مناسب استفاده کنید (مثلاً sanitize_text_field، sanitize_hex_color، absint).
هنگام خروجی‌گیری در قالب حتماً از توابع escaping مانند esc_attr، esc_html یا esc_url استفاده کنید.
برای مقادیر بزرگ یا پیچیده (مثل آرایه‌های بزرگ) توجه کنید که همهٔ theme_modها در یک option ذخیره می‌شوند؛ اگر بار زیادی روی آن بیفتد ممکن است تاثیر روی لود داشته باشد.
اگر تنظیماتی لازم است بین قالب‌ها مشترک باشد، از update_option استفاده کنید؛ اما برای مقادیر وابسته به قالب، set_theme_mod مناسب‌تر است.

حذف یا بازنشانی یک theme mod

// delete a theme mod
remove_theme_mod( 'header_bg_color' );

// reset all theme mods for current theme
remove_theme_mods();

remove_theme_mod حذف یک کلید تعیین‌شده را انجام می‌دهد و remove_theme_mods کلیه تنظیمات مربوط به قالب فعال را پاک می‌کند. این توابع مفید هنگام ریست به مقدار پیش‌فرض یا هنگام توسعه هستند.

مثال پیشرفته: تولید CSS پویا با استفاده از get_theme_mod()

function mytheme_custom_dynamic_css() {
    $bg = get_theme_mod( 'header_bg_color', '#1e73be' );
    $custom_css = "
        .site-header {
            background-color: {$bg};
        }
    ";
    wp_add_inline_style( 'mytheme-style-handle', $custom_css );
}
add_action( 'wp_enqueue_scripts', 'mytheme_custom_dynamic_css' );

در این مثال مقدار رنگ هدر از theme_mod خوانده شده و CSS در زمان بارگذاری اضافه می‌شود. استفاده از wp_add_inline_style بهتر از چاپ مستقیم است، چون وابسته به enqueue است و ترتیب بارگذاری را حفظ می‌کند.

نکات پیشرفته و عملکرد

زیاد کردن تعداد theme_modهای بسیار بزرگ می‌تواند باعث افزایش اندازه option theme_mods و تاثیر روی autoload شود؛ به این مورد دقت کنید.
در وردپرس شبکه (Multisite)، theme_modها به ازای هر سایت جداگانه نگهداری می‌شوند.
می‌توانید از فیلترهای theme_mod_{name} برای تغییر مقدار پیش از نمایش استفاده کنید.

جمع‌بندی و توصیه‌ها

set_theme_mod() تابعی قدرتمند و مناسب برای ذخیره‌سازی تنظیمات وابسته به قالب در وردپرس است. استفادهٔ درست از آن در کنار Customizer، sanitize، و escaping باعث تجربهٔ کاربری بهتر و کدنویسی قابل اتکاتر می‌شود. همیشه پیش از ذخیره و خروجی‌گیری فکر کنید که آیا مقدار باید به قالب محدود باشد یا گزینه‌ای عمومی—و براساس آن بین set_theme_mod و update_option تصمیم بگیرید.

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

خیر

بله