توابع پرکاربرد WordPress کدامند و چگونه از آن‌ها استفاده کنیم؟

حدود هفت سال پیش در پروژه‌ای که قرار بود یک سایت محتوایی سنگین را از صفر بسازم، در همان هفته اول با یک اشتباه روبه‌رو شدم که شش ماه بعد به یک بحران تبدیل شد: به‌جای استفاده از تابع `wp_query` و حلقه استاندارد وردپرس، یک کوئری مستقیم MySQL نوشتم و نتایج را با `foreach` نمایش دادم. سایت شش ماه بدون هیچ مشکلی کار کرد اما روزی که افزونه سئو نسخه جدیدش را منتشر کرد و ساختار متادیتای نوشته‌ها تغییر کرد، همه آن کوئری‌های مستقیم شکستند. آن تجربه، مرا وادار کرد که به توابع وردپرس نه به‌عنوان ابزارهای کاربردی، بلکه به‌عنوان لایه انتزاعی محافظت‌کننده نگاه کنم. امروز می‌خواهم به این پرسش پاسخ بدهم: توابع پرکاربرد وردپرس کدامند و چگونه از آن‌ها استفاده کنیم؟ پیش از ورود به معرفی توابع، اگر با مفهوم پایه‌ای هوک‌ها آشنا نیستید، مطالعه هوک‌های وردپرس چیستند و چگونه کار می‌کنند مبنا را روشن می‌کند چون بیشتر توابع وردپرس از طریق هوک‌ها اجرا می‌شوند.

چرا استفاده از توابع وردپرس حیاتی است؟

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

در سطح فنی، سه دلیل اصلی برای استفاده از توابع وردپرس وجود دارد. دلیل اول، پایداری در برابر آپدیت است چون هسته وردپرس تضمین می‌کند که توابع عمومی در نسخه‌های آینده پشتیبانی می‌شوند، در حالی که ساختار جداول می‌تواند تغییر کند. دلیل دوم، سازگاری با اکوسیستم است چون افزونه‌ها، قالب‌ها و ابزارهای خارجی به توابع استاندارد وردپرس وصل می‌شوند و اگر شما از این توابع استفاده کنید، در اکوسیستم قابل استفاده می‌مانید. دلیل سوم، امنیت است چون توابعی مثل `esc_html` و `sanitize_text_field` امنیت را به‌طور پیش‌فرض تأمین می‌کنند و شما را از پیاده‌سازی دستی نجات می‌دهند.

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

توابع وردپرس، بیمه‌نامه‌ای برای کد شما هستند؛ شما امروز کد می‌نویسید اما فردا کسی می‌خواهد آن را آپدیت کند. توابع وردپرس، پل بین امروز و فردای کد شماست.

نکته دومی که در اهمیت توابع وردپرس باید در نظر گرفت، تفاوت آن با زبان PHP خام است. در PHP خام، شما می‌توانید هر کاری بکنید اما باید همه‌چیز را خودتان مدیریت کنید. در وردپرس، توابع پایه، بسیاری از این مدیریت را برای شما انجام می‌دهند: مدیریت چرخه، مدیریت اتصال، مدیریت داده و مدیریت خروجی. این تفاوت، در پروژه‌های بزرگ به تفاوت‌های محسوسی در زمان توسعه و نگهداری تبدیل می‌شود. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در PHP در وردپرس نوشته‌ام نقطه شروع خوبی است.

دسته‌بندی توابع وردپرس

توابع وردپرس در ده‌ها دسته مختلف تقسیم می‌شوند که هرکدام برای هدف مشخصی طراحی شده‌اند. برای درک بهتر، بهتر است این توابع را در چند دسته اصلی گروه‌بندی کنیم:

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

توابع حلقه و کوئری

