عرض مصدر PHP/str replace

<noinclude>{{DISPLAYTITLE:الدالة <code>str_replace()</code>‎ في PHP}}</noinclude>
(PHP 4, PHP 5, PHP 7)

تبدِّل الدالة str_replace()‎ كل حالات وقوع سلسلة البحث إلى سلسلة الاستبدال.

== الوصف ==
<syntaxhighlight lang="php">
mixed str_replace ( mixed $search , mixed $replace , mixed $subject [, int &$count ] )
</syntaxhighlight>تعيد الدالة 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()‎  <syntaxhighlight lang="php">
<?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;
?>
</syntaxhighlight>المثال 2: مثال على أهمية ترتيب القيم في الدالة str_replace()‎

يحول المثال السطر \r\n أولاً حتى لا يحول مرتين.

ويعيد الحرف F لأنه استبدل A بـ B ، ثم استبدل B بـ C ، وهكذا ...

وأخيرا استبدل E بـ F ، بسبب الاستبدالات من اليسار إلى اليمين.<syntaxhighlight lang="php">
<?php
//  ترتيب الاستبدال
$str     = "Line 1\nLine 2\rLine 3\r\nLine 4\n";
$order   = array("\r\n", "\n", "\r");
$replace = '<br />';
$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;
?>
</syntaxhighlight>

== ملاحظات ==
ملاحظة: هذه الدالة آمنة ثنائيًا (binary-safe).

تحذير: نظرًا لأنَّ الدالة str_replace()‎ تجري عملية الاستبدال من اليسار إلى اليمين، فقد تستبدل قيمةً أُدْخِلَتْ مسبقًا عند إجراء عمليات استبدال متعددة. راجع المثال 2 في هذه الصفحة لمزيدٍ من المعلومات.

ملاحظة: هذه الدالة حساسة لحالة الأحرف. استخدم الدالة str_ireplace()‎ لاستبدال غير حساس لحالة الأحرف.

== انظر أيضًا ==
* الدالة str_ireplace()‎: نسخة غير حساسة لحالة الأحرف من الدالة str_replace()‎.
* الدالة substr_replace()‎: استبدال النص داخل جزء من سلسلة نصية.
* الدالة preg_replace()‎: إجراء عملية بحث واستبدال باستعمال التعابير النمطية (regular expressions).
* الدالة strtr()‎: تحويل الأحرف أو استبدال سلاسل نصية فرعية.

== مصادر ==
* [http://php.net/manual/en/function.str-replace.php صفحة الدالة str_replace في توثيق PHP الرسمي.]  
[[تصنيف:PHP]]
[[تصنيف:PHP Function]]
[[تصنيف:PHP String]]