عرض مصدر PHP/preg replace callback

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

تبحث الدالة <code>preg_replace_callback()‎‎</code> عن تعبير نمطي وتستبدله باستخدام دالة مُعرَّفة من المستخدم.

== الوصف ==
<syntaxhighlight lang="php">
mixed preg_replace_callback ( mixed $pattern , callable $callback , mixed $subject [, int $limit= -1 [, int &$count ]] )
</syntaxhighlight>يتطابق سلوك هذه الوظيفة تقريبًا مع الدالة <code>[[PHP/preg replace|preg_replace()‎‎]]</code>، باستثناء أنه يجب تحديد الدالة المُعرَّفة من المستخدم <code>callback</code> بدلاً من المعامل <code>replacement</code>.

== المعاملات ==

=== <code>pattern</code> ===
النمط المراد البحث عنه. ويمكن أن يكون إما سلسلةً نصيةً أو مصفوفةً من السلاسل النصية.

=== <code>callback</code> ===
الدالة المُعرَّفة من المستخدم التي تُستدعى وتُمرِر مصفوفة من العناصر المطابقة في السلسلة النصية الهدف <code>subject</code>. يجب أن تُعيد الدالة المعرفة من المستخدم سلسلة الاستبدال النصية. هذا هو توقيع الدالة المعرفة من المستخدم:<syntaxhighlight lang="php">
string handler ( array $matches )
</syntaxhighlight>سنحتاج غالبًا إلى دالة <code>callback</code> لاستخدام الدالة <code>preg_replace_callback()‎‎</code> في مكان واحد فقط. في هذه الحالة، يمكننا استخدام [[PHP/anonymous functions|دالة مجهولة]] لتعريف الدالة المُعرَّفة من المستخدم داخل استدعاء <code>preg_replace_callback()‎‎</code>. بهذه الطريقة يتوفر لدينا كافة المعلومات الخاصة بالاستدعاء في مكان واحد، ولا تسبب الفوضى في أسماء الدوال باستخدام اسم دالة مُعرَّفة من المستخدم تكون غير متواجدة في أي مكان آخر.

المثال 1: مثال على الدالة <code>preg_replace_callback()‎‎</code> ووظيفة مجهولة<syntaxhighlight lang="php">
<?php
/* مُرشِح من سطر الأوامر بأسلوب يونيكس لتحويل الحروف الكبيرة
* في بداية الفقرات إلى حروف صغيرة */
$fp = fopen("php://stdin", "r") or die("can't read stdin");
while (!feof($fp)) {
   $line = fgets($fp);
   $line = preg_replace_callback(
       '|<p>\s*\w|',
       function ($matches) {
           return strtolower($matches[0]);
       },
       $line
   );
   echo $line;
}
fclose($fp);
?>
</syntaxhighlight>

=== <code>subject</code> ===
السلسلة النصية، أو مصفوفة من السلاسل النصية المراد البحث والاستبدال فيها.

=== <code>limit</code> ===
أقصى عدد بدائل ممكنة من كل نمط متواجد في كل سلسلة <code>subject</code>. قيمته الافتراضية ‎-1 (بلا حدود).

=== <code>count</code> ===
إذا حُدِد  تصبح قيمة هذا المتغير تساوي عدد عمليات الاستبدال.

== القيم المعادة ==
تُعيد هذه الدالة مصفوفةً إذا كانت المعامل <code>subject</code> يمثل مصفوفة، أو تُعيد سلسلةً نصية خلاف ذلك. في حالة وجود خطأ تكون القيمة المعادة هي <code>NULL</code>.

إذا عُثِرَ على تطابقات، تُعاد السلسلة النصية الهدف االجديدة، وإلا تُعاد السلسلة الهدف الأصلية <code>subject</code> دون تغيير.

== سجل التغييرات ==
{| class="wikitable"
!الإصدار
!وصف
|-
|5.1.0
|إضافة المعامل count
|}

== أمثلة ==
المثال 2: مثال على الدالة <code>preg_replace_callback()‎‎</code><syntaxhighlight lang="php">
<?php
// اُستُخدِم هذا النص في عام 2002
// نريد أن نحصل على هذا التحديث لعام 2003
$text = "April fools day is 04/01/2002\n";
$text.= "Last christmas was 12/24/2001\n";
// the callback function
function next_year($matches)
{
  // كالعادة: $ match [0] هي المطابقة الكاملة
 // مع $ match [1] التطابق مع أول نمط فرعي
 // مُحاط بالأقواس '(...)' وهلم جرا
 return $matches[1].($matches[2]+1);
}
echo preg_replace_callback(
           "|(\d{2}/\d{2}/)(\d{4})|",
           "next_year",
           $text);
?>
</syntaxhighlight>سوف تكون مُخرجات المثال أعلاه كالتالي:<syntaxhighlight lang="php">
April fools day is 04/01/2003
Last christmas was 12/24/2002
</syntaxhighlight>المثال 3: مثال على الدالة <code>preg_replace_callback()‎‎</code> باستخدام بنية متكررة لمعالجة رمز BB المغلف<syntaxhighlight lang="php">
<?php
$input = "plain [indent] deep [indent] deeper [/indent] deep [/indent] plain";

function parseTagsRecursive($input)
{

    $regex = '#\[indent]((?:[^[]|\[(?!/?indent])|(?R))+)\[/indent]#';

    if (is_array($input)) {
        $input = '<div style="margin-left: 10px">'.$input[1].'</div>';
    }

    return preg_replace_callback($regex, 'parseTagsRecursive', $input);
}

$output = parseTagsRecursive($input);

echo $output;
?>
</syntaxhighlight>

== انظر أيضًا ==
* [[PHP/pcre pattern|أنماط PCRE]].
* الدالة <code>[[PHP/preg replace callback array|preg_replace_callback_array()‎‎]]</code>: إجراء بحث عن تعبير نمطي واستبداله باستخدام دالة مُعرّفة من المستخدم.
* الدالة <code>[[PHP/preg quote|preg_quote()‎‎]]</code>: اقتباس حروف التعبير النمطي.
* الدالة <code>[[PHP/preg replace|preg_replace()‎‎]]</code> البحث عن تعبير نمطي واستبداله.
* الدالة <code>[[PHP/preg last error|preg_last_error()‎‎]]</code>: إعادة رمز الخطأ الخاص بتنفيذ آخر PCRE regex.
* [[PHP/anonymous functions|وظائف مجهولة]].
* معلومات حول النوع [[PHP/Types/callable|callback]].

== مصادر ==
<span> </span>[http://php.net/manual/en/function.preg-replace-callback.php صفحة الدالة preg_replace_callback‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎ في توثيق PHP الرسمي].
[[تصنيف:PHP]]
[[تصنيف:PHP Function]]
[[تصنيف:PHP PCRE]]
[[تصنيف:PHP Regular Expressions]]