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

تابع wp_parse_args() یکی از توابع ساده اما بسیار کاربردی در هستهٔ وردپرس است که برای ترکیب کردن پارامترهای ورودی با آرایهٔ پیش‌فرض استفاده می‌شود. این تابع مخصوصاً در مواقعی که تابع یا شورتکدی نیاز به پارامتر‌های دلخواه دارد و می‌خواهید مطمئن باشید همهٔ کلیدهای ضروری مقدار داشته باشند، مفید است.

وقتی از wp_parse_args استفاده می‌کنیم

• پارامترهای کاربر یا شورتکد را با مقادیر پیش‌فرض ترکیب کنیم.
• پارامترها می‌توانند به صورت رشتهٔ query (مثلاً “foo=bar&baz=1”)، آرایه یا شیء باشند.
• می‌خواهیم نگارش کوتاه و امن برای مقداردهی اولیهٔ آرایه‌ها داشته باشیم.

نحو پایه و رفتار تابع

wp_parse_args( $args, $defaults = '' );

این تابع اگر $args یک شیء باشد آن را به آرایه تبدیل می‌کند، اگر آرایه باشد از همان استفاده می‌شود و اگر رشته باشد با استفاده از wp_parse_str پارس می‌شود. سپس مقادیر دریافت‌شده روی آرایهٔ پیش‌فرض اعمال می‌شوند تا مقادیر ورودی جایگزین پیش‌فرض‌ها شوند.

مثال ساده

$defaults = array(
  'title' => 'بدون عنوان',
  'count' => 5,
  'show_date' => true,
);

$args = array(
  'count' => 10,
  'show_date' => false,
);

$parsed = wp_parse_args( $args, $defaults );
// $parsed => array('title'=>'بدون عنوان','count'=>10,'show_date'=>false);

در این مثال، آرایهٔ $args روی $defaults اعمال شده و کلیدهای موجود در $args مقدار پیش‌فرض را بازنویسی می‌کنند. بقیهٔ مقادیر پیش‌فرض حفظ می‌شوند.

پشتیبانی از رشته و شیء

// ورودی به صورت رشته
$args_str = 'count=3&title=لیست';
$parsed_str = wp_parse_args( $args_str, $defaults );

// ورودی به صورت شیء
$args_obj = (object) array( 'title' => 'عنوان شی', 'show_date' => false );
$parsed_obj = wp_parse_args( $args_obj, $defaults );

تابع رشتهٔ ورودی را با wp_parse_str به آرایه تبدیل می‌کند و شیء را با get_object_vars به آرایهٔ معادل تبدیل می‌کند. بنابراین قابلیت انعطاف زیادی در ورودی می‌دهد.

مقایسه با array_merge و shortcode_atts

محدودیت‌ها و حالت‌های لانه‌ای (nested arrays)

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

$defaults = array(
  'layout' => array(
    'cols' => 3,
    'gutter' => 10,
  ),
);

$args = array(
  'layout' => array(
    'cols' => 2
  )
);

$parsed = wp_parse_args( $args, $defaults );
// نتیجه: 'layout' => array('cols'=>2)  => گاتر حذف شده!

در مثال بالا، کل کلید layout توسط آرایهٔ ورودی جایگزین شد و کلید gutter از بین رفت. اگر نیاز به ادغام بازگشتی دارید باید از تابع دلخواه یا توابع PHP مانند array_replace_recursive یا نوشتن تابع merge بازگشتی استفاده کنید.

نمونهٔ تابع merge بازگشتی بهبود یافته

function my_wp_parse_args_recursive( $args, $defaults = array() ) {
  if ( is_object( $args ) ) {
    $args = get_object_vars( $args );
  } elseif ( is_string( $args ) ) {
    wp_parse_str( $args, $args );
  }

  $result = $defaults;
  foreach ( (array) $args as $key => $value ) {
    if ( is_array( $value ) && isset( $result[ $key ] ) && is_array( $result[ $key ] ) ) {
      $result[ $key ] = my_wp_parse_args_recursive( $value, $result[ $key ] );
    } else {
      $result[ $key ] = $value;
    }
  }
  return $result;
}

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

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

• همیشه پس از wp_parse_args مقادیر را sanitize کنید: برای رشته‌ها از sanitize_text_field() یا esc_attr() و برای اعداد از absint() یا intval() استفاده کنید.
• برای شورتکدها shortcode_atts() معمولاً گزینهٔ مناسب‌تری است، چون امکان فیلترگذاری وردپرس را دارد.
• در صورت انتظار برای آرایه‌های تو در تو، از حل مشکل ادغام بازگشتی استفاده کنید.
• اگر ورودی می‌تواند از سمت کاربر بیاید، هیچ‌گاه بدون اعتبارسنجی و پاکسازی از مقادیر استفاده نکنید.

موارد واقعی استفاده

• توابع قالب که آرگومان‌هایی مثل تعداد نوشته‌ها، ترتیب، نمایش تصویر شاخص و … می‌گیرند.
• ویجت‌ها و تنظیمات افزونه‌ که باید ترکیب پارامترهای ذخیره‌شده با مقادیر پیش‌فرض انجام شود.
• شورتکدهای ساده (اگرچه برای شورتکدها معمولاً shortcode_atts توصیه می‌شود).

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

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

ارسال