توابع حلقه و کوئری، پرکاربردترین دسته توابع وردپرس هستند و تقریباً در هر قالب و افزونه‌ای استفاده می‌شوند. این توابع مسئول بازیابی و نمایش نوشته‌ها از پایگاه داده هستند. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در توابع وردپرس برای ساخت کوئری سفارشی نوشته‌ام نقطه شروع خوبی است.

حلقه استاندارد وردپرس

حلقه استاندارد وردپرس، مجموعه‌ای از توابع است که برای نمایش نوشته‌ها در صفحه استفاده می‌شود. الگوی استاندارد این حلقه به‌شرح زیر است:

if ( have_posts() ) {
  while ( have_posts() ) {
    the_post();
    the_title();
    the_content();
  }
}

سه تابع اصلی در این حلقه عبارتند از: `have_posts()` که بررسی می‌کند آیا نوشته بعدی وجود دارد، `the_post()` که اشاره‌گر را به نوشته بعدی حرکت می‌دهد و `the_title()`، `the_content()` و سایر توابع `the_*` که داده نوشته فعلی را نمایش می‌دهند.

تابع WP_Query

تابع `WP_Query` پرکاربردترین تابع کوئری سفارشی در وردپرس است که به شما اجازه می‌دهد نوشته‌ها را با فیلترهای دلخواه بازیابی کنید:

$args = array(
  'post_type' => 'post',
  'posts_per_page' => 5,
  'category_name' => 'news',
  'orderby' => 'date',
  'order' => 'DESC'
);
$query = new WP_Query( $args );

if ( $query->have_posts() ) {
  while ( $query->have_posts() ) {
    $query->the_post();
    the_title();
  }
  wp_reset_postdata();
}

نکته مهم درباره `WP_Query` این است که بعد از پایان حلقه، باید `wp_reset_postdata()` فراخوانی شود تا اشاره‌گر به کوئری اصلی بازگردد. فراموش‌کردن این تابع، به مشکلات پنهان در ادامه صفحه منجر می‌شود.

تابع get_posts

تابع `get_posts` یک جایگزین سبک برای `WP_Query` است که در سناریوهای ساده‌تر استفاده می‌شود و به‌طور مستقیم یک آرایه از اشیاء نوشته برمی‌گرداند:

$posts = get_posts( array(
  'post_type' => 'book',
  'numberposts' => 10
) );

foreach ( $posts as $post ) {
  echo esc_html( $post->post_title );
}

توابع دسترسی به نوشته

توابع دسترسی به نوشته، برای خواندن داده‌های نوشته فعلی یا یک نوشته خاص استفاده می‌شوند. این توابع به دو دسته تقسیم می‌شوند: توابع `the_*` که داده را مستقیماً نمایش می‌دهند و توابع `get_the_*` که داده را برمی‌گردانند. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در توابع وردپرس برای دریافت اطلاعات نوشته نوشته‌ام نقطه شروع خوبی است.

تجربه‌ای که در پروژه‌های واقعی به آن رسیده‌ام این است: در قالب‌هایی که برای وبلاگ‌های حرفه‌ای استفاده می‌کنم، همیشه از توابع `get_the_*` برای پردازش داده قبل از نمایش استفاده می‌کنم. برای مثال، وقتی نیاز دارم عنوان نوشته را قبل از نمایش، بر اساس طول آن کوتاه کنم، از `get_the_title()` استفاده می‌کنم و سپس با `wp_trim_words` کوتاه می‌کنم. این رویکرد، انعطاف بسیار بیشتری نسبت به `the_title()` که داده را مستقیم چاپ می‌کند، می‌دهد.

نمونه کد ترکیبی

// نمایش کوتاه‌شده عنوان با تابع get_the_title
$title = get_the_title();
$short_title = wp_trim_words( $title, 10, '...' );
echo '<h2>' . esc_html( $short_title ) . '</h2>';

// نمایش آدرس نوشته با تابع get_permalink
$url = get_permalink();
echo '<a href="' . esc_url( $url ) . '">ادامه مطلب</a>';

توابع متادیتا

