Zum Hauptinhalt springen
Schneespur
Dokumentation durchblättern

Module entwickeln

Formate & Einheiten

Wie ein Modul Zahlen, Geld, Datum und Messwerte anzeigt, ohne der installationsweiten Einstellung zu widersprechen — kanonisch speichern, beim Anzeigen formatieren.

Seit 1.2.0. Währung, Zahlenformat, Datum, Uhrzeit, Temperatur, Geschwindigkeit, Entfernung und Gewicht folgen einer einzigen Einstellung, die für die ganze Installation gilt. Ein Modul, das einen Wert selbst formatiert, hebelt damit die Entscheidung des Betreibers aus — auf einer amerikanischen Installation steht dann auf Ihrem Bildschirm Kilogramm und auf jedem anderen Pfund.

Die Regel dahinter passt in einen Satz: kanonisch speichern, beim Anzeigen formatieren.

Das klingt selbstverständlich, ist es in der Praxis aber nicht. Die Versuchung ist groß, eine Zahl gleich beim Speichern „richtig“ abzulegen — in der Einheit, in der sie später erscheinen soll. Genau das macht eine Umstellung später unmöglich, weil die Datenbank dann nicht mehr weiß, was der Wert eigentlich bedeutet.

Die kanonischen Einheiten

So liegen die Werte in der Datenbank, im Core wie in den Tabellen Ihres Moduls. Sie ändern sich nie, wenn eine Einstellung sich ändert: Ein Wechsel von Celsius auf Fahrenheit schreibt keine einzige Zeile um.

GrößeGespeichert alsSpaltentyp
Geldganzzahlige Centinteger (z. B. price_amount_cents)
TemperaturCelsiusdecimal / float
Geschwindigkeitkm/hdecimal / float
EntfernungMeterdecimal / float
GewichtKilogrammdecimal / float
SchneehöheZentimeterdecimal / float
NiederschlagMillimeterdecimal / float
ZeitstempelUTCtimestamp / datetime

Eine Einstellung umzustellen ist damit eine Umbeschriftung, keine Umrechnung. Das gilt ausdrücklich auch für Geld: Es findet keine Währungsumrechnung statt. Wer currency_code von EUR auf USD stellt, sieht 12345 weiterhin als einhundertdreiundzwanzig Komma fünfundvierzig, nur mit einem anderen Zeichen davor. Ein Betrieb, der tatsächlich die Währung wechselt, muss seine Preise neu festlegen — und das soll er bewusst tun, nicht durch einen Kurs, den eine Software sich irgendwo geholt hat.

Die zwölf Einstellungen

Sie lassen sich auslesen, aber in aller Regel brauchen Sie das nicht: Der Formatter hält sie bereits.

SchlüsselErlaubte Werte
format_regionde at ch us ca gb (dazu, was Module registrieren)
currency_codeISO 4217, z. B. EUR USD CAD GBP CHF
currency_positionbefore after
number_formatdot_comma (1.234,56) · comma_dot (1,234.56) · apostrophe_dot (1’234.56)
date_formatdmy_dot (06.08.2026) · dmy_slash (06/08/2026) · mdy_slash (08/06/2026) · iso (2026-08-06)
time_format24h 12h
unit_distancemetric imperial
unit_temperaturecelsius fahrenheit
unit_weightmetric imperial
address_formatstreet_zip_city (Innstraße 12, 94032 Passau) · street_city_state_zip (400 S 4th St, Minneapolis, MN 55401) · street_city_zip (10 Downing St, London SW1A 2AA) – seit 1.2.1
csv_delimiter; , – seit 1.2.1
week_starts_on1 (Montag) 7 (Sonntag) – seit 1.2.1; als Text gespeichert, von Formatter::weekStartsOn() als int zurückgegeben

Die letzten drei Schlüssel sind in 1.2.1 hinzugekommen. Die Regionsvorlage setzt seither neben dem Adressformat auch das CSV-Trennzeichen und den ersten Wochentag; alle drei lassen sich wie die übrigen regionalen Einstellungen unter Units & Formats einzeln anpassen.

Ist nichts gesetzt, gelten die Werte der de-Vorlage. Bei einer Container-Installation über Docker oder Coolify läuft der Browser-Installer nicht mit; dort füllt eine Migration die Werte aus APP_LOCALE.

Geschwindigkeit hat bewusst keinen eigenen Schlüssel, sie folgt unit_distance. Kein Land misst in Meilen und fährt in km/h — ein eigener Schalter wäre nur eine zusätzliche Möglichkeit, sich zu widersprechen.

Zwei Abrechnungs-Einstellungen (seit 1.2.1)

