{
    "slug": "php_number_format",
    "term": "number_format() & money_format()",
    "category": "php",
    "difficulty": "beginner",
    "short": "number_format() formats a number with grouped thousands and a specified number of decimal places — the correct way to display prices, statistics, and large integers in PHP. money_format() was deprecated in PHP 7.4 and removed in PHP 8.0.",
    "long": "number_format(float $num, int $decimals, string $decimal_separator, string $thousands_separator) converts a float to a formatted string. The defaults produce English-style formatting (1,234.56), but all separators are configurable for locale-specific output (1.234,56 for German). money_format() was a thin wrapper around the C library strfmon() — locale-dependent, not available on Windows, and removed in PHP 8.0. The modern replacement is NumberFormatter from the Intl extension, which handles currency symbols, locale rules, and sign conventions correctly. For simple price display without Intl, number_format() with explicit separators is safe and predictable.",
    "aliases": [
        "number_format",
        "money_format",
        "PHP number formatting",
        "PHP currency format"
    ],
    "tags": [
        "php-stdlib",
        "formatting",
        "numbers",
        "i18n",
        "currency"
    ],
    "misconception": "number_format() is locale-aware. It is not — it uses whatever separators you pass explicitly. For locale-correct output (currency symbols, right-to-left numbers, Arabic-Indic digits), use NumberFormatter from the Intl extension.",
    "why_it_matters": "Displaying raw floats to users (echo 1234.5) produces output missing thousands separators and trailing zeros — '1234.5' instead of '1,234.50'. number_format() is the one-liner fix. Knowing that money_format() was removed in PHP 8.0 prevents broken upgrades.",
    "common_mistakes": [
        "Using money_format() in code targeting PHP 8+ — it was removed; replace with NumberFormatter::formatCurrency() or number_format() with explicit separators.",
        "Storing number_format() output in a database — it adds commas and periods that break numeric operations; always store raw numbers, format only for display.",
        "Using number_format() for locale-sensitive output without configuring separators — the defaults are English-style regardless of server locale.",
        "Passing a string to number_format() — it silently coerces to float, which can lose precision for large integers; use intl NumberFormatter for arbitrary precision.",
        "Formatting floats for financial calculations — floats have precision errors; use bcmath or integer cents and format only at display time."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "php_sprintf_format",
        "php_mb_string",
        "php_intl_i18n",
        "locale_formatting"
    ],
    "prerequisites": [
        "php_string_functions_modern"
    ],
    "refs": [
        "https://www.php.net/number_format",
        "https://www.php.net/class.numberformatter"
    ],
    "bad_code": "<?php\n// ❌ Raw float output — no thousands separator, inconsistent decimals\n$price = 1234.5;\necho $price;              // '1234.5' — missing separator, missing trailing zero\necho round($price, 2);   // '1234.5' — still no formatting\n\n// ❌ money_format() — removed in PHP 8.0\necho money_format('%.2n', $price); // Fatal error on PHP 8+",
    "good_code": "<?php\n// ✅ number_format() — simple, predictable\n$price = 1234.5;\necho number_format($price, 2);            // '1,234.50'\necho number_format($price, 2, ',', '.');  // '1.234,50' — German style\necho '$' . number_format($price, 2);      // '$1,234.50'\n\n// ✅ NumberFormatter (Intl) — locale-correct currency\n$fmt = new NumberFormatter('en_US', NumberFormatter::CURRENCY);\necho $fmt->formatCurrency(1234.5, 'USD'); // '$1,234.50'\n\n$fmt_de = new NumberFormatter('de_DE', NumberFormatter::CURRENCY);\necho $fmt_de->formatCurrency(1234.5, 'EUR'); // '1.234,50 €'",
    "quick_fix": "Replace echo $price with echo number_format($price, 2) for '1,234.50'. Replace any money_format() calls with NumberFormatter or number_format() with explicit separators.",
    "effort": "low",
    "created": "2026-03-23",
    "updated": "2026-04-18",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/php_number_format",
        "html_url": "https://codeclaritylab.com/glossary/php_number_format",
        "json_url": "https://codeclaritylab.com/glossary/php_number_format.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[number_format() & money_format()](https://codeclaritylab.com/glossary/php_number_format) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/php_number_format"
            }
        }
    }
}