توابع متادیتا، پرکاربردترین توابع در پروژه‌های سفارشی هستند و به شما اجازه می‌دهند داده‌های اضافی را به نوشته، کاربر، دسته‌بندی یا هر موجودیت دیگری متصل کنید. وردپرس چهار نوع متادیتا دارد: post meta، user meta، term meta و option. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در توابع وردپرس برای مدیریت متادیتا نوشته‌ام نقطه شروع خوبی است.

توابع Post Meta

// خواندن متا
$value = get_post_meta( $post_id, 'my_key', true );

// ذخیره متا
update_post_meta( $post_id, 'my_key', $value );

// حذف متا
delete_post_meta( $post_id, 'my_key' );

نکته مهم درباره `get_post_meta` این است که پارامتر سوم (به‌عنوان مقدار `true` یا `false`) تعیین می‌کند که آیا مقدار منفرد برگردد یا آرایه. اگر مقدار `true` باشد، فقط یک مقدار برمی‌گردد؛ اگر `false` باشد، آرایه‌ای از مقادیر برمی‌گردد. در اکثر سناریوها، `true` انتخاب بهتری است چون سریع‌تر و سبک‌تر است.

توابع Option

// خواندن تنظیمات
$option = get_option( 'my_plugin_settings' );

// ذخیره تنظیمات
update_option( 'my_plugin_settings', $data );

// حذف تنظیمات
delete_option( 'my_plugin_settings' );

توابع Option، تنظیمات عمومی سایت را ذخیره می‌کنند و در جدول `wp_options` قرار می‌گیرند. نکته مهم این است که تمام گزینه‌ها در هر بار لود شدن وردپرس بارگذاری می‌شوند، بنابراین باید تعداد گزینه‌ها را کم نگه دارید. اگر نیاز به ذخیره داده‌های حجمی دارید، استفاده از `transient` یا `post meta` انتخاب بهتری است.

توابع User Meta

// ذخیره متا کاربر
update_user_meta( $user_id, 'phone_number', '09120000000' );

// خواندن متا کاربر
$phone = get_user_meta( $user_id, 'phone_number', true );

توابع کاربر

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

توابع بررسی کاربر

// بررسی لاگین
if ( is_user_logged_in() ) {
  // کاربر لاگین کرده
}

// دریافت کاربر فعلی
$current_user = wp_get_current_user();
echo 'خوش آمدید ' . esc_html( $current_user->display_name );

// بررسی دسترسی
if ( current_user_can( 'edit_posts' ) ) {
  // کاربر مجاز است
}

تابع `current_user_can` یکی از مهم‌ترین توابع امنیتی وردپرس است که در پروژه‌های واقعی، استفاده از آن در تمام نقاط حساس کد الزامی است. برای مثال، قبل از اجازه حذف یک نوشته، باید بررسی شود که آیا کاربر فعلی مجوز حذف را دارد یا خیر.

توابع بازیابی و ذخیره کاربر

// بازیابی کاربر با ID
$user = get_user_by( 'id', 5 );

// بازیابی کاربر با ایمیل
$user = get_user_by( 'email', 'user@example.com' );

// ایجاد کاربر جدید
$user_id = wp_create_user( 'username', 'password', 'email@example.com' );

// به‌روزرسانی کاربر
wp_update_user( array(
  'ID' => $user_id,
  'display_name' => 'New Name'
) );

توابع URL و لینک

توابع URL و لینک، برای ساخت و مدیریت آدرس‌های مختلف در وردپرس استفاده می‌شوند. این توابع به‌جای هارد‌کدکردن آدرس‌ها، به شما اجازه می‌دهند که در هر پروژه و هر دامنه‌ای، سایت شما به‌طور صحیح کار کند. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در توابع وردپرس برای ساخت لینک و URL نوشته‌ام نقطه شروع خوبی است.

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

توابع فایل و رسانه

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

