تابع substr_replace() در PHP

تابع substr_replace() یکی از توابع قدرتمند رشته‌ای در PHP است که برای جایگزینی قسمتی از یک رشته (یا آرایه‌ای از رشته‌ها) با یک مقدار دیگر به‌کار می‌رود. این تابع ترکیبی از قابلیت‌های «بریدن» و «چسباندن» رشته را فراهم می‌کند و برای اصلاح یا به‌روزرسانی زیررشته‌ها بسیار مفید است.

قاعدهٔ کلی و امضای تابع

امضای تابع به‌صورت زیر است:

substr_replace ( mixed $haystack , mixed $replacement , mixed $start [, mixed $length ] ) : mixed

پارامترها:

• $haystack — رشته یا آرایه‌ای از رشته‌ها که قرار است در آن جایگزینی انجام شود.
• $replacement — رشته یا آرایه‌ای از رشته‌ها که به‌جای بخش مشخص شده قرار می‌گیرد.
• $start — موقعیت شروع جایگزینی (صفر مبنا). می‌تواند عدد مثبت یا منفی باشد.
• $length — طول قسمت جایگزینی. اگر مشخص نشود، تا انتهای رشته جایگزینی انجام می‌شود. مقدار منفی از انتهای رشته کسر می‌شود.

جدول پارامترها و رفتار

مثال‌های پایه‌ای

<?php
echo substr_replace('Hello World', 'PHP', 6); // Hello PHP
echo substr_replace('abcdef', 'X', 2, 3);    // abXf
?>

در مثال اول از اندیس 6 تا انتها (کلمه “World”) با “PHP” جایگزین می‌شود. در مثال دوم از اندیس 2 به طول 3 کاراکتر (“cde”) با “X” عوض می‌شود.

مثال با اندیس منفی و طول منفی

<?php
echo substr_replace('1234567890', '---', -4);      // 123456---
echo substr_replace('1234567890', '---', 2, -3);   // 12---7890
?>

اندیس منفی شمارش از انتهای رشته انجام می‌دهد. اگر طول منفی باشد، آن قدر از انتهای رشته کسر می‌کند.

رفتار با آرایه‌ها

جالب اینکه تابع می‌تواند آرایه‌ها را هم پردازش کند. اگر $haystack آرایه باشد، برای هر عنصر جایگزینی انجام می‌شود. همچنین $replacement، $start و $length نیز می‌توانند آرایه باشند که به‌صورت زوجی-به-زوجی اعمال می‌شوند.

<?php
$hay = ['apple', 'banana', 'cherry'];
$rep = ['A', 'B', 'C'];
print_r(substr_replace($hay, $rep, 1, 2));
?>

در این مثال برای هر رشته از اندیس 1 به طول 2، مقدار متناظر آرایه $rep قرار می‌گیرد. خروجی آرایهٔ اصلاح‌شده است.

موارد کاربرد و مقایسه با توابع دیگر

• زمانی که می‌خواهید بخشی از رشته را بر اساس موقعیت جایگزین کنید، substr_replace دقیقاً مناسب است؛ برخلاف str_replace که بر پایهٔ مقداری (value-based) جایگزینی انجام می‌دهد.
• برای عملیات پیچیده‌تر بر پایهٔ الگوها، preg_replace مناسب‌تر است؛ اما برای جایگزینی ساده بر اساس موقعیت، خدشه‌ناپذیر و سریع‌تر است.
• substr برای استخراج زیررشته و سپس اتصال دستی replacement قابل استفاده است، اما substr_replace کد را خلاصه‌تر و امن‌تر می‌کند.

نکات فنی و رفتار مرزی

• تابع اندیس‌ها را به عنوان بایت می‌شمارد؛ بنابراین برای رشته‌های چندبایتی (مثل UTF-8) ممکن است کاراکترها بریده شوند. این تابع multi-byte safe نیست.
• اگر $start از طول رشته بزرگ‌تر باشد، replacement به انتها چسبیده می‌شود.
• اگر $length برابر صفر باشد، replacement صرفاً در موقعیت start درج می‌شود (حذف انجام نمی‌شود).

نسخهٔ ایمن برای رشته‌های UTF-8 (پیشنهاد)

از آنجا که substr_replace روی بایت‌ها کار می‌کند، برای کار با UTF-8 می‌توانیم تابعی بر پایهٔ mb_substr بسازیم:

<?php
function mb_substr_replace($string, $replacement, $start, $length = null, $encoding = 'UTF-8') {
    $strlen = mb_strlen($string, $encoding);
    if ($start  $strlen) {
        $start = $strlen;
    }

    if ($length === null) {
        $length = $strlen - $start;
    } elseif ($length < 0) {
        $length = max(0, $strlen - $start + $length);
    }

    $prefix = mb_substr($string, 0, $start, $encoding);
    $suffix = mb_substr($string, $start + $length, null, $encoding);
    return $prefix . $replacement . $suffix;
}

// مثال
echo mb_substr_replace('سلام دنیا', 'جهان', 6, 3); // سلام جهان
?>

این تابع با استفاده از توابع mb_* طول و برش‌های امن برای یونیکد را محاسبه می‌کند و بجای بایت، بر مبنای کاراکتر کار می‌کند. بنابراین از بروز برش نصف کاراکترها جلوگیری می‌شود.

بهینه‌سازی و نکات عملکردی

• برای جایگزینی‌های متعدد روی یک رشته، بهتر است همهٔ تغییرات را در یک بار انجام دهید یا از الگوهای منظم استفاده کنید تا مقدار عملیات‌ رشته‌ای کاهش یابد.
• هنگام استفاده از آرایه‌ها، اندازهٔ آرایهٔ replacement و haystack را بررسی کنید تا از رفتار غیرمنتظره جلوگیری شود.
• اگر نیاز به سازگاری با یونیکد دارید از mbstring استفاده کنید و mb_substr_replace را ترجیح دهید.

مثال پیشرفته: بروزرسانی یک قالب

<?php
$template = 'Dear {name}, your order #{order} is {status}.';
$replacements = [
    '{name}' => 'Ali',
    '{order}' => '12345',
    '{status}' => 'shipped'
];
// با str_replace ساده هم می‌توان این کار را کرد:
$result = str_replace(array_keys($replacements), array_values($replacements), $template);
echo $result; // Dear Ali, your order #12345 is shipped.
?>

اگرچه این مثال با str_replace ساده انجام می‌شود، اما نشان می‌دهد که در بسیاری از سناریوها انتخاب بین substr_replace و str_replace بستگی به اینکه جایگزینی بر مبنای موقعیت یا بر مبنای مقدار باشد، دارد.

خلاصه و توصیه

تابع substr_replace() ابزار ساده و کاربردی برای جایگزینی بر اساس موقعیت در رشته‌هاست. برای رشته‌های UTF-8 یا زمانی که نیاز به محاسبه بر مبنای کاراکتر دارید، از نسخهٔ مبتنی بر mb_substr یا روش‌های مشابه استفاده کنید. هنگام کار با آرایه‌ها به تطابق اندازهٔ آرایه‌ها توجه کنید و در موقعیت‌هایی که جایگزینی براساس الگو مورد نیاز است، preg_replace را در نظر بگیرید.

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

ارسال