numfmt_set_pattern — Funktion · PHP-Referenz

Signatur

numfmt_set_pattern(NumberFormatter $formatter, string $pattern): bool

Beschreibung

numfmt_set_pattern ist die prozedurale Variante von NumberFormatter::setPattern() und weist einem bestehenden NumberFormatter-Objekt ein neues Formatierungsmuster im ICU-Pattern-Syntax zu. Das Muster bestimmt, wie Zahlen formatiert und geparst werden – z. B. die Anzahl der Dezimalstellen, Tausendertrennzeichen, Präfixe und Suffixe.

Typische Anwendungsfälle sind die dynamische Anpassung der Zahlenformatierung, ohne einen neuen Formatter anlegen zu müssen, sowie die Implementierung eigener Ausgabeformate wie Buchhaltungsdarstellungen (#,##0.00;(#,##0.00)) oder Prozentwerte mit festgelegter Dezimalgenauigkeit.

Das Muster folgt der ICU DecimalFormat-Syntax. Dabei steht # für eine optionale Ziffer, 0 für eine Pflichtziffer, . als Dezimaltrennzeichen und , als Trennzeichen-Platzhalter. Das tatsächliche Zeichen für Tausender- und Dezimaltrenner wird durch das Gebietsschema (Locale) des Formatters bestimmt.

Wichtig: Diese Funktion funktioniert nur bei Formattern, die regelbasierte Muster unterstützen, also primär bei NumberFormatter::DECIMAL- und NumberFormatter::CURRENCY-Stilen. Bei anderen Stilen wie NumberFormatter::SPELLOUT wird false zurückgegeben.

Parameter

Name	Typ	Default	Beschreibung
$formatter Pflicht	NumberFormatter		Das `NumberFormatter`-Objekt, dessen Muster geändert werden soll. Wird typischerweise mit `numfmt_create()` erstellt.
$pattern Pflicht	string		Das neue Formatierungsmuster in ICU DecimalFormat-Syntax, z. B. `'#,##0.00'` oder `'#,##0.###'`.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn das Muster erfolgreich gesetzt wurde. Bei einem ungültigen Muster oder einem nicht kompatiblen Formatter-Typ wird false zurückgegeben.

Beispiele

Dezimalstellen dynamisch begrenzen

<?php
$formatter = numfmt_create('de_DE', NumberFormatter::DECIMAL);

// Standardausgabe
echo numfmt_format($formatter, 1234567.891) . "\n";

// Neues Muster: genau 2 Dezimalstellen, Tausendertrenner
numfmt_set_pattern($formatter, '#,##0.00');
echo numfmt_format($formatter, 1234567.891) . "\n";

// Muster ohne Tausendertrenner
numfmt_set_pattern($formatter, '0.###');
echo numfmt_format($formatter, 1234567.891) . "\n";

1.234.567,891 1.234.567,89 1234567,891

Buchhaltungsformat mit negativer Klammer-Darstellung

<?php
$formatter = numfmt_create('en_US', NumberFormatter::DECIMAL);

// Buchhaltungs-Pattern: positive Zahlen normal, negative in Klammern
$pattern = '#,##0.00;(#,##0.00)';

if (numfmt_set_pattern($formatter, $pattern)) {
    echo numfmt_format($formatter, 9876.50) . "\n";
    echo numfmt_format($formatter, -9876.50) . "\n";
} else {
    echo 'Fehler beim Setzen des Musters: ' . numfmt_get_error_message($formatter) . "\n";
}

9,876.50 (9,876.50)

// Wichtig · Fallstricke

Muster-Fehler: Ein syntaktisch ungültiges ICU-Pattern führt zu false als Rückgabewert. Mit numfmt_get_error_message() und numfmt_get_error_code() lässt sich der genaue Fehler ermitteln.

Nicht alle Formatter-Typen unterstützen Muster: Regelbasierte Formatter wie NumberFormatter::SPELLOUT oder NumberFormatter::ORDINAL verwenden intern keine DecimalFormat-Patterns – numfmt_set_pattern schlägt dort fehl.

Locale-Abhängigkeit: Das Muster selbst verwendet immer ASCII-Zeichen (Punkt als Dezimaltrenner, Komma als Gruppentrennzeichen), unabhängig vom Locale. Die tatsächliche Ausgabe richtet sich jedoch nach den Locale-Einstellungen des Formatters.

Siehe auch

numfmt_create numfmt_get_pattern numfmt_format numfmt_get_error_message NumberFormatter