// مسیر پوشه آپلود
$upload_dir = wp_upload_dir();
echo $upload_dir['basedir']; // مسیر فیزیکی
echo $upload_dir['baseurl']; // آدرس URL

// آدرس فایل ضمیمه
$image_url = wp_get_attachment_url( $attachment_id );

// آدرس تصویر با سایز خاص
$image = wp_get_attachment_image_src( $attachment_id, 'medium' );
echo '<img src="' . esc_url( $image[0] ) . '">';

// آدرس تصویر با آرایه کامل اتریبیوت‌ها
echo wp_get_attachment_image( $attachment_id, 'medium' );

تجربه‌ای که در پروژه‌های واقعی داشته‌ام این است: استفاده از `wp_get_attachment_image` به‌جای ساخت دستی تگ `img` توصیه می‌شود چون این تابع به‌طور خودکار `srcset`، `sizes` و سایر اتریبیوت‌های مهم را تولید می‌کند. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در سئوی تصویر چیست نوشته‌ام نقطه شروع خوبی است.

توابع بارگذاری استایل و اسکریپت

توابع بارگذاری استایل و اسکریپت، مکانیزم رسمی وردپرس برای اضافه‌کردن CSS و JavaScript به فرانت‌اند و پنل مدیریت هستند. این توابع، مدیریت وابستگی‌ها، نسخه‌بندی و ترتیب بارگذاری را خودکار انجام می‌دهند. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در توابع وردپرس برای کار با فایل‌ها نوشته‌ام نقطه شروع خوبی است.

add_action( 'wp_enqueue_scripts', function() {
  // بارگذاری استایل
  wp_enqueue_style(
    'my-style',
    get_stylesheet_directory_uri() . '/assets/css/style.css',
    array( 'dashicons' ),
    '1.0.0'
  );

  // بارگذاری اسکریپت
  wp_enqueue_script(
    'my-script',
    get_stylesheet_directory_uri() . '/assets/js/script.js',
    array( 'jquery' ),
    '1.0.0',
    true
  );

  // انتقال داده از PHP به JS
  wp_localize_script( 'my-script', 'myData', array(
    'ajaxUrl' => admin_url( 'admin-ajax.php' ),
    'nonce' => wp_create_nonce( 'my_nonce' )
  ) );
} );

نکته مهم در بارگذاری اسکریپت، پارامتر پنجم (مقدار `true` یا `false`) است که تعیین می‌کند اسکریپت در `` بارگذاری شود یا در انتهای ``. برای بهبود سرعت لود، توصیه می‌شود اسکریپت‌ها در انتهای صفحه بارگذاری شوند.

توابع امنیتی

توابع امنیتی، ستون فقرات امنیت کد وردپرس هستند و در پروژه‌های واقعی، استفاده از آن‌ها اجباری است. این توابع در سه دسته اصلی تقسیم می‌شوند: پاک‌سازی خروجی، اعتبارسنجی ورودی و مدیریت nonce. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در توابع وردپرس برای امنیت و پاک‌سازی داده‌ها نوشته‌ام نقطه شروع خوبی است.

// نمونه استفاده ترکیبی
if ( isset( $_POST['my_data'] ) ) {
  // بررسی nonce
  if ( ! wp_verify_nonce( $_POST['my_nonce'], 'my_action' ) ) {
    wp_die( 'درخواست غیرمعتبر' );
  }

  // پاک‌سازی ورودی
  $data = sanitize_text_field( $_POST['my_data'] );

  // ذخیره در پایگاه داده
  update_option( 'my_data', $data );
}

// پاک‌سازی خروجی
$saved_data = get_option( 'my_data' );
echo '<div>' . esc_html( $saved_data ) . '</div>';

در امنیت کد وردپرس، هیچ داده ورودی را بدون پاک‌سازی نپذیرید و هیچ داده خروجی را بدون پاک‌سازی نمایش ندهید. سه تابع `esc_html`، `esc_attr` و `esc_url` همان سه ابزار ضروری هستند که همیشه باید در جعبه‌ابزار شما باشند.

