الدالة substr() في PHP: اقتطاع جزء من نص

تعيد substr($string, $offset, $length) جزء $string الذي يبدأ عند الموضع $offset (يُعدّ من 0) وطوله $length محرفًا. تعيد substr('Hello world', 0, 5) النص "Hello". احذف $length لتحصل على كل شيء حتى النهاية.

<?php
$s = 'Hello world';

echo substr($s, 0, 5), "\n";   // from the start, 5 characters
echo substr($s, 6), "\n";      // from position 6 to the end
echo substr($s, 4, 3), "\n";   // 3 characters from position 4

تعدّ substr() البايتات. وهذا مثل عدّ المحارف في النص الإنجليزي، لكن ليس في اليابانية أو الصينية أو الرموز التعبيرية أو الحروف ذات العلامات. لهذه استخدم mb_substr()، المعروضة أدناه.

الصيغة

substr(string $string, int $offset, ?int $length = null): string

• $offset هو مكان البدء. 0 هو المحرف الأول. والقيمة السالبة تُعدّ من النهاية.
• $length هو عدد البايتات المأخوذة (البايت الواحد محرف واحد في نص ASCII العادي). والقيمة السالبة تترك ذلك العدد من النهاية. وnull (أو حذفه) تعني «حتى النهاية».

الإزاحة والطول السالبان: العمل من النهاية

تبدأ $offset السالبة العد من نهاية النص، لذا فإن -1 هو المحرف الأخير. وتتوقف $length السالبة قبل النهاية بذلك العدد من المحارف.

<?php
$file = 'report-2026.pdf';

echo substr($file, -3), "\n";       // last 3 characters
echo substr($file, -8, 4), "\n";    // 4 characters, starting 8 from the end
echo substr($file, 0, -4), "\n";    // everything except the last 4
echo substr($file, 7, -4), "\n";    // from position 7, minus the last 4

substr($s, 0, -1) هي الطريقة المعتادة لحذف المحرف الأخير، مثل فاصلة ختامية تركتها حلقة.

الحصول على المحرف الأول أو الأخير

لبايت واحد يمكنك أيضًا الوصول إلى النص بالفهرس مباشرة. $s[0] هو المحرف الأول، ومنذ PHP 7.1 يكون $s[-1] هو الأخير.

<?php
$word = 'banana';

echo substr($word, 0, 1), ' ', $word[0], "\n";    // first character
echo substr($word, -1), ' ', $word[-1], "\n";     // last character
echo substr($word, 1), "\n";                     // drop the first character

الوصول بالفهرس إلى موضع غير موجود يطبع تحذيرًا، بينما تعيد substr() نصًا فارغًا فقط. إذا كان النص قد يكون فارغًا، ففضّل substr().

خارج النطاق: نص فارغ لا false

إذا كانت $offset بعد نهاية النص، تعيد substr() القيمة "" في PHP 8. وفي PHP 7 كانت تعيد false، لذا لم تعد الشيفرات القديمة التي تفحص === false تعمل.

<?php
var_dump(substr('abc', 5));       // start past the end
var_dump(substr('abc', 1, 100));  // length longer than the rest is fine
var_dump(substr('abc', -10));     // negative offset before the start: from 0

النصوص اليابانية: استخدم mb_substr

يخزّن UTF-8 كل محرف من الكانا والكانجي الشائع في 3 بايتات (ويأخذ الكانجي النادر مثل 𠮷 والرموز التعبيرية 4). تعدّ substr() البايتات، لذا تعيد substr('こんにちは', 0, 3) المحرف こ وحده، والطول الذي لا يقع على حد محرف يقطع محرفًا إلى نصفين وينتج نصًا تالفًا. تأخذ mb_substr() الوسائط نفسها وتعدّ المحارف.

<?php
$greeting = 'こんにちは世界';

echo substr($greeting, 0, 3), "\n";       // 3 bytes = 1 character
echo mb_substr($greeting, 0, 3), "\n";    // 3 characters
echo mb_substr($greeting, -2), "\n";      // last 2 characters

// Cutting at 4 bytes splits a character: the result is not valid UTF-8
var_dump(mb_check_encoding(substr($greeting, 0, 4), 'UTF-8'));

ينطبق الأمر نفسه على الرموز التعبيرية والحروف ذات العلامات مثل é. ويستخدم عدّ المحارف mb_strlen()؛ راجع strlen() للبايتات مقابل المحارف.

اختصار النص مع علامة حذف

قطع عنوان طويل لقائمة أو بطاقة هو أكثر الاستخدامات الحقيقية لـ substr() شيوعًا. استخدم mb_substr() حتى لا يُقطع عنوان ياباني في منتصف محرف أبدًا، ولا تضف ... إلا عندما تكون قد اختصرت شيئًا فعلًا.

<?php
function excerpt(string $text, int $max): string
{
    if (mb_strlen($text) <= $max) {
        return $text;
    }
    return rtrim(mb_substr($text, 0, $max)) . '...';
}

echo excerpt('Short title', 20), "\n";
echo excerpt('A much longer title that will not fit in the card', 20), "\n";
echo excerpt('東京から大阪までの新幹線の旅', 8), "\n";

تفعل mb_strimwidth($text, 0, $width, '...') الشيء نفسه حسب عرض العرض، حيث يُعدّ المحرف الياباني كامل العرض عمودين والحرف اللاتيني عمودًا واحدًا. وهي تناسب التخطيطات ثابتة العرض.

عدّ نص جزئي بـ substr_count

تعيد substr_count($haystack, $needle) عدد مرات ظهور $needle. وهي حساسة لحالة الأحرف ولا تعدّ التطابقات المتداخلة.

<?php
echo substr_count('banana', 'an'), "\n";
echo substr_count('aaaa', 'aa'), "\n";      // 2, not 3: no overlaps
echo substr_count('Hello hello', 'hello'), "\n";
echo substr_count(strtolower('Hello hello'), 'hello'), "\n";

substr مع strpos: النص قبل محرف أو بعده

اجمع substr() مع strpos() للقطع عند محرف لا تعرف موضعه مسبقًا، مثل @ في عنوان بريد إلكتروني:

<?php
$email = 'ada.lovelace@example.com';
$at = strpos($email, '@');

echo substr($email, 0, $at), "\n";    // before the @
echo substr($email, $at + 1), "\n";   // after the @

// strstr does the same in one call
echo strstr($email, '@', true), "\n";

تحقق من أن strpos() لم تُعد false قبل استخدام نتيجتها: إذا كان المحرف مفقودًا، تُعامل false على أنها 0 دون تحذير، فتعيد substr('nobody', 0, $at) القيمة "" وتعيد substr('nobody', $at + 1) القيمة "obody".