الدالة preg_replace() في PHP
(PHP 4, PHP 5, PHP 7)
تبحث الدالة preg_replace() عن تعبير نمطي وتستبدله.
الوصف
mixed preg_replace ( mixed $pattern , mixed $replacement , mixed $subject [, int $limit = -1 [, int &$count ]] )
تبحث هذه الدالة في الهدف subject عن النمط المطابق pattern وتبدله إلى replacement.
المعاملات
pattern
النمط المراد البحث عنه. ويمكن أن يكون إما سلسلةً نصيةً أو مصفوفةً من السلاسل النصية.
وتتوافر أيضًا العديد من مُعدِّلات PCRE.
replacement
السلسلة النصية البديلة أو مصفوفة السلاسل النصية البديلة. إذا كان هذا المعامل سلسلة نصية ومعامل النمط pattern كان مصفوفة، فستُبدّل جميع الأنماط إلى تلك السلسلة. وإذا كان كلا المُعامِلان pattern و replacement مصفوفتين، فسيُبدّل كل pattern إلى نظيره من replacement. إذا كان هناك عدد أقل من العناصر في مصفوفة replacement عنها في المصفوفة pattern، فسيُبدّل أي pattern إضافي إلى سلسلة نصية فارغة.
قد تحتوي replacement على مراجع بالشكل \\n أو $n، مع كون الأخيرة هي المفضلة. وسيُبدّل كل مرجع مثل هذا بالنص المُلتقَط إلى النمط الفرعي رقم n المُحاط بالقوسين. يمكن أن تكون قيمة n من 0 إلى 99، وتُشير \\0 أو $0 إلى النص المطابق للنمط بأكمله. يُحسب فتح الأقواس من اليسار إلى اليمين (بدءًا من 1) للحصول على رقم النمط الفرعي اللاقط. لاستخدام الخط المائل العكسي في الاستبدال، يجب مضاعفته ("\\\\" PHP string).
عند استخدام نمط استبدال حيث يتبع رقمٌ آخر مباشرة مرجعًا خلفيًا (أي: وضع رقم مباشرةً بعد النمط المطابق)، لا يمكنك استخدام صيغة \\1 المعتادة للمرجع الخلفي. قد تؤدي صيغة \\11، على سبيل المثال، إلى إرباك الدالة preg_replace() لأنها لن تعرف ما إذا كنت تريد المرجعٍ الخلفي \\1 متبوعًا بالرقم 1، أو المرجع الخلفي \\11 متبوعاً بلا شيء. في هذه الحالة، يكون الحل هو استخدام ${1}1. وهذا يُنشِئ مرجعًا خلفيًا معزولًا وهو $1، ويترك (1) كرقم بذاته.
عند استخدام المُعدِّل e المُهمَل (deprecated)، تُهرِّب هذه الدالة بعض الأحرف (وهي ' و " و \ و NULL) داخل السلاسل النصية التي تحل محل المراجع الخلفية. وذلك لضمان عدم ظهور أية أخطاء في بناء الجملة جرَّاء استخدام المرجع الخلفي سواء مع علامات اقتباس مفردة أو مزدوجة مثل 'strlen(\'$1\')+strlen("$2")'. تأكد من أنك على علم ببناء جملة السلسلة النصية في PHP لمعرفة كيف ستظهر السلسلة المُفسَّرة بالضبط.
subject
السلسلة النصية، أو مصفوفة من السلاسل النصية المراد البحث والاستبدال فيها.
إذا كان subject عبارة عن مصفوفة، فسيجري البحث والاستبدال في كل عنصر من المصفوفة الهدف subject، وتكون القيمة المعادة مصفوفة أيضًا.
limit
أقصى عدد بدائل ممكنة من كل نمط متواجد في كل سلسلة subject. قيمته الافتراضية -1 (بلا حدود).
count
إذا حُدِد تصبح قيمة هذا المتغير تساوي عدد عمليات الاستبدال.
القيم المعادة
تُعيد هذه الدالة مصفوفةً إذا كانت المعامل subject يمثل مصفوفة، أو تُعيد سلسلةً نصية خلاف ذلك.
إذا عُثِرَ على تطابقات، تُعاد السلسلة النصية الهدف الجديدة، وإلا فستُعاد السلسلة الهدف الأصلية subject دون تغيير. في حالة وجود خطأ تكون القيمة المعادة هي NULL.
أخطاء واستثناءات
بدءًا من PHP 5.5.0، يُطلق الخطأ من المستوى E_DEPRECATED عند المرور في المُعدِّل "\e". وبدءًا من PHP 7.0.0، يُطلق E_WARNING في هذه الحالة ولا يكون هناك أي تأثير لاستخدام "\e".
سجل التغييرات
| الإصدار | الوصف |
| 7.0.0 | إزالة دعم المُعدِّل /e. واستخدم الدالة preg_replace_callback() بدلاً من ذلك.
|
| 5.5.0 | إيقاف المُعدِّل /e. واستخدم preg_replace_callback() بدلاً من ذلك. راجع وثائق PREG_REPLACE_EVAL للحصول على معلومات إضافية حول مخاطر الأمان.
|
| 5.1.0 | إضافة المعامل count |
أمثلة
المثال 1: استخدام المراجع الخلفية متبوعة بأرقام
<?php
$string = 'April 15, 2003';
$pattern = '/(\w+) (\d+), (\d+)/i';
$replacement = '${1}1,$3';
echo preg_replace($pattern, $replacement, $string);
?>
سوف تكون مُخرجات المثال أعلاه كالتالي:
April1,2003
المثال 2: استخدام المصفوفات المفهرسة مع الدالة preg_replace()
<?php
$string = 'The quick brown fox jumps over the lazy dog.';
$patterns = array();
$patterns[0] = '/quick/';
$patterns[1] = '/brown/';
$patterns[2] = '/fox/';
$replacements = array();
$replacements[2] = 'bear';
$replacements[1] = 'black';
$replacements[0] = 'slow';
echo preg_replace($patterns, $replacements, $string);
?>
سوف تكون مُخرجات المثال أعلاه كالتالي:
The bear black slow jumps over the lazy dog.
من خلال ترتيب مفاتيح المصفوفتين $patterns و $replacements باستخدام الدالة ksort()، فيجب أن نحصل على ما كنا نريد.
<?php
ksort($patterns);
ksort($replacements);
echo preg_replace($patterns, $replacements, $string);
?>
سوف تكون مُخرجات المثال أعلاه كالتالي:
The slow black bear jumps over the lazy dog.
المثال 3: استبدال عدة قيم
<?php
$patterns = array ('/(19|20)(\d{2})-(\d{1,2})-(\d{1,2})/',
'/^\s*{(\w+)}\s*=/');
$replace = array ('\3/\4/\1\2', '$\1 =');
echo preg_replace($patterns, $replace, '{startDate} = 1999-5-27');
?>
سوف تكون مُخرجات المثال أعلاه كالتالي:
$startDate = 5/27/1999
المثال 4: إزالة المسافات البيضاء يزيل هذا المثال المسافات البيضاء الزائدة من سلسلة نصية.
<?php
$str = 'foo o';
$str = preg_replace('/\s\s+/', ' ', $str);
// foo o
echo $str;
?>
المثال 5: استخدام المعامل count
<?php
$count = 0;
echo preg_replace(array('/\d/', '/\s/'), '*', 'xp 4 to', -1 , $count);
echo $count; //3
?>
سوف تكون مُخرجات المثال أعلاه كالتالي:
xp***to
3
ملاحظات
ملاحظة:
عند استخدام المصفوفات مع pattern و replacement، تُعالَج المفاتيح بالترتيب الذي تظهر به في المصفوفة. وهو ليس بالضرورة نفس ترتيب الفهرس الرقمي. إذا استُخدِمت الفهارس لتحديد أي pattern الذي يجب استبداله بأي replacement، فيجب استدعاء ksort() على كل مصفوفة قبل استدعاء الدالة preg_replace().
انظر أيضًا
- أنماط PCRE.
- الدالة
preg_quote(): اقتباس حروف التعبير النمطي. - الدالة
preg_filter(): البحث عن تعبير نمطي واستبداله. - الدالة
preg_match(): مطابقة تعبير نمطي. - الدالة
preg_replace_callback(): البحث عن تعبير نمطي واستبداله باستخدام دالة مُعرّفة من المستخدم. - الدالة
preg_split(): تقسيم سلسلة نصية باستخدام التعبير النمطي. - الدالة
preg_last_error(): إعادة رمز الخطأ الخاص بتنفيذ آخر PCRE regex.