توابع شرطی

توابع شرطی یا Conditional Tags، توابعی هستند که وضعیت فعلی صفحه را بررسی می‌کنند و مقدار `true` یا `false` برمی‌گردانند. این توابع در پروژه‌های واقعی برای اعمال رفتار متفاوت در صفحات مختلف استفاده می‌شوند. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در توابع وردپرس برای دریافت تنظیمات قالب نوشته‌ام نقطه شروع خوبی است.

if ( is_single() ) {
  // کد فقط در صفحه نوشته تکی اجرا شود
}

if ( is_front_page() && is_user_logged_in() ) {
  // کد فقط در صفحه فرود برای کاربران لاگین‌کرده
}

توابع ترجمه

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

// ترجمه ساده
echo esc_html__( 'خوش آمدید', 'my-theme' );

// ترجمه با جمع و مفرد
printf(
  esc_html( _n( '%s نظر', '%s نظر', $count, 'my-theme' ) ),
  number_format_i18n( $count )
);

توابع ووکامرس

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

// بازیابی محصول
$product = wc_get_product( $product_id );
echo esc_html( $product->get_name() );
echo wp_kses_post( $product->get_price_html() );

// دسترسی به سبد خرید
$cart = WC()->cart;
$total = $cart->get_cart_total();
echo wp_kses_post( $total );

توابع پیشرفته و REST API

توابع پیشرفته و REST API، برای پروژه‌های سازمانی و اپلیکیشن‌های مدرن کاربرد دارند. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در API در وردپرس نوشته‌ام نقطه شروع خوبی است.

// ثبت endpoint سفارشی
add_action( 'rest_api_init', function() {
  register_rest_route( 'my-plugin/v1', '/items', array(
    'methods' => 'GET',
    'callback' => function( $request ) {
      return new WP_REST_Response( array(
        'items' => get_posts( array( 'numberposts' => 10 ) )
      ), 200 );
    },
    'permission_callback' => function() {
      return current_user_can( 'read' );
    }
  ) );
} );

در پروژه‌های مدرن، REST API وردپرس ابزار اصلی برای ارتباط با اپلیکیشن‌های موبایل، فرانت‌اندهای مدرن و سرویس‌های خارجی است. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در ساخت API اختصاصی برای وردپرس نوشته‌ام نقطه شروع خوبی است.

اشتباهات رایج در استفاده از توابع

اشتباهات رایج در استفاده از توابع وردپرس، یکی از مسائلی است که در پروژه‌های واقعی بارها دیده‌ام و بسیاری از آن‌ها به باگ‌های سخت و بی‌سروصدا منجر می‌شود. در ادامه، به هشت اشتباه رایج اشاره می‌کنم.

• استفاده از `the_*` به‌جای `get_the_*`: توابع `the_*` داده را مستقیم چاپ می‌کنند و امکان پردازش را از شما می‌گیرند. اگر نیاز به پردازش دارید، از `get_the_*` استفاده کنید.
• فراموش کردن `wp_reset_postdata`: بعد از استفاده از `WP_Query` سفارشی، حتماً باید این تابع را فراخوانی کنید تا اشاره‌گر به کوئری اصلی بازگردد.
• هارد‌کدکردن URL سایت: به‌جای `https://example.com/wp-content`، از `content_url()` استفاده کنید تا در هر دامنه‌ای کار کند.
• استفاده مستقیم از `$_GET` و `$_POST`: همیشه داده ورودی را با `sanitize_text_field` یا مشابه آن پاک‌سازی کنید.
• نمایش بدون پاک‌سازی: هر داده‌ای که از دیتابیس می‌خوانید، قبل از نمایش باید با `esc_html`، `esc_attr` یا `esc_url` پاک‌سازی شود.
• نادیده‌گرفتن `current_user_can`: قبل از هر عملیات حساس، مجوز کاربر را بررسی کنید.
• استفاده از توابع منسوخ‌شده: توابعی مثل `get_currentuserinfo` منسوخ شده‌اند و در نسخه‌های جدید وردپرس کار نمی‌کنند. همیشه مستندات رسمی را بررسی کنید.
• عدم استفاده از `wp_enqueue_*`: بارگذاری مستقیم CSS و JS با تگ `link` و `script`، باعث می‌شود که وردپرس نتواند مدیریت وابستگی‌ها را انجام دهد.

