الدالة str_contains() في PHP: هل يحتوي النص على نص آخر؟

تعيد str_contains($haystack, $needle) القيمة true إذا ظهر $needle في أي مكان من $haystack، وfalse في غير ذلك. أُضيفت في PHP 8.0 وهي حساسة لحالة الأحرف.

<?php
$sentence = 'The quick brown fox';

var_dump(str_contains($sentence, 'quick'));   // true
var_dump(str_contains($sentence, 'Quick'));   // false: case-sensitive
var_dump(str_contains($sentence, 'dog'));     // false

if (str_contains($sentence, 'fox')) {
    echo "Found a fox\n";
}

على عكس strpos()، تعيد قيمة منطقية حقيقية، فلا يوجد فخ «الوجود في الموضع 0 يبدو مثل false».

الصيغة

str_contains(string $haystack, string $needle): bool
str_starts_with(string $haystack, string $needle): bool
str_ends_with(string $haystack, string $needle): bool

أُضيفت الثلاث في PHP 8.0 وتعمل بايتًا بايتًا، لذا تتعامل مع النصوص اليابانية ونصوص UTF-8 الأخرى بشكل صحيح دون نسخة mb_.

فحص البداية أو النهاية بـ str_starts_with وstr_ends_with

<?php
$url = 'https://example.com/report.pdf';

var_dump(str_starts_with($url, 'https://'));   // true
var_dump(str_ends_with($url, '.pdf'));         // true
var_dump(str_ends_with($url, '.PDF'));         // false

$name = '株式会社コディ';
var_dump(str_starts_with($name, '株式会社'));   // true

الاحتواء دون حساسية لحالة الأحرف

لا توجد str_icontains(). حوّل النصين إلى أحرف صغيرة أولًا. وتحوّل mb_strtolower() أيضًا الحروف خارج ASCII، مثل É أو الكيريلية، التي تتركها strtolower() كما هي.

<?php
function containsIgnoreCase(string $haystack, string $needle): bool
{
    return str_contains(mb_strtolower($haystack), mb_strtolower($needle));
}

var_dump(containsIgnoreCase('Learning PHP', 'php'));       // true
var_dump(containsIgnoreCase('ÉCOLE DE CODE', 'école'));    // true

// The same check with stripos (ASCII letters only)
var_dump(stripos('Learning PHP', 'php') !== false);        // true

النص المبحوث عنه الفارغ يعيد true

يوجد النص الفارغ في كل نص، بما فيه النص الفارغ. وهذا مهم عندما يأتي النص المبحوث عنه من مربع بحث تركه المستخدم فارغًا.

<?php
var_dump(str_contains('abc', ''));    // true
var_dump(str_contains('', ''));       // true

$search = '';   // a blank search field
$title = 'PHP str_contains';
$matches = $search !== '' && str_contains($title, $search);
var_dump($matches);

التحقق من أن نصًا يحتوي أيًّا من عدة كلمات أو كلها

تأخذ str_contains() نصًا مبحوثًا عنه واحدًا. مرّ على مصفوفة منها: أعِد النتيجة حالما يتطابق أحدها في حالة «أي منها»، أو حالما يفشل أحدها في حالة «كلها».

<?php
function containsAny(string $haystack, array $needles): bool
{
    foreach ($needles as $needle) {
        if (str_contains($haystack, $needle)) {
            return true;
        }
    }
    return false;
}

function containsAll(string $haystack, array $needles): bool
{
    foreach ($needles as $needle) {
        if (!str_contains($haystack, $needle)) {
            return false;
        }
    }
    return true;
}

$comment = 'Buy cheap watches now';

var_dump(containsAny($comment, ['cheap', 'free', 'winner']));   // true
var_dump(containsAll($comment, ['cheap', 'free']));             // false

للتحقق من أن قيمة هي أحد عناصر مصفوفة، لا جزءًا من نص، استخدم in_array().

قبل PHP 8: strpos !== false

الشيفرة التي يجب أن تعمل على PHP 7 تستخدم strpos() مع مقارنة صارمة. وتعطي الإجابة نفسها التي تعطيها str_contains()، إلا مع النص المبحوث عنه الفارغ: كانت strpos() في PHP 7 تطبع Warning: strpos(): Empty needle وتعيد false.

<?php
$haystack = 'php is fun';

var_dump(str_contains($haystack, 'php'));       // PHP 8
var_dump(strpos($haystack, 'php') !== false);   // PHP 7 and later

// The bug to avoid: position 0 is falsy
var_dump((bool) strpos($haystack, 'php'));

يطبع السطر الأخير bool(false) مع أن النص موجود، لأن php تقع في الموضع 0. واستبدال مثل هذه الفحوص بـ str_contains() من أسهل الترقيات إلى PHP 8.