Streng genommen sind das keine Format-Einstellungen: Sie entscheiden, wie ein Preis berechnet und ob er angezeigt wird. Sie stehen aber auf derselben Seite wie die übrigen Geld-Einstellungen (Admin → Settings → Company & Location → Billing), und ein Modul, das mit Beträgen arbeitet, braucht sie.

SchlüsselErlaubte WerteSo lesen Sie ihn
billing_increment_minutes1 (minutengenau) · 15 · 30 · 60JobPricing::incrementMinutes(): int – nie direkt über Setting::get(). Ein gespeicherter Wert außerhalb dieser vier oder gar keiner wird als 1 gelesen.
report_show_amountsbool, Standard falseNicht auslesen, um zu entscheiden, ob Beträge für einen Kunden gedruckt werden: Fragen Sie PdfReportService::revenueFor(...), das bei ausgeschalteter Einstellung null liefert (siehe Kern-Datenmodell).

Der Takt gilt nur für Preise pro Stunde, und er wird beim Abschluss eines Einsatzes als price_increment_min am Einsatz festgeschrieben. Eine Änderung der Einstellung wirkt sich also auf künftige Einsätze aus, nie auf frühere. report_show_amounts steuert jede Ausgabe des Sammelberichts für Kunden: den Download im Admin-Bereich, den Objektbericht, den Download des Kunden im Portal und das PDF im Anhang der Bericht-E-Mail. Die interne Kundenbericht-Seite und der CSV-Export zeigen Beträge immer.

Der Formatter

Klasse: App\Services\Format\Formatter, in AppServiceProvider als Singleton gebunden.

public const PLACEHOLDER = '—';

date(?DateTimeInterface $moment): string
time(?DateTimeInterface $moment, bool $withSeconds = false): string
dateTime(?DateTimeInterface $moment, bool $withSeconds = false): string

number(?float $value, int $decimals = 1): string
money(?int $cents): string
currencySymbol(): string

temperature(?float $celsius): string
speed(?float $kmh): string
distance(?float $metres): string
weight(?float $kilograms): string
snowDepth(?float $centimetres): string
precipitation(?float $millimetres): string

addressFormat(): string                     // 'street_zip_city' | 'street_city_state_zip' | 'street_city_zip'
addressLines(mixed $source): array          // list<string> – since 1.2.1
address(mixed $source): string              // the lines joined with ", " – since 1.2.1
csvDelimiter(): string                      // ';' or ',' – since 1.2.1
weekStartsOn(): int                         // 1 (Monday) or 7 (Sunday) – since 1.2.1

parseDecimal(string $input): ?float        // die Gegenrichtung — siehe unten
parseMoneyToCents(string $input): ?int

browserSettings(): array                    // die vier Werte, die das Layout an JS reicht

Zwei Eigenheiten, die Ihnen Arbeit ersparen:

Jede Anzeigemethode nimmt null entgegen und gibt dafür PLACEHOLDER zurück. Der alte Dreisatz $x ? format_date($x) : '—' ist damit überflüssig; er verdoppelt nur, was der Dienst ohnehin tut, und bringt die Gefahr mit, an einer Stelle ein anderes Zeichen zu verwenden als an allen anderen.

Die Anzeige-Zeitzone setzt der Formatter selbst, nicht der Aufrufer. Schreiben Sie also kein ->setTimezone(config('app.display_timezone')), bevor Sie einen Wert übergeben. Es passiert innen ohnehin, und zweimal angewendet ist es ein Fehler, der erst auffällt, wenn ein Kunde in einer anderen Zeitzone sitzt.

Adressen setzt seit 1.2.1 nur noch der Formatter zusammen, über addressLines() und address(). $source wird nach seiner Form behandelt, nicht nach seiner Klasse: Ein Model oder Array mit street, zip, city und state genügt. Damit formatiert dieselbe Methode ein CustomerObject ebenso wie die eigene Firmenadresse des Betreibers aus den Einstellungen.

Die Reihenfolge folgt address_format:

  • street_zip_city stellt die Postleitzahl vor den Ort (94032 Passau).
  • street_city_state_zip stellt das Bundesland bzw. den Staat vor die Postleitzahl (Minneapolis, MN 55401). Fehlt der Staat, entfällt nicht nur er, sondern auch das Komma: Ein US-Betrieb, der das Feld leer lässt, bekommt Minneapolis 55401 und nie ein hängendes Minneapolis, 55401.
  • street_city_zip setzt weder Komma noch Staat (London SW1A 2AA).

addressLines() gibt für eine leere Quelle ein leeres Array zurück und nicht den PLACEHOLDER. So entscheidet das @if in Ihrer View, ob überhaupt etwas erscheint. In Blade-Views verwenden Sie format_address() bzw. format_address_lines().

