الدالة str_replace() في PHP
(PHP 4, PHP 5, PHP 7)
تبدِّل الدالة str_replace() كل حالات وقوع سلسلة البحث إلى سلسلة الاستبدال.
الوصف
mixed str_replace ( mixed $search , mixed $replace , mixed $subject [, int &$count ] )
تعيد الدالة str_replace() سلسلة أو مصفوفة مع تبديل كل حالات وقوع المعامل search في المعامل subject إلى قيمة المعامل replace المعطاة.
إذا كنت لا تحتاج إلى قواعد استبدال معقدة (باستعمال التعابير النمطية) يجب عليك دائمًا استخدام هذه الدالة بدلاً من الدالة preg_replace().
المعاملات
إذا كان المعامل search والمعامل replace مصفوفتين، فإن الدالة str_replace() تأخذ قيمة من كل مصفوفة وتستخدمها للبحث والاستبدال في المعامل subject. إذا كان المعامل replace يحتوي على قيم أقل من المعامل search، فستستخدم سلسلة نصية فارغة لبقية قيم الاستبدال. إذا كان المعامل search مصفوفة والمعامل replace سلسلة نصية، فستستخدم سلسلة الاستبدال هذه لكل قيمة من قيم المعامل search. ومع ذلك، فإن العكس ليس له معنى.
إذا كان المعامل search أو المعامل replace مصفوفة، فستعالَج عناصرها من العنصر الأول إلى العنصر الأخير.
search
القيمة التي يُبْحَث عنها والمعروفة باسم الإبرة (needle). يمكن استخدام مصفوفة لتعيين قيم متعددة.
replace
قيمة الاستبدال التي تحل محل قيم المعامل search التي تم عُثِرَ عليها. يمكن استخدام مصفوفة لتعيين بدائل متعددة.
subject
السلسلة أو المصفوفة التي يُبْحَث عنها وتستبدل، والمعروفة باسم كومة القش (haystack).
إذا كان المعامل subject مصفوفةً، فستجرى عملية البحث والاستبدال مع كل مَدْخَل للمعامل subject، وتكون القيمة المعادة مصفوفة أيضًا.
count
إذا مُرِّرَ المعامل count، فستضبط قيمته إلى عدد عمليات الاستبدال التي نُفِّذَت.
القيم المعادة
تعيد الدالة str_replace() سلسلة نصية أو مصفوفة بها القيم المستبدلة.
أمثلة
المثال 1: مثال بسيط على الدالة str_replace()
<?php
// <body text='black'>
$bodytag = str_replace("%body%", "black", "<body text='%body%'>");
// Hll Wrld f PHP
$vowels = array("a", "e", "i", "o", "u", "A", "E", "I", "O", "U");
$onlyconsonants = str_replace($vowels, "", "Hello World of PHP");
$newphrase = str_replace($healthy, $yummy, $phrase);
// 2
$str = str_replace("ll", "", "good golly miss molly!", $count);
echo $count;
?>
المثال 2: مثال على أهمية ترتيب القيم في الدالة str_replace()
يحول المثال الأول السطر \r\n أولاً حتى لا يحول مرتين. وسيعيد المثل الثاني الحرف F لأنه استبدل A بالحرف B ، ثم استبدل B بالحرف C ، وهكذا ... وأخيرا استبدل E بالحرف F ، بسبب أنَّ الاستبدالات تجرى من اليسار إلى اليمين.
<?php
// ترتيب الاستبدال
$str = "Line 1\nLine 2\rLine 3\r\nLine 4\n";
$order = array("\r\n", "\n", "\r");
$replace = '<br />';
// الناتج هو F
$newstr = str_replace($order, $replace, $str);
$search = array('A', 'B', 'C', 'D', 'E');
$replace = array('B', 'C', 'D', 'E', 'F');
$subject = 'A';
echo str_replace($search, $replace, $subject);
// apearpearle pear
// لنفس السبب المذكور أعلاه.
$letters = array('a', 'p');
$fruit = array('apple', 'pear');
$text = 'a p';
$output = str_replace($letters, $fruit, $text);
echo $output;
?>
ملاحظات
ملاحظة: هذه الدالة آمنة ثنائيًا (binary-safe).
تحذير: نظرًا لأنَّ الدالة str_replace() تجري عملية الاستبدال من اليسار إلى اليمين، فقد تستبدل قيمةً أُدْخِلَتْ مسبقًا عند إجراء عمليات استبدال متعددة. راجع المثال 2 في هذه الصفحة لمزيدٍ من المعلومات.
ملاحظة: هذه الدالة حساسة لحالة الأحرف. استخدم الدالة str_ireplace() لاستبدال غير حساس لحالة الأحرف.
انظر أيضًا
- الدالة
str_ireplace(): نسخة غير حساسة لحالة الأحرف من الدالةstr_replace(). - الدالة
substr_replace(): استبدال النص داخل جزء من سلسلة نصية. - الدالة
preg_replace(): إجراء عملية بحث واستبدال باستعمال التعابير النمطية (regular expressions). - الدالة
strtr(): تحويل الأحرف أو استبدال سلاسل نصية فرعية.