Die Umschaltung des Administrationsdesigns: Was sich für Entwickler geändert hat #

Lesen Sie diese Seite, wenn Sie ein Administrationsdesign pflegen, eine Erweiterung, die Kernel-Klassen für die Administration überschreibt, Code, der die Design-Einstellungen oder den Design-Base-Cache liest, oder eine Installation, die sevenx_themes_admin_classic verwendet. Sie führt die neue Klasse auf, die Änderung am Cache-Schlüssel, das Verhalten auf den persistenten Workern von Velocity und was die Kernel-Overrides von sevenx_themes_admin_classic ersetzt. Gültig seit dem 15. Oktober 2026.

Die Seite für Benutzer ist die Funktionsseite, die Einstellungen stehen in der Anleitung. Das Framework, auf dem dies aufbaut (Registry, Modul uiswitch, Richtlinien, Speicherung in der Sitzung, Varianten-Schlüssel des Caches), ist in UI-Umschaltung: Hinweise für Entwickler beschrieben.

Kurz gesagt #

• Neue Kernel-Klasse expUISwitchDesignProvider (kernel/classes/uiswitch/expuiswitchdesignprovider.php), der Provider design der UI-Umschaltung. Er setzt site.ini [DesignSettings] SiteDesign und AdditionalSiteDesignList[] im Speicher, für die Anfragen eines Benutzers, der ein anderes Administrationsdesign gewählt hat.
• Neue statische Methode eZTemplateDesignResource::designBaseCachePath( $siteAccess = false ). Der Dateiname des Design-Base-Caches des aktuellen Siteaccess enthält den Varianten-Schlüssel der UI-Umschaltung nur, wenn eine Wahl angewendet wird. Ohne Wahl ist der Dateiname byte-genau derselbe wie bisher. Ein namentlich angefragter Siteaccess wird nie umgeschaltet.
• Kompilierte Templates, {cache-block} und der Cache der Inhaltsansichten werden durch den Varianten-Schlüssel der UI-Umschaltung aus dem Framework getrennt. Der Template-Override-Cache war bereits nach der Design-Liste geschlüsselt.
• Eine Umschaltung leert keinen Cache: kein eZCache::clearByTag().
• apply() und reset() leeren die statischen und globalen Design-Daten, sodass ein persistenter Velocity-Worker nie das Design eines Benutzers in die nächste Anfrage mitnimmt.
• Die Kernel-Overrides von sevenx_themes_admin_classic (ezpKernelWeb, global_functions.php) sind ab dessen Version 0.2.5 überflüssig und müssen entfernt werden.

Die Provider-Klasse #

expUISwitchDesignProvider extends expUISwitchProvider (Kennung design, Richtlinie uiswitch/design, Einstellungsgruppe uiswitch.ini [UISwitch_design]).

Die Design-Daten zu leeren heißt eZTemplateDesignResource::clearInMemoryCache() (das globale eZTemplateDesignSetting, das statische Override-Array und die Match-File-Caches, das globale eZOverrideTemplateCacheMap) und das Entfernen von $GLOBALS['eZTemplateDesignResourceBases']. Die Basen namentlich angefragter Siteaccesses (eZTemplateDesignResourceSiteAccessBases) werden nicht angetastet: Sie folgen nie einer Umschaltung.

Die Registry ruft apply() aus ezpKernelWeb::requestInit() auf, nach dem Start der Sitzung und vor der Login-Vorprüfung, dem Request/Input-Ereignis, eZLocale und jedem Template, sodass $site.design und jedes Template das gewählte Design sehen. Im Setup-Assistenten (validity-check-required) wird es nicht aufgerufen, und eZTemplateDesignResource::designSetting( 'site' ) gibt weiterhin zuerst site-design-override zurück, wo das gesetzt ist.

Der Schlüssel des Design-Base-Caches #

eZTemplateDesignResource::allDesignBases() speichert die Liste der Design-Verzeichnisse in <cache>/<DESIGN_BASE_CACHE_NAME><md5>.php, wenn site.ini [DesignSettings] DesignLocationCache=enabled gilt. Der Dateiname kommt jetzt aus der neuen öffentlichen statischen Methode:

