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

تابع wp_timezone_string() یکی از ابزارهای کاربردی وردپرس برای به‌دست آوردن شناسهٔ ناحیهٔ زمانی (timezone identifier) سایت است. این تابع به شما کمک می‌کند تا زمان‌ها را به‌درستی مطابق تنظیمات سایت نمایش دهید یا برای پردازش‌های زمان‌بنیاد، شیٔ DateTime مناسبی بسازید. در ادامه رفتار، مثال‌های واقعی، نکات فنی و بهترین شیوه‌ها را بررسی می‌کنیم.

wp_timezone_string() چیست و چگونه کار می‌کند؟

این تابع تلاش می‌کند تا یک رشتهٔ معتبر مربوط به ناحیهٔ زمانی (مثل “Asia/Tehran” یا “Europe/London”) برگرداند. اگر در تنظیمات وردپرس (تنظیمات عمومی) کاربر یک timezone identifier انتخاب کرده باشد، همان رشته بازگردانده می‌شود. اما اگر سایت فقط از جابه‌جایی GMT (گزینهٔ gmt_offset) استفاده کند و شناسهٔ TZ ذخیره نشده باشد، تابع بر اساس آن آفست یک شناسهٔ مبتنی بر UTC می‌سازد (برای مثال “UTC+3:30”).

نکتهٔ مهم: اگر می‌خواهید با اشیاء DateTime کار کنید، بهتر است از wp_timezone() (که یک DateTimeZone بازمی‌گرداند) استفاده کنید؛ اما wp_timezone_string() برای نمایش ساده یا سازگاری با API هایی که رشتهٔ timezone می‌پذیرند مفید است.

نمونهٔ ساده — دریافت رشتهٔ ناحیهٔ زمانی

$tz_string = wp_timezone_string();
echo $tz_string; // e.g. "Asia/Tehran" or "UTC+3:30"

این کد رشتهٔ ناحیهٔ زمانی سایت را خوانده و نمایش می‌دهد. اگر شناسهٔ مستقیم تنظیم شده باشد همان نمایش داده می‌شود، وگرنه براساس gmt_offset یک رشتهٔ “UTC±HH:MM” ساخته می‌شود.

نمایش زمان فعلی سایت با استفاده از wp_date

// نمایش زمان فعلی سایت به فرمت Y-m-d H:i:s
$current = wp_date( 'Y-m-d H:i:s' );
echo $current;

wp_date از تنظیمات زمانی سایت استفاده و زمان را طبق منطقهٔ زمانی سایت بازمی‌گرداند. این روش نسبت به استفادهٔ مستقیم date() یا DateTime بدون تعیین صحیح زمان منطقه‌ای امن‌تر است.

استفادهٔ حرفه‌ای با DateTime و wp_timezone()

$tz = wp_timezone(); // برمی‌گرداند: DateTimeZone
$dt = new DateTimeImmutable( '2025-10-30 14:00', $tz );
echo $dt->format('Y-m-d H:i:s'); // زمان در ناحیهٔ زمانی سایت

// تبدیل به UTC برای ذخیره در دیتابیس
$utc = $dt->setTimezone( new DateTimeZone('UTC') );
echo $utc->format('Y-m-d H:i:s');

در این مثال ابتدا یک DateTimeImmutable با ناحیهٔ زمانی سایت می‌سازیم، سپس آن‌را به UTC تبدیل می‌کنیم تا مثلاً در دیتابیس با استاندارد جهانی ذخیره شود. استفاده از wp_timezone() باعث می‌شود از هرگونه ناسازگاری با تنظیمات سایت جلوگیری شود.

مثال کاربردی: زمان‌بندی رویداد (cron) با در نظر گرفتن timezone کاربر

وردپرس برای کرون داخلی (WP-Cron) معمولاً زمان‌ها را به شکل UTC یا timestamp مدیریت می‌کند. اگر لازم است زمان‌هایی که کاربر وارد می‌کند (مثلاً فرم تعیین زمان برای ارسال پست) به درستی به UTC تبدیل شوند، از wp_timezone() یا wp_timezone_string() استفاده کنید:

// فرض: کاربر زمان محلی را به صورت '2025-10-30 20:00' وارد کرده
$user_input = '2025-10-30 20:00';
$tz = wp_timezone();
$dt = new DateTime( $user_input, $tz );
$utc_dt = $dt->setTimezone( new DateTimeZone('UTC') );
$timestamp = $utc_dt->getTimestamp();

// از $timestamp برای ثبت رویداد کرون یا ذخیره در DB استفاده کنید

در این سناریو نشان دادیم چطور زمان وارد شده توسط کاربر (مطابق تنظیمات سایت) به UTC تبدیل شده و قابل استفاده در زمان‌بندی یا ذخیره‌سازی می‌شود.

جدول مقایسهٔ توابع مرتبط

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

• اگر امکان دارد همیشه شناسهٔ TZ (مثلاً “Asia/Tehran”) را در تنظیمات سایت انتخاب کنید؛ شناسه‌ها DST را هم لحاظ می‌کنند؛ اما افست ثابت (مانند +3.5) ممکن است در تغییرات تابستانی خطا ایجاد کند.
• برای نمایش تاریخ/زمان به کاربر، از wp_date استفاده کنید تا ترجمه‌ها و تنظیمات وردپرس رعایت شوند.
• برای پردازش‌های سروری یا ذخیره‌سازی بین‌المللی، زمان‌ها را به UTC تبدیل کنید تا یکپارچگی حفظ شود.
• از DateTimeImmutable برای جلوگیری از تغییر ناخواستهٔ اشیاء زمان استفاده کنید.
• اگر تابع wp_timezone_string مقدار غیرمنتظره‌ای بازگرداند، ابتدا get_option(‘timezone_string’) و get_option(‘gmt_offset’) را بررسی کنید تا منبع مشکل مشخص شود.

بهینه‌سازی و اصلاح کد

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

// ناصحیح: ممکن است زمان ناحیهٔ زمانی سایت را در نظر نگیرد
echo date('Y-m-d H:i:s');

// صحیح: مطابق تنظیمات وردپرس
echo wp_date('Y-m-d H:i:s');

در مثال بالا، استفاده از wp_date باعث می‌شود که خروجی همیشه مطابق با timezone تنظیم‌شده در وردپرس باشد، حتی اگر PHP سرور در یک منطقهٔ زمانی متفاوت تنظیم شده باشد.

جمع‌بندی

wp_timezone_string() ابزاری ساده اما مفید برای به‌دست آوردن رشتهٔ ناحیهٔ زمانی سایت است. برای پردازش‌های پیشرفته‌تر و ساخت اشیاء DateTime از wp_timezone() استفاده کنید و همیشه در طراحی سیستم‌های زمان‌بنیاد، DST و تبدیل به/از UTC را در نظر داشته باشید. رعایت این نکات باعث می‌شود نمایش و ذخیرهٔ زمان‌ها در سایت شما دقیق و یکپارچه باشد.

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

ارسال