Einstellungen mit eZINI lesen #

Diese Seite richtet sich an PHP-Entwickler, die in ihrem Code Konfiguration lesen. Jede Einstellung in Exponential ist ein INI-Wert, gelesen über eZINI (lib/ezutils/classes/ezini.php), das die Standardwerte des Kernels, die Erweiterungen, den Siteaccess und die Überschreibungen der Installation zu einer Sicht zusammenführt. Die auf Erweiterungen ausgerichtete Referenz ist eZINI; diese Seite konzentriert sich auf die korrekte Verwendung in PHP-Code.

Inhalt #

1. Die Aufrufe
2. Die Schichten
3. Umgebungsvarianten
4. Arrays
5. Standardwerte für fehlende Schlüssel
6. Ihre eigene Einstellungsdatei
7. Einstellungen schreiben
8. Caches und persistente Worker

Die Aufrufe #

$ini = eZINI::instance();                          // site.ini
$ini = eZINI::instance( 'content.ini' );           // another file
$value  = $ini->variable( 'DebugSettings', 'DebugOutput' );      // a string
$has    = $ini->hasVariable( 'DebugSettings', 'DebugOutput' );   // bool
$list   = $ini->variable( 'ExtensionSettings', 'ActiveExtensions' ); // an array for Key[] settings
$parts  = $ini->variableArray( 'SomeBlock', 'SemicolonList' );   // a value split on ';'
$block  = $ini->group( 'DatabaseSettings' );                     // the whole block as an array
$exists = $ini->hasGroup( 'AcmeReportSettings' );

eZINI::instance() gibt ein gemeinsam genutztes Objekt je Datei und Verzeichnis zurück, sodass ein erneuter Aufruf günstig ist.

Die Schichten #

Ein Wert wird in dieser Reihenfolge gelesen; die letzte Schicht, die ihn setzt, gewinnt:

1. settings/<file>.ini, die Standardwerte des Kernels (oder die eigene settings/<file>.ini Ihrer Erweiterung für eine Datei von Ihnen)
2. settings/<file>.ini.append.php der aktiven Erweiterungen, in der Reihenfolge der Erweiterungen
3. settings/siteaccess/<siteaccess>/ und settings/siteaccess/<siteaccess>/ der Erweiterungen
4. settings/override/ der Erweiterungen
5. settings/override/<file>.ini.append.php der Installation

Die Reihenfolge der Erweiterungen spielt eine Rolle, wenn zwei Erweiterungen denselben Schlüssel setzen (Ladereihenfolge der Erweiterungen, Geltungsbereiche von Einstellungen und ihre Reihenfolge).

Umgebungsvarianten #

Wenn config.env.php EXP_ENV definiert (zum Beispiel dev, test, prod), liest eZINI zusätzlich eine Variante jeder Datei mit dem Umgebungsnamen nach .ini, nach der Standarddatei derselben Schicht:

settings/override/site.ini.append.php
settings/override/site.ini.test.append.php     read after it when EXP_ENV is 'test'

Die Variante überschreibt nur ihre eigene Schicht, und jede Umgebung hat ihren eigenen INI-Cache. eZINI::environment() gibt den Namen zurück; Templates lesen ihn mit {exp_environment()} (Umgebungseinstellungen).

Arrays #

[AcmeReportSettings]
ClassList[]
ClassList[]=article
ClassList[]=event

• Zeilen Key[]=value addieren sich über die Schichten hinweg.
• Eine leere Zeile Key[] löscht alles, was davor gesetzt wurde, auch in früheren Schichten. Liefern Sie sie als erste Zeile einer Liste in Ihren Standardwerten aus, damit eine Überschreibung die Liste sauber ersetzen kann.
• Key[name]=value ergibt ein assoziatives Array.

Standardwerte für fehlende Schlüssel #

variable() auf einen fehlenden Schlüssel schreibt einen Fehler („Undefined variable“ oder „Undefined group“) in die Debug-Ausgabe und das Fehler-Log und gibt false zurück. Code, der optionale oder neue Schlüssel liest, muss prüfen:

$ini = eZINI::instance( 'acmereport.ini' );
$limit = $ini->hasVariable( 'ListSettings', 'DefaultLimit' )
    ? max( 1, min( 100, (int)$ini->variable( 'ListSettings', 'DefaultLimit' ) ) )
    : 10;

Casten und begrenzen Sie Werte aus Einstellungen immer, wie jede Eingabe: Einstellungen werden von Menschen geschrieben.

Ihre eigene Einstellungsdatei #

Liefern Sie extension/acmereport/settings/acmereport.ini mit jedem Schlüssel und einem Kommentar zu jedem aus. Änderungen an den Dateien des Kernels gehören in *.ini.append.php, eingeschlossen in einen PHP-Kommentar, damit der Webserver sie niemals anzeigt:

<?php /* #?ini charset="utf-8"?
[ModuleSettings]
ExtensionRepositories[]=acmereport
*/ ?>

Einstellungen schreiben #

$ini->setVariable( $block, $name, $value ) ändert den Wert im Speicher für diese Anfrage; save() schreibt eine Datei. Um Einstellungen in einer Datei zu ändern, verwenden Sie die Engine exp:ini, die Zeile für Zeile bearbeitet und Kommentare erhält (Einstellungen auf der Kommandozeile ändern, exp:ini):

php bin/php/console exp:ini get acmereport.ini/ListSettings/DefaultLimit
php bin/php/console exp:ini set acmereport.ini/ListSettings/DefaultLimit 20 global

Schreiben Sie niemals Geheimnisse in eine Datei, die Ihre Erweiterung ausliefert; lesen Sie sie aus settings/override/ der Installation.

Caches und persistente Worker #

• Einstellungen werden in den INI-Cache kompiliert. Nach einer Änderung: php bin/php/ezcache.php --clear-tag=ini. --clear-id=ini erfasst den globalen INI-Cache nicht.
• Unter Velocity liest ein Worker die Einstellungen einmal und behält sie; exp:velocity deploy leert den INI-Cache und startet die Worker in der richtigen Reihenfolge neu (Persistente Velocity-Worker für PHP-Entwickler).
• Halten Sie einen eZINI-Wert nicht anfrageübergreifend in einer eigenen statischen Eigenschaft; lesen Sie ihn dort aus eZINI::instance(), wo Sie ihn brauchen (Fallen durch statischen Zustand).

Verwandte Seiten #

• Einstellungen und INI-Dateien in Ihrer Anwendung
• INI-Dateien für Erweiterungsautoren
• eZINI erhält Kommentare
• Freie Dokumentation: diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.