static function designBaseCachePath( $siteAccess = false )
{
    $siteAccessName = $siteAccess ? (string)$siteAccess : ( $GLOBALS['eZCurrentAccess']['name'] ?? '' );
    if ( !$siteAccess && !empty( $GLOBALS['expUISwitchVariantKey'] ) )
        $siteAccessName .= '-' . $GLOBALS['expUISwitchVariantKey'];

    return eZSys::cacheDirectory() . '/' . self::DESIGN_BASE_CACHE_NAME . md5( $siteAccessName ) . '.php';
}

• Keine Wahl angewendet (der Varianten-Schlüssel ist ''): md5( <siteaccess> ), dieselbe Datei wie bisher.
• Eine Wahl angewendet: md5( <siteaccess> . '-' . <variant key> ), zum Beispiel md5( 'admin-design-admin4' ).
• $siteAccess angegeben: md5( $siteAccess ), egal was der aktuelle Benutzer gewählt hat. Diese Liste wird aus den Einstellungen des Siteaccess auf der Festplatte gelesen, die eine Umschaltung nie ändert.

Der Varianten-Schlüssel ist der gesamte Schlüssel der Anfrage, die Provider nach Kennung sortiert und mit . verbunden (design-admin4.language-ger-DE). Ein Benutzer, der nur die Sprache der Oberfläche geändert hat, erhält daher ebenfalls eine eigene Datei des Design-Base-Caches; ihr Inhalt entspricht dem der Standarddatei.

Code, der den Dateinamen selbst gebildet hat (DESIGN_BASE_CACHE_NAME . md5( $siteaccess )), findet weiterhin die Standarddatei; rufen Sie designBaseCachePath() auf, um die Datei der aktuellen Anfrage zu erhalten.

Vor dieser Änderung setzte sevenx_themes_admin_classic für seinen Siteaccess DesignLocationCache=disabled im Speicher, weil eine Design-Liste pro Sitzung sich nicht eine Cache-Datei pro Siteaccess teilen kann. Der Kernel lässt den Cache eingeschaltet.

Die anderen Caches #

Eine Umschaltung ruft kein eZCache::clearByTag() auf. Die Erweiterung leerte bei jeder Umschaltung und jedem Zurücksetzen die Caches template und template-block der ganzen Installation; mit den obigen Schlüsseln hat jedes Design eigene Caches, und die Caches der Benutzer ohne Wahl bleiben unberührt.

Velocity und andere persistente Worker #

Ein Velocity-Worker bedient viele Anfragen in einem Prozess. Pro Anfrage baut index.php ein neues ezpKernelWeb, dessen eZINI::resetAllInstances() frische INI-Instanzen liefert, sodass ein angewendetes Design nie in den Einstellungen bleibt. Was in einem Prozess bleibt, sind statische und globale Daten:

• expUISwitch::beginRequest() ruft zu Beginn jedes requestInit() das reset() jedes Providers auf, der früher im Prozess einen Wert angewendet hat, und setzt den Varianten-Schlüssel auf ''.
• expUISwitchDesignProvider::reset() und apply() leeren die oben aufgeführten statischen und globalen Design-Daten. Das statische Override-Array ist dasjenige, das einmal ein kompiliertes Admin-Pagelayout mit einem öffentlichen Header ausgeliefert hat (24. September 2026).
• Die Registry überspringt einen Provider, dessen Klasse ein Worker nicht kennt (class_exists), sodass das Nennen der Klasse in den Einstellungen vor dem Neustart der Worker keine Anfragen abbricht. Erzeugen Sie die Autoloads neu und stellen Sie bereit, bevor die Einstellungen eine neue Provider-Klasse nennen.

Die Kernel-Overrides von sevenx_themes_admin_classic ersetzen #

Bis 0.2.4 ersetzte sevenx_themes_admin_classic zwei Kernel-Dateien über classes/kerneloverride/ und EZP_AUTOLOAD_ALLOW_KERNEL_OVERRIDE:

