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

تابع get_template_directory() یکی از توابع پایه‌ای وردپرس برای به‌دست آوردن مسیر فایل‌سیستم (filesystem path) قالبِ اصلی (parent theme) است. این تابع زمانی کاربرد دارد که می‌خواهید به فایل‌های قالب والد دسترسی پیدا کنید — برای بارگذاری فایل‌ها، include/require و یا ثبت مسیرهای فایل در سرور.

چیست و چه برمی‌گرداند؟

get_template_directory() مسیر کامل (absolute filesystem path) دایرکتوری قالب اصلی سایت را برمی‌گرداند. این مقدار برای عملیات فایل روی سرور (مثل include یا require) مناسب است و با URL اشتباه گرفته نشود.

وقتی قالب فرزند (child theme) فعال است چه تفاوتی دارد؟

نکته کلیدی: get_template_directory() همیشه مسیر قالب والد را برمی‌گرداند، حتی اگر قالب فرزند فعال باشد. اگر نیاز دارید مسیر قالب فعال (که می‌تواند فرزند باشد) را بگیرید، باید از get_stylesheet_directory() استفاده کنید.

مثال‌های عملی و کاربردها

• include/require فایل‌های کمکی از داخل پوشه /inc قالب والد
• ثبت مسیر به فایل‌های PHP برای autoload یا loader
• استفاده در اسکریپت‌های سروری که با سیستم‌فایل کار می‌کنند (خواندن/نوشتن)

مثال: include یک فایل PHP از قالب والد

require_once get_template_directory() . '/inc/helpers.php';

این کد فایل helpers.php در پوشه inc قالب والد را بارگذاری می‌کند. توضیح: از آنجا که get_template_directory() مسیر فایل‌سیستم را برمی‌گرداند، آن را با نام فایل ترکیب می‌کنیم و با require_once به بارگذاری می‌پردازیم. اگر بخواهید اجازه دهید فایل در قالب فرزند جایگزین شود، نباید از این روش استفاده کنید؛ در عوض از locate_template یا get_stylesheet_directory استفاده کنید.

مثال: enqueue کردن استایل والد در قالب فرزند

add_action( 'wp_enqueue_scripts', 'child_theme_enqueue_styles' );
function child_theme_enqueue_styles() {
    wp_enqueue_style( 'parent-style', get_template_directory_uri() . '/style.css' );
    wp_enqueue_style( 'child-style',
        get_stylesheet_uri(),
        array( 'parent-style' )
    );
}

توضیح: در این مثال از get_template_directory_uri() (نسخه URL تابع) برای آدرس‌دهی به فایل style.css قالب والد استفاده می‌کنیم؛ زیرا برای مرورگر نیاز به URL داریم نه مسیر فایل‌سیستم. سپس استایل فرزند را با وابستگی به استایل والد بارگذاری می‌کنیم تا ترتیب درست CSS حفظ شود.

مقایسه توابع مرتبط

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

• برای دسترسی به فایل‌ها روی سرور از get_template_directory() یا get_stylesheet_directory() استفاده کنید؛ برای URLها از نسخه _uri استفاده کنید.
• اگر می‌خواهید اجازه دهید توسعه‌دهنده قالب فرزند برخی فایل‌ها را بازنویسی کند، از locate_template() یا get_stylesheet_directory استفاده کنید تا اولویت با فرزند باشد.
• برای جلوگیری از مشکلات مسیر از توابع کمکی وردپرس مانند trailingslashit() یا wp_normalize_path در موارد نیاز استفاده کنید.
• از داده‌های بیرونی در مسیرها استفاده نکنید یا حتماً آن‌ها را اعتبارسنجی/اسکیپ کنید تا از حملات مسیردهی (path traversal) جلوگیری شود.
• در پلاگین‌ها بهتر است روی فایل‌های قالب تکیه نکنید؛ اگر نیاز به تعامل با قالب است، از فیلترها و اکشن‌ها استفاده کنید یا از توابع امنی مانند get_theme_file_path() و get_parent_theme_file_path() بهره ببرید.

نمونه پیشرفته: بارگذاری template part با اولویت قالب فرزند

// استفاده از locate_template برای احترام به قالب فرزند
if ( locate_template( 'template-parts/my-part.php', true, false ) ) {
    // فایل بارگذاری شده است (فرزند ترجیح داده می‌شود)
}

توضیح: locate_template ابتدا در قالب فرزند به دنبال فایل می‌گردد و اگر پیدا نکرد، در قالب والد جستجو می‌کند. آرگومان دوم (true) مشخص می‌کند که فایل به‌صورت include انجام شود و آرگومان سوم (false) مانع از load مستقیم با require_once می‌شود (به کنترل بهتر کمک می‌کند).

به‌روزرسانی‌های جدید و توابع جایگزین

نسخه‌های جدید وردپرس توابعی مثل get_parent_theme_file_path() و get_theme_file_path() ارائه کرده‌اند که در برخی سناریوها خوانایی و تطابق بیشتری دارند. برای مثال get_parent_theme_file_path(‘inc/file.php’) مسیر کامل فایل در قالب والد را برمی‌گرداند و به‌صورت داخلی امن‌تر و واضح‌تر است.

نتیجه‌گیری و راهنمای سریع

• get_template_directory() = مسیر فایل‌سیستم قالب والد (برای include/require).
• برای اجازه دادن به قالب فرزند از get_stylesheet_directory() یا locate_template() استفاده کنید.
• برای URL منابع از get_template_directory_uri() یا get_stylesheet_directory_uri() استفاده کنید.
• همیشه از توابع وردپرس برای مسیر/URL استفاده کنید تا سازگاری با ساختارهای مختلف نصب وردپرس حفظ شود.

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

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

ارسال