Helfer

In app/helpers.php liegen schmale Wrapper, die überall verfügbar sind — auch in den Blade-Views Ihres Moduls:

format_date($moment)                     format_number($value, $decimals = 1)
format_time($moment, $withSeconds = false)   format_money($cents)
format_datetime($moment, $withSeconds = false)

format_temperature($celsius)   format_speed($kmh)
format_distance($metres)       format_weight($kilograms)
format_snow_depth($centimetres)   format_precipitation($millimetres)

format_address($source)        format_address_lines($source)   // since 1.2.1
{{-- In einer Modul-View --}}
<td>{{ format_datetime($delivery->created_at) }}</td>
<td>{{ format_weight($delivery->grit_kilograms) }}</td>
<td>{{ format_money($delivery->price_cents) }}</td>

Maßstabswechsel

distance() und weight() wählen ihren Maßstab nach der Größenordnung. Sie übergeben also immer den kanonischen Wert und bekommen etwas Lesbares zurück, statt selbst entscheiden zu müssen, ob 2.000 Meter als Meter oder als Kilometer erscheinen sollen:

Aufrufmetrischimperial
distance(850.0)850 m2,789 ft
distance(2000.0)2,0 km1.2 mi
weight(250.0)250 kg551 lb
weight(1500.0)1,5 t1.7 tn
snowDepth(12.0)12,0 cm4.7 in
precipitation(1.2)1,2 mm0.05 in

Imperiales Gewicht rechnet in short tons (2.000 lb), nicht in der britischen long ton.

Schneehöhe und Niederschlag folgen unit_distance — niemand misst die Straße in Meilen und den Schnee darauf in Zentimetern. Der Niederschlag behält in Zoll zwei Nachkommastellen: Ein Millimeter sind 0,04 in, mit nur einer Stelle würde ein echter Regen auf 0.0 abgerundet und damit zu „kein Niederschlag“.

Eingabe: die Gegenrichtung

Ein Formularfeld, das eine Zahl annimmt, muss sie im Format des Betreibers lesen. 1.234,56 und 1,234.56 sind derselbe Betrag, von zwei verschiedenen Menschen getippt — und (float) '1.234,56' ergibt in PHP 1.0.

$cents = app(Formatter::class)->parseMoneyToCents($request->input('price'));

if ($cents === null) {
    // nicht lesbar — ablehnen, niemals 0 speichern
}

parseDecimal() ist streng auf die eingestellten Trennzeichen und rät nicht. 12,34,56 liefert auf einer Installation mit Komma-Dezimaltrennung null statt 123456. Das ist Absicht: Einen Tippfehler stillschweigend als hundertmal zu große Zahl zu lesen, setzt einen falschen Preis in einen Vertrag.

Verwenden Sie auf einem frei getippten Zahlenfeld keine numeric-Validierung — Laravels numeric weist 1.234,56 zurück. Erst parsen, dann den geparsten Wert prüfen.

Einheitenkürzel stehen in den Übersetzungen

°C, km/h, lb und Verwandte kommen aus lang/{locale}/format.php, nie als Literal im Code. So kann ein Sprachpaket sie lokalisieren. Braucht Ihr Modul ein Kürzel, das der Core nicht mitbringt, liefern Sie es in Ihrer eigenen, namensraumbehafteten Übersetzungsdatei aus, statt die Zeichenkette einzubauen.

Der Core setzt das mit tests/Feature/FormatDriftGuardTest.php durch. Der Test lässt den Build scheitern bei einem fest eingebauten €, km/h oder °C, bei einem mm oder cm, das an einen ausgegebenen Wert geklebt oder in eine Übersetzung eingebacken wurde, sowie bei format('d.m.Y…') oder einem nackten format('H:i…') irgendwo unter app/, resources/views/ oder lang/.

Seit 1.2.1 weist der Test außerdem eine von Hand zusammengesetzte Adresse zurück: in Views eine Blade-Ausgabe oder einen JS-Ausdruck, der zip und city aneinanderklebt, und im PHP-Code unter app/ eine Zeichenketten-Verkettung neben einem Zugriff auf ->zip oder ->city. Der Grund ist derselbe wie bei den Einheiten: Eine Adresse, die an einer Stelle selbst gebaut wird, kennt das Regionsformat und das neue Bundesland-Feld nicht.

Ein solcher Wächter lohnt sich auch für Ihr Modul. Die Klasse existiert nämlich nicht aus Prinzipienreiterei: In lang/en/customer_object.php stand über mehrere Releases hinweg Price (€), und es ist niemandem aufgefallen.

Eine Beschriftung, die die Einheit trägt: :unit