• kernel/private/classes/ezpkernelweb.php: eine alte Kopie von ezpKernelWeb mit einem Block am Ende von __construct(), der das Design umschaltete. Alles andere in der Kopie ist älter als Monate von Kernel-Änderungen (Sicherheits-Header, der 403-Pfad des Formular-Tokens, der Audit-Header, Korrekturen für Velocity); wer sie installiert, setzt den Kernel also zurück.
• kernel/private/classes/global_functions.php: eine alte Kopie ohne Design-Logik, nur mitgeliefert, weil das kopierte ezpKernelWeb sie aus seinem eigenen Verzeichnis einband.

Version 0.2.5 entfernt beide, das Modul switchadmindesign, sein Werkzeug in der Werkzeugleiste und seine Zurücksetzungen der Werkzeugleisten, und verlässt sich stattdessen auf die Umschaltung des Kernels. admin_classic (Beschriftung „Klassisch (serverseitig)“, Kette admin) steht in den Kernel-Standardwerten von settings/uiswitch.ini [UISwitch_design], neben admin4l, admin4, adminui, admin3 (Kette admin2;admin) und admin; es wird überall angeboten, wo die Erweiterung aktiv ist, weil die Erweiterung das Design-Verzeichnis registriert. Die eigene settings/uiswitch.ini.append.php der Erweiterung wiederholt dieselben Werte, was nicht schadet (jedes Design wird einmal angeboten). Ebenso wird adminui nur in einem Siteaccess mit ActiveAccessExtensions[]=exp_adminui angeboten, in einer Standardinstallation also allein im Siteaccess adminui (Anleitung).

Das Pagelayout der klassischen admin (design/admin/templates/pagelayout.tpl) zeigt sein rechtes Menü an, sofern der Benutzer es nicht geschlossen hat (admin_right_menu_show=0), wie admin4; bisher sah ein Benutzer, der die Einstellung nie gesetzt hatte, es eingeklappt. So bleibt das Werkzeug zum Umschalten erreichbar.

In einer Installation, die die Overrides verwendet hat:

1. Aktualisieren Sie die Erweiterung auf 0.2.5 oder neuer. Stellen Sie sicher, dass extension/sevenx_themes_admin_classic/classes/kerneloverride/ nicht mehr existiert.

2. Erzeugen Sie die Autoloads ohne -o / --kernel-override neu:

   php bin/php/ezpgenerateautoloads.php -e

   Ordnet var/autoload/ezp_override.php ezpKernelWeb noch der Erweiterung zu, erzeugen Sie sie mit -o neu, nachdem die Dateien entfernt sind, oder verschieben Sie sie; lassen Sie EZP_AUTOLOAD_ALLOW_KERNEL_OVERRIDE in config.php ausgeschaltet, sofern keine andere Erweiterung es braucht.

3. Entfernen Sie einen Eintrag PolicyOmitList[]=switchadmindesign aus Ihren eigenen Einstellungen, falls Sie einen hinzugefügt haben, und ersetzen Sie die Richtlinie switchadmindesign/switch in Ihren Rollen durch uiswitch/design.

4. Stellen Sie bereit (./console exp:velocity deploy --allow-root-user).

Eine Installation prüfen #

• grep -rn "kerneloverride" var/autoload/ezp_override.php gibt nichts aus (oder die Datei existiert nicht).
• Ohne Wahl ist die Datei des Design-Base-Caches eines Siteaccess weiterhin <cache>/<DESIGN_BASE_CACHE_NAME>, gefolgt von md5( '<siteaccess>' ).
• php vendor/bin/phpunit tests/tests/kernel/classes/uiswitch/expUISwitchDesignProviderTest.php läuft durch (ohne Datenbank): erlaubte Werte, Ketten, Beschriftungen, Anwenden und Zurücksetzen, der Dateiname des Design-Base-Caches mit und ohne Wahl und das Setzen des Varianten-Schlüssels durch die Registry.

Verwandte Seiten #

• Funktion: das Administrationsdesign wählen
• Anleitung: die Umschaltung des Administrationsdesigns
• UI-Umschaltung: Hinweise für Entwickler
• Velocity-Engines und das Bereitstellen einer PHP-Änderung
• Erweiterungen: Verhaltensänderungen