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";

נתוני locale (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";

לפלט שמותאם ל-locale עם המיקום הנכון של הסמל לכל מדינה, 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(); היא לא מוסיפה מפרידי אלפים, אבל היא שולטת ברוחב ובסימן.