اگر می‌خواهید درک عمیق‌تری از این اشتباهات داشته باشید، مقاله‌ای که در اشتباهات رایج در کدنویسی وردپرس نوشته‌ام به‌طور کامل این موضوع را باز می‌کند.

در استفاده از توابع وردپرس، قاعده ساده‌ای وجود دارد: هر داده‌ای که از دیتابیس یا کاربر می‌آید، باید پاک‌سازی شود؛ هر داده‌ای که به کاربر می‌رود، باید پاک‌سازی شود؛ و هر عملیات حساس، باید بررسی مجوز داشته باشد. این سه قاعده، ۹۰ درصد باگ‌های امنیتی را حذف می‌کند.

پرسش‌های پرتکرار درباره توابع وردپرس

این بخش را به سؤالاتی اختصاص داده‌ام که بیشتر در جلسه‌های مشاوره تکرار می‌شوند و پاسخ‌شان در تصمیم نهایی وزن زیادی دارد.

تفاوت `the_title()` و `get_the_title()` چیست؟

تابع `the_title()` عنوان نوشته را مستقیماً چاپ می‌کند و مقدار برنمی‌گرداند، در حالی که `get_the_title()` عنوان را به‌عنوان مقدار برمی‌گرداند. اگر نیاز دارید که عنوان را قبل از نمایش پردازش کنید (مثلاً کوتاه کنید یا فرمت دهید)، از `get_the_title()` استفاده کنید. اگر فقط می‌خواهید عنوان را چاپ کنید، `the_title()` کافی است.

چگونه از `WP_Query` برای فیلتر کردن نوشته‌ها استفاده کنم؟

تابع `WP_Query` آرگومان‌های متنوعی برای فیلترکردن می‌پذیرد: `post_type`، `posts_per_page`، `category_name`، `tag`، `author`، `orderby`، `order`، `meta_query`، `date_query` و چندین آرگومان دیگر. برای مثال، برای نمایش پنج نوشته از دسته خبری: `new WP_Query( array( 'category_name' => 'news', 'posts_per_page' => 5 ) )`. بعد از پایان حلقه، حتماً `wp_reset_postdata()` را فراخوانی کنید.

چرا باید از `wp_enqueue_style` و `wp_enqueue_script` استفاده کنم؟

این دو تابع، مکانیزم رسمی وردپرس برای بارگذاری CSS و JS هستند و سه مزیت دارند: مدیریت خودکار وابستگی‌ها (مثلاً اگر jQuery لازم دارید، وردپرس خودش آن را بارگذاری می‌کند)، جلوگیری از بارگذاری تکراری (اگر چند افزونه یک اسکریپت را بارگذاری کنند، فقط یک بار بارگذاری می‌شود) و امکان کش کردن مناسب. بارگذاری مستقیم CSS و JS با تگ، این سه مزیت را از بین می‌برد.

تفاوت `update_option` و `update_post_meta` چیست؟

تابع `update_option` برای ذخیره تنظیمات عمومی سایت استفاده می‌شود و در جدول `wp_options` ذخیره می‌شود. تابع `update_post_meta` برای ذخیره داده متای یک نوشته خاص استفاده می‌شود و در جدول `wp_postmeta` ذخیره می‌شود. قاعده سرانگشتی این است: اگر داده به کل سایت مربوط است، از `update_option` استفاده کنید؛ اگر داده به یک نوشته، کاربر یا موجودیت خاص مربوط است، از `update_post_meta` یا مشابه آن استفاده کنید.