Hinzugekommen in 1.2.1. Die Räumschwelle eines Objekts wird seither in der Einheit gespeichert, die die Region verwendet (cm oder in, je nach unit_distance). Ihre Beschriftung kann deshalb keine feste Einheit mehr nennen, und der Core-Schlüssel trägt einen Platzhalter:

// lang/{locale}/customer_object.php
'field_plow_threshold' => 'Plow threshold (:unit)',   // en
'field_plow_threshold' => 'Räumen ab (:unit)',        // de

Gefüllt wird er beim Lesen mit Formatter::snowUnitLabel(), das das übersetzte Kürzel der aktuellen Region liefert:

__('customer_object.field_plow_threshold', ['unit' => app(Formatter::class)->snowUnitLabel()])

Ein Sprachpaket, das customer_object.field_plow_threshold überschreibt, muss den Platzhalter :unit behalten. Wer (cm) hineinschreibt, legt Zentimeter über ein Feld, das Zoll annimmt. Ein Betreiber mit imperialen Einheiten liest dann (cm), tippt einen Wert in Zentimetern, und das Formular speichert ihn mit unit='in'. Der Wert ist ab da falsch, und nichts in der Oberfläche weist darauf hin.

Dasselbe gilt für jeden Core-Schlüssel, dessen Text einen :platzhalter enthält: Eine Überschreibung verliert alles, was sie nicht wiederholt.

Was unangetastet bleibt

Maschinenformate sind keine Anzeige-Entscheidung. Diese hier bleiben genau so, wie sie sind:

  • Y-m-d im Wert von <input type="date"> und Y-m-d\TH:i bei datetime-local — das liest der Browser, kein Mensch
  • Y-m-d_His in erzeugten Dateinamen; ein Schrägstrich aus mdy_slash wäre dort ein Pfadtrenner
  • ISO 8601 in API-Antworten und im DSGVO-Datenexport (Art. 20 verlangt Maschinenlesbarkeit)
  • Datenbankspalten, JSON-Nutzlasten, toISOString() in JS-Datumsauswahlfeldern
  • Breiten- und Längengrad — technische Koordinaten, immer mit Punkt als Dezimaltrenner

Die Browser-Seite

Das Layout reicht an JavaScript genau vier Werte weiter, über Formatter::browserSettings():

window.schneespurFormat        // { timeFormat, dateFormat, numberFormat, timeZone }
window.schneespurFormatTime(date)   // Date → "2:30 PM" / "14:30"
window.schneespurFormatDate(date)   // Date → "08/06/2026" / "06.08.2026"

timeZone ist in 1.2.1 mit der Korrektur der Zeitzone dazugekommen. Die eigene Uhr in format.js liest ihn (settings().timeZone), damit die laufende Schichtuhr in der Fahrer-App der Zeitzone des Betriebs folgt und nicht der des Geräts. Die anderen drei Werte ändern, wie ein Wert aussieht; dieser ändert, welcher Wert es ist. Gehen Sie also nicht davon aus, dass window.schneespurFormat bei drei Schlüsseln aufhört: Ein Modul, das das Objekt ausdrücklich zerlegt und die Zeitzone braucht, sollte timeZone mitnehmen, statt auf die des Browsers zurückzufallen.

Beide Funktionen erwarten ein Date-Objekt und weisen alles andere zurück. Sie geben dann denselben Platzhalter aus, den auch der Server schreibt, und warnen einmal pro Seite statt einmal pro Aufruf. Sichern Sie Ihre eigene Aufrufstelle trotzdem ab: new Date(null) ist nicht etwa ein ungültiges Datum, sondern der 1. Januar 1970. Übergeben Sie also value ? new Date(value) : null.

Hierher gehört ohnehin fast nichts. Was der Server rendern kann, rendert der Server.

RegionRegistry

Ein Sprachpaket kann seine Regionsvorlage gleich mitbringen. Die Einzelheiten stehen bei den Registries.

Checkliste für ein Modul, das Zahlen anzeigt

  • Speichert kanonisch — Cent, Celsius, km/h, Meter, Kilogramm, Zentimeter, Millimeter, UTC
  • Jede Anzeige läuft über einen format_*()-Helfer oder den Formatter
  • Keine Null-Dreisätze darum herum und kein setTimezone() davor
  • Jede vom Betreiber getippte Zahl läuft durch parseDecimal() / parseMoneyToCents()
  • Nirgends im Modul ein €, km/h, °C, d.m.Y oder H:i als Literal
  • Jeder überschriebene Core-Schlüssel behält seine :platzhalter – customer_object.field_plow_threshold trägt :unit
  • Maschinenformate unangetastet