الدالة str_replace() في PHP: استبدال نص داخل نص

تعيد str_replace($search, $replace, $subject) نسخة من $subject مع استبدال كل ظهور لـ $search بـ $replace. تعيد str_replace('world', 'PHP', 'Hello world') النص "Hello PHP".

<?php
$text = 'I like cats. cats are great.';

$new = str_replace('cats', 'dogs', $text);

echo $new, "\n";
echo $text, "\n";   // the original is unchanged

تعيد الدالة النص الجديد؛ ولا تعدّل المتغير الذي تمرره. أسند النتيجة، ولو إلى المتغير نفسه: $text = str_replace(...).

الصيغة

str_replace(
    array|string $search,
    array|string $replace,
    string|array $subject,
    int &$count = null
): string|array

يمكن أن يكون كل من الوسائط الثلاثة الأولى نصًا أو مصفوفة. وإذا كان $subject مصفوفة، يُنفَّذ الاستبدال على كل عنصر وتحصل على مصفوفة بالمفاتيح نفسها: تعيد str_replace('.txt', '.md', ['a.txt', 'b.txt']) المصفوفة ['a.md', 'b.md']. البحث حساس لحالة الأحرف ويطابق نصًا حرفيًا، لا أنماطًا. للأنماط استخدم preg_replace().

استبدال عدة نصوص معًا

مرّر مصفوفات لـ $search و$replace. تُستبدل قيمة البحث الأولى بالبديل الأول، والثانية بالثاني، وهكذا. وإذا كان $replace نصًا واحدًا، تُستبدل به كل قيم البحث، وهذه الطريقة القصيرة لحذف مجموعة من المحارف.

<?php
$template = 'Hello {name}, your order {id} has shipped.';

echo str_replace(['{name}', '{id}'], ['Ada', '#1042'], $template), "\n";

// One replacement for every search value: remove punctuation
echo str_replace(['.', ',', '!', '?'], '', 'Hi, there! Ready? Yes.'), "\n";

// Fewer replacements than searches: the missing ones are ""
echo str_replace(['a', 'b', 'c'], ['1'], 'abcabc'), "\n";

فخ الترتيب وstrtr()

مع المصفوفات، تنفّذ str_replace() استبدالًا تلو الآخر على النص كله. وقد يطابق بحث لاحق نصًا أدرجه للتو استبدال سابق. أما strtr() مع مصفوفة فتستبدل كل شيء في مرور واحد، وتجرّب المفاتيح الأطول أولًا، ولا تلمس أبدًا نصًا سبق استبداله.

<?php
$s = 'apple banana';

// apple -> banana, then every banana (including the new one) -> cherry
echo str_replace(['apple', 'banana'], ['banana', 'cherry'], $s), "\n";

// One pass: each original word is replaced once
echo strtr($s, ['apple' => 'banana', 'banana' => 'cherry']), "\n";

استخدم strtr() للتبديل ولعناصر القوالب النائبة التي قد تظهر في القيم.

عدّ مرات الاستبدال

يُملأ الوسيط الرابع بعدد الاستبدالات التي جرت. مرّر متغيرًا؛ تكتب PHP فيه.

<?php
$text = 'one fish, two fish, red fish, blue fish';

$result = str_replace('fish', 'cat', $text, $count);

echo $result, "\n";
echo "Replaced $count times\n";

الاستبدال دون حساسية لحالة الأحرف بـ str_ireplace

تأخذ str_ireplace() الوسائط نفسها وتتجاهل حالة الأحرف عند المطابقة. ويُدرج البديل تمامًا كما كتبته.

<?php
$text = 'PHP, php and Php';

echo str_replace('php', 'Python', $text), "\n";
echo str_ireplace('php', 'Python', $text), "\n";

لا تطوي str_ireplace() إلا حروف ASCII. للاستبدال دون حساسية لحالة الأحرف مع الحروف ذات العلامات أو الكيريلية، استخدم preg_replace() مع المعدّلين i وu.

استبدال الظهور الأول فقط

تستبدل str_replace() كل شيء دائمًا. لاستبدال أول تطابق فقط، جده بـ strpos() واقطعه بـ substr_replace():

<?php
function replaceFirst(string $search, string $replace, string $subject): string
{
    $pos = strpos($subject, $search);
    if ($pos === false) {
        return $subject;
    }
    return substr_replace($subject, $replace, $pos, strlen($search));
}

echo replaceFirst('a', 'A', 'banana'), "\n";

// The same with a regex and a limit of 1
echo preg_replace('/' . preg_quote('a', '/') . '/', 'A', 'banana', 1), "\n";

للظهور الأخير، استخدم strrpos() مكان strpos().

حذف المسافات والأسطر الجديدة والمحارف الأخرى

الاستبدال بنص فارغ يحذف النص. ومن عمليات التنظيف الشائعة حذف فواصل الأسطر أو كل المسافات، وكثيرًا ما تحتوي المُدخلات اليابانية على مسافات كاملة العرض (　، U+3000) لا يطابقها البحث العادي عن " ".

<?php
$text = "line one\r\nline two\nline three";
echo str_replace(["\r\n", "\n", "\r"], ' ', $text), "\n";

$phone = '090 1234 5678';
echo str_replace(' ', '', $phone), "\n";

$name = '山田　太郎';
echo str_replace('　', ' ', $name), "\n";   // full-width space to normal space

ضع "\r\n" قبل "\n" و"\r" في المصفوفة، حتى يصبح فاصل أسطر Windows مسافة واحدة لا اثنتين.