چگونه از `get_user_meta` استفاده کنم؟

تابع `get_user_meta` داده متای کاربر را برمی‌گرداند و سه پارامتر می‌پذیرد: شناسه کاربر، نام کلید و مقدار `single`. مثال: `get_user_meta( $user_id, 'phone', true )`. اگر پارامتر سوم `true` باشد، مقدار منفرد برمی‌گردد؛ اگر `false` باشد، آرایه‌ای از مقادیر برمی‌گردد. در اکثر سناریوها، `true` انتخاب بهتری است.

چرا در کد باید از `esc_html` و `esc_attr` استفاده کنم؟

این دو تابع از XSS (Cross-Site Scripting) جلوگیری می‌کنند. تابع `esc_html` کاراکترهای HTML خطرناک را کدگذاری می‌کند و برای نمایش متن در محتوای HTML استفاده می‌شود. تابع `esc_attr` برای نمایش مقادیر در اتریبیوت‌های HTML استفاده می‌شود. اگر این توابع را استفاده نکنید، مهاجم می‌تواند با درج کد HTML یا JS در ورودی، سایت شما را هک کند.

آیا `wp_query` روی سرعت سایت اثر دارد؟

تابع `WP_Query` به‌طور مستقیم روی سرعت سایت اثر دارد چون کوئری دیتابیس اجرا می‌کند. اگر تعداد کوئری‌های `WP_Query` زیاد باشد یا از آرگومان‌های سنگین (مثل `meta_query` پیچیده) استفاده شود، می‌تواند سرعت سایت را کم کند. توصیه من این است که کوئری‌های خود را با افزونه Query Monitor بررسی کنید و در صورت نیاز، از کش یا transient برای ذخیره نتایج استفاده کنید.

تفاوت `is_single` و `is_singular` چیست؟

تابع `is_single` فقط برای نوشته‌های تکی از نوع `post` کار می‌کند. تابع `is_singular` برای هر نوع نوشته تکی (شامل post، page و هر نوع نوشته سفارشی) کار می‌کند. اگر می‌خواهید کد شما برای همه انواع نوشته‌های تکی اجرا شود، از `is_singular` استفاده کنید. اگر فقط برای نوشته‌های معمولی blog، از `is_single`.

چگونه از `get_template_directory_uri` استفاده کنم؟

تابع `get_template_directory_uri` آدرس URL پوشه قالب والد را برمی‌گرداند. برای قالب فرزند، از `get_stylesheet_directory_uri` استفاده کنید. برای بارگذاری فایل‌های قالب (CSS، JS، تصاویر)، از ترکیب این توابع با نام فایل استفاده کنید: `get_template_directory_uri() . '/assets/css/style.css'`. این رویکرد، سایت شما را در هر دامنه‌ای سازگار می‌کند.

آیا می‌توانم توابع وردپرس را قبل از بارگذاری کامل هسته فراخوانی کنم؟

خیر، توابع وردپرس تنها پس از بارگذاری هسته قابل فراخوانی هستند. اگر نیاز به اجرای کد قبل از بارگذاری کامل هسته دارید، باید از هوک‌های اولیه مثل `muplugins_loaded` یا `plugins_loaded` استفاده کنید. اما حتی در این هوک‌ها هم بعضی توابع در دسترس نیستند. برای بیشتر توابع، هوک `init` نقطه شروع امن است.

آیا `current_user_can` جایگزین `is_user_logged_in` است؟

خیر، این دو تابع برای هدف متفاوتی طراحی شده‌اند. تابع `is_user_logged_in` بررسی می‌کند که آیا کاربر لاگین کرده یا نه. تابع `current_user_can` بررسی می‌کند که آیا کاربر فعلی مجوز مشخصی (مثلاً `edit_posts`) را دارد. در سناریوهای امنیتی، استفاده از `current_user_can` به‌جای `is_user_logged_in` توصیه می‌شود چون مجوز دقیق را بررسی می‌کند.

