تابع str_pad() در PHP

تابع str_pad() در PHP ابزاری ساده و کاربردی برای افزودن کاراکترها به اطراف یک رشته است تا طول مشخصی را پر کند. این تابع در قالب خروجی‌های نمایشی، تولید شناسه‌های ثابت‌طول، یا آماده‌سازی فایل‌های fixed-width بسیار مفید است. در این مقاله به پارامترها، حالت‌ها، مثال‌های عملی و نکات پیشرفته (از جمله کار با رشته‌های چندبایتی) می‌پردازیم.

سینتکس و پارامترها

مقادیر pad_type

• STR_PAD_RIGHT — اضافه کردن کاراکترها در سمت راست (پیش‌فرض)
• STR_PAD_LEFT — اضافه کردن کاراکترها در سمت چپ
• STR_PAD_BOTH — پخش کردن padding بین چپ و راست (در صورت نیاز سمت راست یک کاراکتر بیشتر می‌گیرد)

مثال‌های ساده

<?php
echo str_pad('7', 3, '0', STR_PAD_LEFT);   // "007"
echo str_pad('abc', 6, '-');               // "abc---" (STR_PAD_RIGHT پیش‌فرض)
echo str_pad('PHP', 7, '*', STR_PAD_BOTH); // "**PHP**" یا بسته به تقسیم ممکن است "*PHP***"
?>

در این قطعه کد، ابتدا از str_pad برای تکمیل عدد به 3 کاراکتر با صفر استفاده شده — شیوه‌ای رایج برای شناسه‌ها یا شماره‌گذاری. نمونه دوم نشان می‌دهد که پیش‌فرض سمت راست است. نمونه سوم تکمیل دوطرفه را نمایش می‌دهد.

قوانین و نکات مهم

• اگر pad_length کمتر یا مساوی طول فعلی رشته باشد، تابع رشته اصلی را برمی‌گرداند.
• اگر pad_string خالی باشد، PHP هشدار می‌دهد؛ بنابراین همواره یک pad_string معتبر مشخص کنید.
• برای اعداد و فرمت‌های عددی، گاهی استفاده از sprintf() یا number_format() مناسب‌تر و سریع‌تر است.
• str_pad بر اساس بایت‌ها عمل می‌کند؛ در برخورد با حروف چندبایته (مثلاً فارسی یا یونیکد) باید احتیاط کرد.

نمونه کاربردی: تولید رشته‌های fixed-width برای فایل

<?php
$rows = [
  ['id' => 1, 'name' => 'علی', 'amount' => 500],
  ['id' => 12, 'name' => 'زهرا', 'amount' => 12345],
];

foreach ($rows as $r) {
    $id = str_pad((string)$r['id'], 5, '0', STR_PAD_LEFT);      // 5 chars
    $name = str_pad($r['name'], 20);                            // 20 chars, right pad
    $amount = str_pad((string)$r['amount'], 10, ' ', STR_PAD_LEFT);
    echo $id . $name . $amount . "n";
}
?>

این مثال نمایش می‌دهد چگونه می‌توان رکوردها را برای یک فایل fixed-width آماده کرد؛ اما توجه کنید در نام‌ها که ممکن است کاراکترهای چندبایته باشند (فارسی)، str_pad ممکن است طول‌های نادرست ایجاد کند و باعث جابه‌جایی ستون‌ها شود.

کار با رشته‌های چندبایته (UTF-8)

str_pad بر پایه تابع strlen عمل می‌کند که طول بر حسب بایت را برمی‌گرداند. برای رشته‌های UTF-8 باید از توابع چندبایته (mb_*) استفاده کرد و در نتیجه خودمان تابعی برای padding بسازیم.

<?php
function mb_str_pad($input, $pad_length, $pad_string=' ', $pad_type=STR_PAD_RIGHT, $encoding='UTF-8') {
    $input_len = mb_strlen($input, $encoding);
    if ($pad_length <= $input_len) {
        return $input;
    }
    $pad_needed = $pad_length - $input_len;
    if ($pad_string === '') {
        trigger_error('mb_str_pad: pad_string cannot be empty', E_USER_WARNING);
        return $input;
    }
    // Build repeated pad to required length (in characters)
    $repeat = ceil($pad_needed / mb_strlen($pad_string, $encoding));
    $full_pad = str_repeat($pad_string, $repeat);
    $left = $right = '';
    if ($pad_type === STR_PAD_LEFT) {
        $left = mb_substr($full_pad, 0, $pad_needed, $encoding);
    } elseif ($pad_type === STR_PAD_RIGHT) {
        $right = mb_substr($full_pad, 0, $pad_needed, $encoding);
    } else { // STR_PAD_BOTH
        $left_len = floor($pad_needed / 2);
        $right_len = $pad_needed - $left_len;
        $left = mb_substr($full_pad, 0, $left_len, $encoding);
        $right = mb_substr($full_pad, 0, $right_len, $encoding);
    }
    return $left . $input . $right;
}
?>

کد بالا یک نسخهٔ امن برای UTF-8 فراهم می‌کند. ابتدا طول واقعی رشته با mb_strlen گرفته می‌شود، سپس برحسب کاراکتر padding لازم محاسبه و با استفاده از mb_substr برش داده می‌شود تا از شکستن کاراکترهای چندبایته جلوگیری شود.

بهینه‌سازی‌ها و توصیه‌های کارشناسی

• برای padding با یک کاراکتر ثابت (مثلاً ‘0’ یا ‘ ‘)، استفاده از str_repeat و substr می‌تواند کارایی بیشتری داشته باشد تا تکرار str_pad در حلقه‌ها.
• اگر هدف قالب‌بندی عددی است (مثلاً تعداد اعشار یا صفرهای پیشوند)، sprintf('%03d', $num) اغلب ساده‌تر و سریع‌تر است.
• در محیط‌هایی که حافظه/سرعت مهم است، از ایجاد رشته‌های بزرگ به‌صورت مکرر اجتناب کنید و از پیش‌محاسبه padding استفاده نمایید.

خطاها و نکات امنیتی

• از pad_string خالی پرهیز کنید — PHP هشدار خواهد داد.
• در پذیرش ورودی از کاربر، قبل از اعمال padding بررسی کنید که طول یا محتوای رشته منطقی باشد تا موجب بروز خطا یا سوء استفاده نشود.
• در پردازش فایل‌های fixed-width برای بانک‌ها یا سیستم‌های مالی، رعایت دقیق encoding و اندیس‌های کاراکتری الزامی است.

نتیجه‌گیری

تابع str_pad ابزاری ساده اما قدرتمند برای تکمیل و تراز کردن رشته‌ها در PHP است. برای کاربردهای معمول کافی و سریع است، اما هنگام کار با رشته‌های چندبایته یا نیازهای خاص قالب‌بندی بهتر است از توابع mb_ و یا روش‌های سفارشی استفاده کنید. با رعایت نکات پرکاربرد و استفادهٔ درست از STR_PAD_LEFT/RIGHT/BOTH می‌توانید خروجی‌های منظم و قابل پیش‌بینی تولید کنید.

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

ارسال