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

در توسعه پلاگین‌ها و قالب‌های وردپرس اغلب نیاز به ساخت پوشه‌های جدید به‌صورت بازگشتی (مثل mkdir -p در لینوکس) داریم. تابع wp_mkdir_p() یک کمک‌ابزار داخلی وردپرس است که همین کار را برای شما انجام می‌دهد. در این مقاله به صورت دقیق، با مثال و نکات امنیتی و بهترین‌شیوه‌ها به بررسی این تابع می‌پردازیم.

تابع wp_mkdir_p چیست؟

تابع wp_mkdir_p یک wrapper ساده است که سعی می‌کند مسیر داده‌شده را به‌صورت بازگشتی ایجاد کند. این تابع مسیرها را نرمالایز می‌کند، پوشه‌های لازم را یکی‌یکی می‌سازد و در نهایت نتیجه (true/false) را بازمی‌گرداند.

خلاصه عملکرد

چرا از wp_mkdir_p استفاده کنیم؟

• سازگاری با وردپرس: تابع در هسته وردپرس قرار دارد و برای تسهیل عملیات فایل طراحی شده است.
• ایمن‌تر از فراخوانی مستقیم mkdir با اعلام خطاها (تابع از @ برای سرکوب هشدارها استفاده می‌کند).
• عملکرد بازگشتی بدون نیاز به نوشتن منطق دستی برای ساخت چند سطح پوشه.

مثال پایه‌ای

if ( ! function_exists( 'wp_mkdir_p' ) ) {
    require_once ABSPATH . 'wp-admin/includes/file.php';
}

$upload_dir = wp_upload_dir();
$dir = trailingslashit( $upload_dir['basedir'] ) . 'my-plugin-cache';

if ( ! wp_mkdir_p( $dir ) ) {
    // مدیریت خطا: مثلاً ثبت در لاگ یا نمایش پیغام
    error_log( "Could not create directory: $dir" );
} else {
    // مسیر آماده استفاده است
}

در این مثال ابتدا مطمئن می‌شویم که فایل کمکی شامل تابع بارگذاری شده؛ سپس مسیر پایه آپلود را گرفته و یک زیرپوشه ایجاد می‌کنیم. اگر ساخت پوشه موفق نباشد، با error_log خطا ثبت می‌شود.

مثال پیشرفته — استفاده از WP_Filesystem

require_once ABSPATH . 'wp-admin/includes/file.php';

$creds = request_filesystem_credentials( site_url() . '/wp-admin/', '', false, false, null );

if ( ! WP_Filesystem( $creds ) ) {
    // دسترسی به فایل‌سیستم فراهم نشد
    return;
}

global $wp_filesystem;
$dir = WP_CONTENT_DIR . '/my-plugin-cache';

if ( ! $wp_filesystem->is_dir( $dir ) ) {
    $wp_filesystem->mkdir( $dir, FS_CHMOD_DIR );
}

این روش در میزبان‌هایی که نیاز به اعتبارسنجی FTP/SSH دارند مناسب‌تر است. WP_Filesystem یک انتزاع برای عملیات فایل فراهم می‌کند و به شما اجازه می‌دهد تا از روش مناسب برای سرور فعلی استفاده کنید.

نکات امنیتی و مجوزها (Permissions)

• تابع wp_mkdir_p معمولاً سعی می‌کند دسترسی‌ها را روی 0777 قرار دهد و سپس chmod می‌کند؛ اما این مقدار همیشه مطلوب نیست. مقدار 0755 (FS_CHMOD_DIR) به‌طور معمول امن‌تر است.
• روی هاست‌های اشتراکی به 0777 نیازی نیست و ممکن است خطر امنیتی ایجاد کند. اگر امکان‌پذیر است مالکیت فایل/پوشه را درست کنید یا از FS_CHMOD_DIR استفاده کنید.
• قبل از ساخت پوشه، ورودی کاربر را اعتبارسنجی و مسیرها را نرمالایز کنید تا از directory traversal جلوگیری شود.

مقایسه wp_mkdir_p با mkdir PHP

تابع PHP: mkdir($dir, 0755, true) نیز قابلیت بازگشتی دارد. تفاوت‌های مهم:

• wp_mkdir_p برای استفاده در وردپرس طراحی شده و با توابع کمکی دیگر سازگار است.
• در شرایطی که سرور نیاز به استفاده از FTP برای نوشتن فایل دارد، wp_mkdir_p به تنهایی کافی نیست و باید از WP_Filesystem استفاده کنید.
• wp_mkdir_p هشدارها را سرکوب می‌کند و رفتار مشخصی در مواجهه با خطا دارد؛ درحالی‌که mkdir خطا/هشدار صادر می‌کند.

مثال: ساخت مسیر داخل wp-content/uploads و ذخیره فایل

$upload = wp_upload_dir();
$dir = trailingslashit( $upload['basedir'] ) . 'my-plugin/temp';

if ( wp_mkdir_p( $dir ) ) {
    $file = $dir . '/example.txt';
    file_put_contents( $file, 'Hello from my plugin' );
} else {
    error_log( 'Unable to create upload directory for my-plugin' );
}

در این سناریو اگر ساخت پوشه موفق باشد، فایل example.txt در آن نوشته خواهد شد. اگر نه، خطا در لاگ ثبت می‌شود. توجه داشته باشید که در برخی سرورها ممکن است file_put_contents با موفقیت کار نکند مگر اینکه مالکیت و سطح دسترسی پوشه مناسب باشد.

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

• همیشه از توابع وردپرس مانند wp_upload_dir، trailingslashit و wp_mkdir_p استفاده کنید تا از مشکلات پورت‌ها و مسیرها جلوگیری شود.
• برای عملیات حساس به‌خصوص روی هاست‌های دارای محدودیت، از WP_Filesystem استفاده کنید تا وردپرس بتواند از FTP یا دیگر روش‌ها کمک بگیرد.
• برای رفع باگ‌ها، پیام‌های خطا را لاگ کنید و تجربه کاربری را با پیام‌های مناسب مدیریت کنید.
• از ورودی‌های کاربر برای تعیین نام پوشه استفاده نکنید؛ یا حداقل آن‌ها را sanitize کرده و از توابعی مثل sanitize_file_name استفاده کنید.

جمع‌بندی

تابع wp_mkdir_p یک ابزار ساده اما حیاتی برای توسعه‌دهندگان وردپرس است که کمک می‌کند پوشه‌ها را به‌آسانی و بازگشتی ایجاد کنند. با این حال، باید به مسائل مربوط به مجوز‌ها و محیط سرور (FTP/SSH) توجه کنید و در مواقع لازم از WP_Filesystem بهره ببرید. رعایت نکات امنیتی و استفاده از توابع وردپرس باعث می‌شود افزونه‌ها و قالب‌های شما پایدارتر و سازگارتر با میزبان‌های مختلف باشند.

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

ارسال