الدالة strpos() في PHP: إيجاد موضع نص جزئي

تعيد strpos($haystack, $needle) موضع أول $needle داخل $haystack، معدودًا من 0، أو false إذا لم يكن موجودًا. اختبر النتيجة دائمًا بـ !== false، لأن التطابق في البداية يعيد 0.

<?php
$text = 'apple, banana, cherry';

var_dump(strpos($text, 'banana'));   // found at position 7
var_dump(strpos($text, 'apple'));    // found at position 0
var_dump(strpos($text, 'grape'));    // not found

if (strpos($text, 'apple') !== false) {
    echo "Found apple\n";
}

إذا لم تكن تحتاج إلا إلى إجابة بنعم أو لا في PHP 8، فإن str_contains() أوضح. واستخدم strpos() عندما يهم الموضع.

الصيغة

strpos(string $haystack, string $needle, int $offset = 0): int|false

البحث حساس لحالة الأحرف. وتخبرها $offset من أين تبدأ البحث؛ والإزاحة السالبة تُعدّ من نهاية النص.

فخ !== false

القيمتان 0 وfalse متساويتان في المقارنة المرنة (==). لذا يُعامل التطابق في الموضع 0 على أنه «غير موجود» في أي فحص غير صارم.

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

// Wrong: position 0 is falsy, so this says "no"
if (strpos($url, 'https')) {
    echo "wrong check: has https\n";
} else {
    echo "wrong check: no https\n";
}

// Right: compare strictly with false
if (strpos($url, 'https') !== false) {
    echo "right check: has https\n";
}

تنطبق القاعدة نفسها على stripos() وstrrpos() وarray_search()، التي قد تعيد كلها 0 لتطابق حقيقي.

البحث دون حساسية لحالة الأحرف بـ stripos

تأخذ stripos() الوسائط نفسها وتتجاهل حالة حروف ASCII.

<?php
$title = 'Learning PHP the Hard Way';

var_dump(strpos($title, 'php'));    // case-sensitive: not found
var_dump(stripos($title, 'php'));   // found at 9

إيجاد آخر ظهور بـ strrpos

تعيد strrpos() موضع آخر تطابق. وهي الطريقة المعتادة للحصول على امتداد ملف أو آخر جزء من مسار.

<?php
$file = 'archive.backup.tar.gz';

$dot = strrpos($file, '.');
echo substr($file, $dot + 1), "\n";      // gz
echo substr($file, 0, $dot), "\n";       // archive.backup.tar

$path = '/var/www/html/index.php';
echo substr($path, strrpos($path, '/') + 1), "\n";

لأسماء الملفات تحديدًا، تفعل pathinfo($file, PATHINFO_EXTENSION) ذلك نيابة عنك. وقطع النص عند الموضع مشروح في صفحة substr().

بدء البحث من إزاحة

يتخطى الوسيط الثالث بداية النص. والإزاحة السالبة تبدأ قبل النهاية بذلك العدد من المحارف.

<?php
$s = 'one two one two';

var_dump(strpos($s, 'one'));        // 0
var_dump(strpos($s, 'one', 1));     // skip position 0: finds the second one
var_dump(strpos($s, 'two', -3));    // search only the last 3 characters

إيجاد كل مرات الظهور

تجد strpos() تطابقًا واحدًا. استخدم حلقة وحرّك الإزاحة بعد كل تطابق لتجدها كلها:

<?php
$text = 'the cat sat on the mat with the hat';
$needle = 'the';

$positions = [];
$offset = 0;
while (($pos = strpos($text, $needle, $offset)) !== false) {
    $positions[] = $pos;
    $offset = $pos + strlen($needle);
}

print_r($positions);
echo count($positions), " matches\n";

العدد فقط؟ substr_count($text, 'the') أقصر. وللأنماط، تعيد preg_match_all() مع PREG_OFFSET_CAPTURE كل تطابق مع موضعه.

النصوص اليابانية: موضع البايت مقابل موضع المحرف

تجد strpos() النص متعدد البايتات بشكل صحيح، لكن العدد الذي تعيده بالبايتات. يأخذ كل محرف من الكانا والكانجي الشائع 3 بايتات في UTF-8، لذا يكون موضع البايت في نص ياباني خالص ثلاثة أضعاف موضع المحرف، وفي النص المختلط يتباعد الاثنان بطرق أقل وضوحًا. تعيد mb_strpos() المحارف، وهذا ما تتوقعه mb_substr().

<?php
$s = '東京都渋谷区';

var_dump(strpos($s, '渋谷'));      // byte position
var_dump(mb_strpos($s, '渋谷'));   // character position

echo mb_substr($s, mb_strpos($s, '渋谷')), "\n";

الخلط بينهما خطأ كلاسيكي: تمرير نتيجة strpos() إلى mb_substr() يبدأ من موضع أبعد مما يجب في النص. استخدم strpos مع substr، وmb_strpos مع mb_substr.