چگونه از `wp_remote_get` و `wp_remote_post` برای درخواست HTTP استفاده کنم؟

تابع `wp_remote_get` برای درخواست GET و `wp_remote_post` برای درخواست POST استفاده می‌شود. مثال: `$response = wp_remote_get( 'https://api.example.com/data' );` و سپس برای دسترسی به داده: `$body = wp_remote_retrieve_body( $response );`. این توابع از cURL در پس‌زمینه استفاده می‌کنند و مکانیزم استاندارد وردپرس برای ارتباط با سرویس‌های خارجی هستند. اگر می‌خواهید درک عمیق‌تری از این لایه داشته باشید، مقاله‌ای که در توابع وردپرس برای ارسال درخواست HTTP نوشته‌ام نقطه شروع خوبی است.

چک‌لیست عملی و سخن پایانی

اگر این راهنما را با یک جمله خلاصه کنم، توابع وردپرس لایه انتزاعی محافظت‌کننده‌ای هستند که کد شما را از پیاده‌سازی مستقیم و شکننده دور نگه می‌دارند و در بلندمدت، پایداری، امنیت و سازگاری سایت شما را تضمین می‌کنند. در این راهنما، توابع پرکاربرد وردپرس را در ده دسته اصلی (حلقه و کوئری، دسترسی به نوشته، متادیتا، کاربر، URL، فایل، بارگذاری استایل، امنیت، شرطی و ترجمه) به‌همراه نمونه کد عملی بررسی کردیم و لایه‌های پیشرفته‌تری مثل REST API و توابع ووکامرس را نیز پوشش دادیم.

برای استفاده عملی از این راهنما، چک‌لیست زیر را در پروژه‌های خود اجرا کنید:

• قبل از هر کوئری دیتابیس، بررسی کنید که آیا تابع وردپرس مناسب وجود دارد یا خیر.
• در حلقه‌ها، بعد از `WP_Query` سفارشی، حتماً `wp_reset_postdata()` را فراخوانی کنید.
• هرگز آدرس سایت را هارد‌کد نکنید؛ از توابع URL وردپرس استفاده کنید.
• در نمایش هر داده، از `esc_html`، `esc_attr` یا `esc_url` استفاده کنید.
• در پردازش هر ورودی، از `sanitize_text_field` یا مشابه آن استفاده کنید.
• در تمام نقاط حساس، از `current_user_can` و nonce استفاده کنید.
• برای بارگذاری CSS و JS، از `wp_enqueue_style` و `wp_enqueue_script` استفاده کنید.
• در کدهای قابل ترجمه، از توابع `__`، `_e` و `esc_html__` استفاده کنید.
• در پروژه‌های فروشگاهی، از توابع ووکامرس (`wc_get_product` و مشابه) استفاده کنید.
• در پروژه‌های مدرن، REST API وردپرس را در نظر بگیرید.

تجربه‌ای که در پروژه‌های واقعی به آن رسیده‌ام این است: تیم‌هایی که این چک‌لیست را در فرآیند توسعه خود ادغام می‌کنند، در بلندمدت کد پایدارتری دارند که در مواجهه با تغییرات وردپرس و افزونه‌ها نیازی به بازنویسی ندارد. اگر تجربه‌ای از کار با توابع وردپرس در پروژه‌های واقعی دارید — چه موفق، چه ناامیدکننده — برایم جالب است که در دیدگاه‌ها بنویسید کدام تابع بیشترین اثر را روی پروژه شما داشته و کدام اشتباه در استفاده از آن‌ها بیشترین زمان را از شما گرفته است. تجربه‌های واقعی شما، این راهنما را برای خواننده بعدی دقیق‌تر و کاربردی‌تر خواهد کرد. ⚙️