PHP/preg match

(PHP 4, PHP 5, PHP 7)

تُطابق الدالة preg_match()‎‎ تعبيرًا نمطيًا على سلسلة نصية.

الوصف

int preg_match ( string $pattern , string $subject [, array &$matches [, int $flags = 0 [, int$offset = 0 ]]] )

تبحث الدالة في السلسلة النصية subject عن مُطابقة للتعبير النمطي الُمعطى pattern.

المعاملات

pattern

النمط المراد البحث عنه، كسلسلة نصية.

subject

السلسلة النصية المُدخلة.

matches

إذا ضُبِطَت قيمة المعامل matches، فستُملأ تلك المصفوفة بنتائج البحث. إذ ستحتوي ‎‎‎‎$matches[0]‎ على النص الذي يطابق النمط الكامل، وستحتوي ‎‎‎‎$matches[1]‎ على النص الذي يطابق أول نمط فرعي محاط بالأقواس، وهكذا.

flags

يمكن أن تكون قيمة المعامل flags أحد الرايات التالية:

PREG_OFFSET_CAPTURE: إذا مُرِرت هذه الراية، فستُعيد الدالةُ أيضًا إزاحةَ السلسلة النصية المُطابقة باستخدام التعبير النمطي الأساسي والتعبيرات الفرعية المُتضَمَنة فيه لكل متطابقة تحدث. لاحظ أن هذا يغير قيمة matches في مصفوفة حيث كل عنصر فيها هو مصفوفة تتكون من سلسلة متطابقة عند الفهرس 0 وإزاحة السلسلة النصية في subject عند الفهرس 1.

<?php
preg_match('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
print_r($matches);
?>

سوف تكون مُخرجات المثال أعلاه كالتالي:

Array
(
    [0] => Array
        (
            [0] => foobarbaz
            [1] => 0
        )

    [1] => Array
        (
            [0] => foo
            [1] => 0
        )

    [2] => Array
        (
            [0] => bar
            [1] => 3
        )

    [3] => Array
        (
            [0] => baz
            [1] => 6
        )

)

PREG_UNMATCHED_AS_NULL

إذا مُرِرت هذه الراية ، تُعاد الأنماط الفرعية غير المطابقة بالقيمة NULL؛ وتُعاد بخلاف ذلك كسلسلة فارغة.

<?php
preg_match('/(a)(b)*(c)/', 'ac', $matches);
var_dump($matches);
preg_match('/(a)(b)*(c)/', 'ac', $matches, PREG_UNMATCHED_AS_NULL);
var_dump($matches);
?>

سوف تكون مُخرجات المثال أعلاه كالتالي:

array(4) {
  [0]=>
  string(2) "ac"
  [1]=>
  string(1) "a"
  [2]=>
  string(0) ""
  [3]=>
  string(1) "c"
}
array(4) {
  [0]=>
  string(2) "ac"
  [1]=>
  string(1) "a"
  [2]=>
  NULL
  [3]=>
  string(1) "c"
}

offset

يبدأ البحث عادةً من بداية سلسلة الموضوع النصية. يمكن استخدام المعامل الاختياري offset لتحديد المكان البديل الذي تبدأ منه عملية البحث (بالبايت).

ملاحظة: استخدام offset لا يعادل تمرير  substr($subject, $offset)‎‎ إلى preg_match()‎‎ بدلاً من السلسلة النصية subject، لأن النمط pattern يمكن أن يحتوي على بعض الرموز الخاصة مثل ^ أو $ أو ‎?‎<‎‎‎=x)‎). قارن بين هذا المثال:

<?php
$subject = "abcdef";
$pattern = '/^def/';
preg_match($pattern, $subject, $matches, PREG_OFFSET_CAPTURE, 3);
print_r($matches);
?>

سوف تكون مُخرجات المثال أعلاه كالتالي:

Array
(
)

وبين المثال الآتي:

<?php
$subject = "abcdef";
$pattern = '/^def/';
preg_match($pattern, substr($subject,3), $matches, PREG_OFFSET_CAPTURE);
print_r($matches);
?>

الذي سوف ينتج:

Array
(
    [0] => Array
        (
            [0] => def
            [1] => 0
        )

)

بدلاً من ذلك، لتجنب استخدام substr()‎‎، استخدم G\ بدلاً من الرمز ^ ، أو المُعدِّل A بدلاً من ذلك، فكلاهما يعمل مع معامل الإزاحة offset.

