Signatur
Beschreibung
ResourceBundle ist eine PHP-Klasse, die auf die ICU-Ressourcenbündel-Infrastruktur aufsetzt. ICU-Ressourcenbündel sind kompilierte Binärdateien (.res), die lokalisierte Daten wie Zeichenketten, Zahlen, Arrays und verschachtelte Tabellen für verschiedene Locales enthalten. Die Klasse erlaubt es, solche Bundles zu laden und gezielt Werte abzurufen.
Typische Anwendungsfälle sind Anwendungen, die echte Unicode-konforme Lokalisierung benötigen, z. B. Datumsformate, Währungsbezeichnungen, länderspezifische Sortierregeln oder eigene Übersetzungsdaten. Im Gegensatz zu einfachen .ini- oder .php-Array-Dateien sind ICU-Bundles für sehr große und komplexe Lokalisierungsszenarien ausgelegt.
Ein ResourceBundle-Objekt kann über den Konstruktor oder die statische Methode ResourceBundle::create() instanziiert werden. Der Zugriff auf einzelne Einträge erfolgt per get()-Methode oder über den Array-Zugriffsoperator. Verschachtelte Bundles werden als weitere ResourceBundle-Objekte zurückgegeben. Das Bundle unterstützt außerdem Iteration über alle enthaltenen Schlüssel.
Für die Nutzung dieser Klasse muss die PHP-Erweiterung intl aktiviert sein. Die ICU-Ressourcendateien werden in der Regel mit dem ICU-Tool genrb aus Textdateien (.txt) kompiliert.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $locale Pflicht | string|null | Das Locale, für das das Bundle geladen werden soll, z. B. 'de_DE'. Bei null wird das Standard-Locale verwendet. Ein leerer String '' lädt das Root-Bundle. |
|
| $bundle Pflicht | string|null | Pfad zum Verzeichnis, in dem die .res-Dateien liegen, oder der Name eines ICU-Datenpaketes. Bei null werden die eingebauten ICU-Daten verwendet. |
|
| $fallback | bool | true | Gibt an, ob bei fehlendem Locale automatisch auf übergeordnete Locales oder das Root-Bundle zurückgefallen werden soll. Standard ist true. |
Rückgabewert
Beispiele
Grundlegende Verwendung: Wert aus einem ICU-Bundle lesen
<?php
// Voraussetzung: Im Verzeichnis /var/bundles/ existiert eine kompilierte
// Datei de.res (erzeugt mit 'genrb') mit dem Inhalt:
// root { greeting { "Hallo" } }
// de { greeting { "Guten Tag" } }
$bundle = new ResourceBundle('de', '/var/bundles/');
if ($bundle === null) {
echo 'Bundle konnte nicht geladen werden.';
} else {
$greeting = $bundle->get('greeting');
echo $greeting; // Ausgabe: Guten Tag
}
Iteration über alle Schlüssel eines Bundles
<?php
// Eingebaute ICU-Daten für Sprachnamen (CLDR) verwenden
$bundle = new ResourceBundle('de', 'ICUDATA-lang');
if ($bundle !== null) {
// Gibt die ersten 5 Sprachbezeichnungen auf Deutsch aus
$count = 0;
foreach ($bundle as $key => $value) {
if (is_string($value)) {
echo $key . ': ' . $value . PHP_EOL;
}
if (++$count >= 5) break;
}
echo 'Gesamtanzahl Einträge: ' . count($bundle) . PHP_EOL;
}
Verschachteltes Bundle und statische create()-Methode
<?php
// Statische Fabrikmethode als Alternative zum Konstruktor
$bundle = ResourceBundle::create('en_US', 'ICUDATA');
if ($bundle !== null) {
// Auf verschachteltes Subbundle zugreifen
$sub = $bundle->get('Layout');
if ($sub instanceof ResourceBundle) {
echo 'Subbundle enthält ' . count($sub) . ' Einträge.' . PHP_EOL;
}
// Fehlercode nach einer fehlgeschlagenen Operation prüfen
echo 'Letzter Fehlercode: ' . $bundle->getErrorCode() . PHP_EOL;
echo 'Letzte Fehlermeldung: ' . $bundle->getErrorMessage() . PHP_EOL;
}
Verfügbare Locales eines Bundles auflisten
<?php
// Alle Locales ermitteln, für die ein Bundle existiert
$locales = ResourceBundle::getLocales('');
foreach (array_slice($locales, 0, 10) as $locale) {
echo $locale . PHP_EOL;
}
// Wichtig · Fallstricke
Erweiterung erforderlich: ResourceBundle setzt die PHP-Erweiterung intl voraus. Ohne sie ist die Klasse nicht verfügbar. Prüfe die Verfügbarkeit mit extension_loaded('intl').
Fehlerbehandlung: Bei einem Fehler beim Laden gibt der Konstruktor kein null zurück, sondern ein Objekt, bei dem getErrorCode() einen Fehlercode ungleich U_ZERO_ERROR liefert. Prüfe nach der Instanziierung stets den Fehlercode. ResourceBundle::create() gibt hingegen null zurück, wenn das Bundle nicht geladen werden kann.
Kompilierte Dateien: Die .res-Dateien müssen mit dem ICU-Tool genrb aus Textdateien erzeugt werden. Rohe .txt-Dateien können nicht direkt geladen werden.
Fallback-Verhalten: Wenn fallback auf true gesetzt ist und ein Schlüssel im angeforderten Locale fehlt, wird automatisch auf das übergeordnete Locale (z. B. von de_DE auf de) und zuletzt auf das Root-Bundle zurückgegriffen. Mit false wird dieses Verhalten deaktiviert.