الدالة number_format() في PHP: فاصل الآلاف والمنازل العشرية

تعيد number_format($number, $decimals) العدد نصًا مع فاصل للآلاف وعدد ثابت من المنازل العشرية: تعيد number_format(1234567.891, 2) النص "1,234,567.89". ومع وسيط واحد تقرّب إلى عدد صحيح: number_format(1234567.891) تساوي "1,234,568".

<?php
$amount = 1234567.891;

echo number_format($amount), "\n";            // no decimals
echo number_format($amount, 2), "\n";         // 2 decimals
echo number_format($amount, 2, ',', '.'), "\n"; // European style
echo number_format(0.129, 2), "\n";
echo number_format(-1234.567, 1), "\n";

المعاملات الأربعة

number_format(
    float $num,
    int $decimals = 0,
    ?string $decimal_separator = ".",
    ?string $thousands_separator = ","
): string

الوسيط الثالث هو المحرف بين الجزء الصحيح والمنازل العشرية، والرابع هو المحرف بين مجموعات الأرقام الثلاثية. ويمكن أن يكون أيٌّ منهما أي نص، بما فيه النص الفارغ أو محرف متعدد البايتات. عدّل الفواصل أدناه لترى كل أسلوب:

<?php
$n = 1234567.891;

echo number_format($n, 2, '.', ','), "  US, UK, Japan\n";
echo number_format($n, 2, ',', '.'), "  Germany, Spain, Italy, Brazil\n";
echo number_format($n, 2, ',', ' '), "  France, Russia, Poland\n";
echo number_format($n, 2, '.', "'"), "  Switzerland\n";
echo number_format($n, 2, '.', ''), "  no separator\n";

تستخدم بيانات الإعدادات المحلية (CLDR) مسافة ضيقة غير قابلة للكسر (U+202F) للفرنسية ومسافة غير قابلة للكسر (U+00A0) للروسية، فلا ينقسم العدد أبدًا على سطرين. وفي HTML، مرّر "\u{202F}" أو "\u{00A0}" فاصلًا بدل المسافة العادية.

تنسيق عدد دون فاصل الآلاف

مرّر '' وسيطًا رابعًا. تحصل على عدد عادي بعدد ثابت من المنازل العشرية، وهو الشكل الذي تتوقعه بوابات الدفع وملفات CSV المصدّرة وقيم <input type="number">:

<?php
$prices = [5, 19.9, 1234.5];

foreach ($prices as $p) {
    echo number_format($p, 2, '.', ''), "\n";
}

// Cents as an integer, for APIs that want the smallest unit
echo (int) round(19.9 * 100), "\n";

في السطر الأخير، round() قبل التحويل مهمة: يُخزَّن 19.9 * 100 على شكل 1989.9999999999998، و(int) وحدها ستقتطعه إلى 1989.

كيف تقرّب number_format

تقرّب number_format() النصف بعيدًا عن الصفر، كما تفعل round()، فيصبح 0.5 العدد 1 ويصبح -2.5 العدد -3. وتصحح أيضًا الخطأ الثنائي الضئيل في قيم مثل 2.675، ولهذا قد تختلف عن sprintf('%.2f'):

<?php
foreach ([0.5, 1.5, 2.5, -2.5] as $x) {
    echo $x, " => ", number_format($x), "\n";
}

echo "\n";
echo number_format(2.675, 2), "  number_format\n";
echo sprintf('%.2f', 2.675), "  sprintf\n";
echo round(2.675, 2), "  round\n";

// PHP 8.3: negative decimals round to tens, hundreds, thousands
echo number_format(1234567, -3), "\n";

لا يمكن تخزين 2.675 بدقة في النظام الثنائي؛ فالقيمة المخزنة أقل منها بقليل جدًا. تنسّق sprintf() تلك القيمة المخزنة فتحصل على 2.67، بينما تعاملها number_format() وround() على أنها 2.675 التي كتبتها. إذا احتجت إلى قاعدة تقريب محددة، فاستدعِ round() أو floor() أو ceil() بنفسك أولًا (راجع التقريب والرياضيات) ومرّر النتيجة إلى number_format().

تنسيق المال والعملات الأخرى

لا تعرف number_format() شيئًا عن العملات، لذا تضيف الرمز بنفسك. ضع إشارة السالب قبل الرمز، وتذكّر أن الين لا منازل عشرية له:

<?php
function money(float $amount, string $symbol = '$'): string
{
    $sign = $amount < 0 ? '-' : '';
    return $sign . $symbol . number_format(abs($amount), 2);
}

echo money(1499.5), "\n";
echo money(-20), "\n";
echo money(1234.5, '€'), "\n";

// Japanese yen: no decimals, 円 after the number
echo number_format(1980), "円\n";
echo '¥' . number_format(128000), "\n";

للمخرجات المراعية للإعدادات المحلية مع موضع الرمز الصحيح لكل بلد، يؤدي NumberFormatter من امتداد intl المهمة كلها:

$fmt = new NumberFormatter('de_DE', NumberFormatter::CURRENCY);
echo $fmt->formatCurrency(1234.5, 'EUR'); // 1.234,50 € (a no-break space before €)

يتطلب امتداد intl، وهو غير مثبّت في كل مكان، لذا تكون number_format() مع رمزك الخاص هي الخيار القابل للنقل.

النتيجة نص لا عدد

هذا أشهر خطأ مع number_format(): تنسيق قيمة ثم الحساب بها. "1,234.50" ليس نصًا رقميًا، لذا لا تقرأ PHP إلا 1 قبل الفاصلة:

<?php
echo number_format(1234.5, 2) + 1;

Warning: A non-numeric value encountered in /home/index.php on line 2
2

وتمرير مثل هذا النص مرة أخرى إلى number_format() أسوأ: يرمي TypeError: number_format(): Argument #1 ($num) must be of type int|float, string given. احتفظ بالعدد الخام للحساب ولا تنسّق إلا لحظة الطباعة. وإذا تلقيت نصًا منسقًا من نموذج أو ملف، فاحذف الفواصل أولًا:

<?php
$total = 1234.5;
$display = number_format($total, 2);      // for output only

echo $display, "\n";
echo number_format($total + 100, 2), "\n"; // math on the number, then format

// Turning "1,234.50" back into a float
$input = '1,234.50';
$value = (float) str_replace(',', '', $input);
var_dump($value);

// European input "1.234,50"
$eu = '1.234,50';
$value = (float) str_replace(['.', ','], ['', '.'], $eu);
var_dump($value);

للحشو أو المحاذاة أو إشارة الموجب قبل العدد، استخدم sprintf() بدلًا منها؛ فهي لا تضيف فواصل الآلاف، لكنها تتحكم في العرض والإشارة.