PHP/preg match all

(PHP 4, PHP 5, PHP 7)

تطابق الدالة preg_match_all()‎‎ تعبيرًا نمطيًا بشكل شامل.

الوصف

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

تبحث هذه الدالة في الموضوع subject عن جميع المتطابقات للتعبير النمطي المُعطى pattern وتضعهم في المصفوفة matches بالترتيب المحدد بواسطة flags.

بعد العثور على أول متطابقة، ستستمر عمليات البحث التالية من نهاية المتطابقة الأخيرة.

المعاملات

pattern

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

subject

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

matches

مصفوفة من جميع المتطابقات في مصفوفة متعددة الأبعاد مُرتّبة وفقًا للرايات flags.

flags

يمكن أن تكون مزيجًا من الرايات التالية (لاحظ أنه من غير المنطقي استخدام PREG_PATTERN_ORDER مع PREG_SET_ORDER).

PREG_PATTERN_ORDER

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

<?php
preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
   "<b>example: </b><div align=left>this is a test</div>",
   $out, PREG_PATTERN_ORDER);
echo $out[0][0] . ", " . $out[0][1] . "\n";
echo $out[1][0] . ", " . $out[1][1] . "\n";
?>

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

<b>example: </b>, <div align=left>this is a test</div>
example: , this is a test

لذا، تحتوي المصفوفة ‎$out[0]‎ على مجموعة من السلاسل النصية التي تتطابق مع النمط الكامل، وتحتوي المصفوفة ‎ ‎$out[1]‎على مجموعة من السلاسل النصية المحاطة بالوسوم.

إذا احتوى النمط على نمط فرعي مُسمّى، فستحتوي المصفوفة ‎$matches بشكل إضافي على عناصر للمفاتيح مع اسم النمط الفرعي.

إذا كان النمط يحتوي على نمط فرعي مُسمّى مكرر، يُحتفظ بالنمط الفرعي الموجود في أقصى اليمين في ‎$match[NAME]‎.

<?php
preg_match_all(
   '/(?J)(?<match>foo)|(?<match>bar)/',
   'foo bar',
   $matches,
   PREG_PATTERN_ORDER
);
print_r($matches['match']);
?>

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

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

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

<?php
preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
   "<b>example: </b><div align=\"left\">this is a test</div>",
   $out, PREG_SET_ORDER);
echo $out[0][0] . ", " . $out[0][1] . "\n";
echo $out[1][0] . ", " . $out[1][1] . "\n";
?>

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

<b>example: </b>, example:
<div align="left">this is a test</div>, this is a test

PREG_OFFSET_CAPTURE

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

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

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

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

        )

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

        )

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

        )

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

        )

)

PREG_UNMATCHED_AS_NULL

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

إذا لم يُحدد راية ترتيب، فستُفترض الراية PREG_PATTERN_ORDER.

offset

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

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

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

تُعيد الدالة عدد متطابقات النمط الكاملة (التي قد تكون صفرًا)، أو FALSE في حالة حدوث خطأ.

سجل التغيير

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

أمثلة

المثال 1: استخراج جميع أرقام الهواتف من بعض النصوص.

<?php
preg_match_all("/\(?  (\d{3})?  \)?  (?(1)  [\-\s] ) \d{3}-\d{4}/x",
                "Call 555-1212 or 1-800-555-1212", $phones);
?>

المثال 2: البحث عن وسوم HTML المتوافقة (دقيق) مثال على المرجع الخلفي. وهو يخبر pcre بأنه يجب أن يتطابق مع المجموعة الثانية من الأقواس في التعبير النمطي نفسه، والتي ستكون ([\w]+) في هذه الحالة. الشرطة المائلة العكسية الزائدة مطلوبة لأن السلسلة النصية محاطة بعلامات اقتباس مزدوجة.

<?php
$html = "<b>bold text</b><a href=howdy.html>click me</a>";
preg_match_all("/(<([\w]+)[^>]*>)(.*?)(<\/\\2>)/", $html, $matches, PREG_SET_ORDER);
foreach ($matches as $val) {
   echo "matched: " . $val[0] . "\n";
   echo "part 1: " . $val[1] . "\n";
   echo "part 2: " . $val[2] . "\n";
   echo "part 3: " . $val[3] . "\n";
   echo "part 4: " . $val[4] . "\n\n";
}
?>

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

matched: <b>bold text</b>
part 1: <b>
part 2: b
part 3: bold text
part 4: </b>

matched: <a href=howdy.html>click me</a>
part 1: <a href=howdy.html>
part 2: a
part 3: click me
part 4: </a>

المثال 3: استخدام النمط الفرعي يعمل هذا مع إصدار PHP 5.2.2 (PCRE 7.0)‎ أيضًا وما يليه، ومع ذلك يوصى باستخدام النمط في المثال للتوافق مع الإصدارات السابقة.

<?php
$str = <<<FOO
a: 1
b: 2
c: 3
FOO;
preg_match_all('/(?P<name>\w+): (?P<digit>\d+)/', $str, $matches);
print_r($matches);
?>

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

Array
(
    [0] => Array
        (
            [0] => a: 1
            [1] => b: 2
            [2] => c: 3
        )

    [name] => Array
        (
            [0] => a
            [1] => b
            [2] => c
        )

    [1] => Array
        (
            [0] => a
            [1] => b
            [2] => c
        )

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

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

)

انظر أيضًا

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

مصادر

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