تابع get_stylesheet_directory_uri چطور کار می‌کند؟
تابع get_stylesheet_directory_uri برای دریافت URL قالب فعال وردپرس؛ بررسی پارامترها، تفاوت با get_template_directory_uri و اشتباهات رایج.
6 دقیقه مطالعه
چرا URL قالب فعال اهمیت دارد؟
در توسعه Child Theme وردپرس، یکی از پرتکرارترین کارها، لینک کردن فایل‌های CSS، JavaScript و تصاویر سفارشی است. برای این کار باید URL عمومی قالب فعال مشخص باشد. اگر از URL قالب اصلی (Parent) استفاده کنید، فایل‌های سفارشی Child Theme نادیده گرفته می‌شوند و تغییرات شما اعمال نمی‌شود. تابعget_stylesheet_directory_uri() ابزار استاندارد وردپرس برای دریافت URL قالب فعال است و پایه پیاده‌سازی الگوی Override در Child Theme است.
تابع get_stylesheet_directory_uri چیست؟
تابعget_stylesheet_directory_uri() یک تابع هسته وردپرس است که در فایل wp-includes/theme.php تعریف شده است. این تابع URL عمومی پوشه قالب فعال را برمی‌گرداند.
مقدار بازگشتی یک رشته است که به URL پوشه قالب فعال اشاره می‌کند، بدون اسلش انتهایی. برای نمونه اگر Child Theme فعال باشد:
https://example.com/wp-content/themes/mytheme-childامضای تابع و پارامترها
امضای این تابع به‌شکل زیر است:function get_stylesheet_directory_uri() {
$stylesheet = str_replace( '%2F', '/', rawurlencode( get_stylesheet() ) );
$theme_root_uri = get_theme_root_uri( $stylesheet );
$stylesheet_dir_uri = "$theme_root_uri/$stylesheet";
return apply_filters( 'stylesheet_directory_uri', $stylesheet_dir_uri, $stylesheet, $theme_root_uri );
}stylesheet_directory_uri دارد که امکان تغییر URL را فراهم می‌کند.
نکته مهم این است که URL بازگشتی هیچ اسلش انتهایی ندارد. بنابراین هنگام ساخت URL فایل، باید از trailingslashit() یا ترکیب با اسلش استفاده کنید.
سازوکار داخلی تابع
تابعget_stylesheet_directory_uri() از سه تابع دیگر استفاده می‌کند:
- get_stylesheet() که نامک قالب فعال را برمی‌گرداند
- get_theme_root_uri() که URL پوشه `themes` را برمی‌گرداند
- فیلتر stylesheet_directory_uri که امکان تغییر نهایی را فراهم می‌کند
نکته مهم این است که این تابع از rawurlencode استفاده می‌کند تا کاراکترهای خاص را برای URL امن کند. این رفتار در پروژه‌هایی که نام Child Theme شامل کاراکترهای خاص است، اهمیت دارد.
تفاوت با get_template_directory_uri
این دو تابع پرتکرارترین اشتباه توسعه‌دهندگان Child Theme را می‌سازند: -get_stylesheet_directory_uri(): URL قالب فعال (Child Theme در صورت وجود)
- get_template_directory_uri(): URL قالب اصلی (Parent Theme)
در سایت بدون Child Theme، این دو تابع مقدار یکسانی برمی‌گردانند. اما وقتی Child Theme فعال است، تفاوت آشکار می‌شود.
قاعده ساده:
- اگر فایلی را از Child Theme بارگذاری می‌کنید و می‌خواهید فایل سفارشی جایگزین فایل والد شود، از get_stylesheet_directory_uri() استفاده کنید.
- اگر فایلی همیشه در Parent Theme است و کاربر نباید آن را تغییر دهد، از get_template_directory_uri() استفاده کنید.
راهنمای تابع دیگر در صفحه get_template_directory_uri آمده است.
کاربردهای عملی در Child Theme
یکی از رایج‌ترین کاربردها، بارگذاری فایل CSS Child Theme است:wp_enqueue_style(
'mytheme-child-style',
get_stylesheet_directory_uri() . '/assets/css/child.css',
array(),
'1.0.0'
);$banner_url = get_stylesheet_directory_uri() . '/assets/images/child-banner.jpg';
echo ' . ')
';esc_url() برای URL و از esc_attr__() برای متن ALT استفاده شده است.
کاربرد سوم، بارگذاری فایل ترجمه از Child Theme است:
load_child_theme_textdomain(
'mytheme-child',
get_stylesheet_directory() . '/languages'
);الگوی Override فایل‌های والد
یکی از الگوهای حرفه‌ای در Child Theme، جایگزینی شرطی فایل‌های والد است. این الگو به‌ویژه در پروژه‌هایی که Parent Theme قابل ویرایش نیست، بسیار کاربردی است:$child_css = get_stylesheet_directory_uri() . '/assets/css/header.css';
$parent_css = get_template_directory_uri() . '/assets/css/header.css';
if ( file_exists( get_stylesheet_directory() . '/assets/css/header.css' ) ) {
wp_enqueue_style( 'mytheme-header', $child_css );
} else {
wp_enqueue_style( 'mytheme-header', $parent_css );
}نقش esc_url در خروجی
همیشه URLهای تولیدشده توسط توابع وردپرس را باesc_url() عبور دهید. این تابع کاراکترهای خطرناک را حذف می‌کند و از حملات XSS جلوگیری می‌کند.
اگر URL را مستقیماً در HTML چاپ کنید، مهاجم می‌تواند از طریق فیلترها یا داده‌های ذخیره‌شده، کاراکترهای مخرب تزریق کند. برای مطالعه بیشتر درباره توابع escape، می‌توانید به راهنمای esc_html مراجعه کنید.
الگوی صحیح:
echo '';نکات امنیتی و اشتباهات رایج
اشتباه اول، استفاده از این تابع در Parent Theme بدون Child Theme است. در این حالت، این تابع همان مقدارget_template_directory_uri را برمی‌گرداند و تفاوتی ندارد. بنابراین اگر فقط Parent Theme دارید، هر دو تابع یکسان عمل می‌کنند.
اشتباه دوم، نبود esc_url است. هر URL که در HTML چاپ می‌شود باید با esc_url عبور کند.
اشتباه سوم، نبود اسلش پیش از نام فایل است. اگر URL را بدون اسلش با نام فایل ترکیب کنید، URL نادرست ساخته می‌شود.
اشتباه چهارم، استفاده از این تابع برای include فایل‌های PHP است. برای include باید از get_stylesheet_directory() استفاده کنید که مسیر فیزیکی برمی‌گرداند.
اشتباه پنجم، نبود بررسی file_exists است. اگر فایلی که لینک می‌کنید وجود نداشته باشد، خطای ۴۰۴ رخ می‌دهد.
اشتباه ششم، نبود تست در Parent و Child Theme است. باید در هر دو حالت رفتار کد را بررسی کنید.
تحلیل فنی پیشرفته
در نگاه مهندسی، تابعget_stylesheet_directory_uri() یک نقطه معماری در لایه قالب است که بر چند جنبه از سیستم اثر می‌گذارد. لایه اول لایه URL است. این تابع بر پایه get_theme_root_uri کار می‌کند و URL را با در نظر گرفتن HTTPS، پروکسی معکوس و هاست‌های توزیع‌شده محاسبه می‌کند.
لایه دوم لایه کشینگ است. نتیجه این تابع در حافظه کش می‌شود و در طول درخواست HTTP باقی می‌ماند.
لایه سوم لایه امنیت است. URLهای تولیدشده ممکن است در خروجی HTML چاپ شوند و اگر به‌درستی escape نشوند، می‌توانند به حمله XSS منجر شوند. همیشه از esc_url استفاده کنید.
لایه چهارم لایه CDN است. در پروژه‌هایی که از CDN استفاده می‌کنند، URLهای قالب معمولاً به دامنه CDN اشاره می‌کنند. این تغییر توسط فیلتر stylesheet_directory_uri یا فیلترهای مرتبط انجام می‌شود.
لایه پنجم لایه Override است. الگوی Override در Child Theme، یکی از پایه‌ای‌ترین اصول توسعه در وردپرس است و این تابع یکی از اجزای کلیدی آن است.
لایه ششم لایه استقرار است. در محیط‌های Staging و Production، دامنه‌ها متفاوت هستند. استفاده از توابع وردپرس بر مسیرهای مطلق ارجحیت دارد.
لایه هفتم لایه Performance است. درج تعداد زیاد فایل‌های CSS و JS به‌صورت جداگانه می‌تواند زمان بارگذاری را افزایش دهد. بهتر است فایل‌ها را ادغام کنید یا از HTTP/2 استفاده کنید.
لایه هشتم لایه Multisite است. در شبکه‌های Multisite، هر سایت می‌تواند Child Theme متفاوتی داشته باشد و این تابع همیشه URL Child Theme سایت جاری را برمی‌گرداند.
مفاهیم پایه‌ای URL در URL در ویکی‌پدیا توضیح داده شده است.
برای مطالعه بیشتر روی توابع مرتبط، می‌توانید به راهنمای wp_get_theme، راهنمای add_theme_support، راهنمای get_header، راهنمای get_footer، راهنمای get_sidebar و راهنمای get_template_part مراجعه کنید.
پرسش‌های پرتکرار
تفاوت get_stylesheet_directory_uri و get_template_directory_uri چیست؟ اولی URL قالب فعال و دومی URL قالب اصلی را برمی‌گرداند. آیا URL بازگشتی اسلش انتهایی دارد؟ خیر، URL بدون اسلش انتهایی برگردانده می‌شود. آیا می‌توان از این تابع برای include فایل PHP استفاده کرد؟ خیر، برای include باید ازget_stylesheet_directory استفاده کنید.
آیا این تابع در Parent Theme کار می‌کند؟ بله، در این حالت همان URL Parent Theme را برمی‌گرداند.
چطور فایلی را از Child Theme با اولویت بالاتر بارگذاری کنیم؟ با ترکیب get_stylesheet_directory_uri، get_template_directory_uri و file_exists.
نتیجه و مسیر ادامه
تابعget_stylesheet_directory_uri() یک ابزار پایه‌ای برای دریافت URL قالب فعال در وردپرس است. استفاده درست از آن یعنی درک دقیق تفاوت با get_template_directory_uri()، توجه به اسلش انتهایی، escape با esc_url و تست در Parent و Child Theme. اشتباه‌های کوچک در این تابع اغلب به خطای ۴۰۴ یا نمایش نادرست فایل منجر می‌شوند.
اگر این تابع را در پروژه‌ای واقعی به کار برده‌اید و رفتار غیرمنتظره‌ای دیده‌اید — به‌خصوص در ترکیب با CDN یا در محیط‌های Multisite — تجربه‌تان می‌تواند راهگشای دیگران باشد. کدام بخش بیشترین زمان را از شما گرفت؟ دیدگاه خود را بنویسید.
سعید کریمه
نویسنده
نویسنده در وردپرس کار.