القيم المعادة

تُعيد الدالة preg_match()‎‎ القيمة 1 إذا تطابق النمط pattern مع السلسلة النصية subject المُعطاة، أو 0 إذا لم يتطابق، أو FALSE في حالة حدوث خطأ.

تحذير: قد تُعيد هذه الدالة القيمة المنطقية FALSE، ولكن قد تُعيد أيضًا قيمة غير منطقية تُقيّم بنفس القيمة FALSE. يرجى قراءة قسم القيم المنطقية Booleans لمزيد من المعلومات. ويستخدم العامل === لاختبار القيمة المعادة من هذه الدالة.

سجل التغييرات

الإصدار	الوصف
7.2.0	دعم PREG_UNMATCHED_AS_NULL لمعامل flags$.
5.3.6	إعادة FALSE إذا كانت قيمة offset أكبر من طول subject.
5.2.2	قبول الأنماط الفرعية المسماة للصياغة (<name>?) و ('name'?) وكذلك (‎?P<name>‎). وكانت الإصدارات السابقة تقبل (‎?P<name>‎) فقط.

أمثلة

المثال 1: إيجاد سلسلة النصية "php"

يشير الحرف "i" بعد محدد النمط إلى بحث غير حساس لحالة الأحرف:

<?php
if (preg_match("/php/i", "PHP is the web scripting language of choice.")) {
    echo "A match was found.";
} else {
    echo "A match was not found.";
}
?>

المثال 2: البحث عن الكلمة "web" يشير الرمز ‎\b الموجود في النمط إلى حدود الكلمات، لذا لا يمكن مطابقة سوى كلمة "web" المنفصلة، وليس جزء من كلمة مثل "webbing" أو "cobweb":

<?php
if (preg_match("/\bweb\b/i", "PHP is the web scripting language of choice.")) {
    echo "A match was found.";
} else {
    echo "A match was not found.";
}

if (preg_match("/\bweb\b/i", "PHP is the website scripting language of choice.")) {
    echo "A match was found.";
} else {
    echo "A match was not found.";
}
?>

المثال 3: الحصول على اسم النطاق من عنوان URL

<?php
// استخراج اسم المضيف من URL
preg_match('@^(?:http://)?([^/]+)@i',
   "http://www.php.net/index.html", $matches);
$host = $matches[1];
// استخراج آخر قسمين من اسم المضيف
preg_match('/[^.]+\.[^.]+$/', $host, $matches);
echo "domain name is: {$matches[0]}\n";
?>

سوف تكون مُخرجات المثال أعلاه كالتالي:

domain name is: php.net

المثال 4: استخدام الأنماط الفرعية

<?php
$str = 'foobar: 2008';
preg_match('/(?P<name>\w+): (?P<digit>\d+)/', $str, $matches);
/ * يعمل هذا مع إصدار 5.2.2 أيضًا وما يليه، ومع ذلك
* يوصى باستخدام النموذج أعلاه للتوافق مع الإصدارات السابقة * /
// preg_match ('/ (؟<name>\w+): (?<digit>\d+)/', $str, $matches);
print_r($matches);
?>

سوف تكون مُخرجات المثال أعلاه كالتالي:

Array
(
    [0] => foobar: 2008
    [name] => foobar
    [1] => foobar
    [digit] => 2008
    [2] => 2008
)

ملاحظات

نصيحة: لا تستخدم الدالة preg_match()‎‎ إذا كنت تريد فقط التحقق من وجود سلسلة نصية واحدة في سلسلة نصية أخرى. سيكون من الأسرع استخدام الدالة strpos()‎‎ بدلاً من ذلك.

انظر أيضًا

• أنماط PCRE.
• الدالة preg_quote()‎‎: اقتباس حروف التعبير النمطية.
• الدالة preg_match_all()‎‎: إجراء مطابقة شاملة لتعبير نمطي.
• الدالة preg_replace()‎‎: البحث عن تعبير نمطي واستبداله.
• الدالة preg_split()‎‎: تقسيم سلسلة نصية باستخدام التعبير النمطي.
• الدالة preg_last_error()‎‎: إعادة رمز الخطأ الخاص بتنفيذ آخر تعبير نمطي بصيغة PCRE.

مصادر

• صفحة الدالة preg_match‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎ في توثيق PHP الرسمي.