3. Den Code beschaffen #

Dieses Kapitel bringt den Code von Exponential auf Ihren Rechner. Es gibt drei Wege: ein git clone gefolgt von composer install, bei dem jedes se7enxweb-Paket als Git-Klon mit seiner vollständigen Historie ankommt (der empfohlene Weg für alle, die Websites bauen), composer create-project (der schnellste Weg zu einer Website, die Sie nur betreiben) und composer require in ein leeres Verzeichnis (wenn die Installation ein eigenes Projekt sein soll). Alle drei führen zu denselben Dateien. Das Kapitel erklärt, welche Version Sie auf welchem Weg erhalten und wie Sie eine auswählen, wie die Extensions als Composer-Pakete ankommen, wie das Paket Exponential Velocity ankommt und was unter PHP 8.0 bis 8.3 anders ist, und schließt mit einem Rundgang durch jeden Eintrag der obersten Ebene des Installationsverzeichnisses und den Rechten, die Sie vor der Installation setzen müssen.

Warnung .htaccess bremst jede Anfrage. Sind .htaccess-Dateien erlaubt (AllowOverride alles außer None), geschweige denn genutzt, sucht Apache sie bei jeder Anfrage in jedem Verzeichnis des Pfads und liest und wertet sie aus, und die Ladezeiten der Seiten steigen drastisch (gemessen). Die einzige wirkliche Abhilfe ist, die Funktion für den virtuellen Host abzuschalten: AllowOverride None im virtuellen HTTPS-Host, und die Regeln in der Konfiguration des virtuellen Hosts selbst als mod_rewrite-Regeln. Das ist in Geschwindigkeitstests im Produktivbetrieb weit schneller und die Zeit für die Optimierung einer Produktivkonfiguration unbedingt wert. Stellen Sie sofort um: Übernehmen Sie die Regeln des Beispiels für einen virtuellen HTTPS-Host in Ihren virtuellen Host (mit dem statischen Cache auch staticcache_offload.conf), setzen Sie AllowOverride None, führen Sie apachectl configtest aus, laden Sie Apache neu und testen Sie die Website. Dieselben Regeln für andere Server: nginx, LiteSpeed, Caddy, IIS, Velocity (eingebaut); wohin Regeln für virtuelle Hosts in einem Control Panel gehören: Plesk, cPanel, DirectAdmin, ISPConfig. Unter LiteSpeed oder OpenLiteSpeed kann zusätzlich der Seiten-Cache des Servers anonyme Besucher und Crawler ohne PHP bedienen: Seiten-Caching mit LiteSpeed und OpenLiteSpeed.

Inhalt · Zurück: 2. Voraussetzungen · Weiter: 4. Eine Installationsmethode wählen

3.1 Versionen, Tags und Branches #

Exponential wird als Composer-Paket se7enxweb/exponential aus dem Git-Repository github.com/se7enxweb/exponential veröffentlicht.

Die Linie 6.0.15 folgt auf den Release-Tag v6.0.14; der Branch main bezeichnet sich selbst als 6.0.15stable (lib/version.php) und enthält die in Changelog 6.0.15 beschriebenen Änderungen. Um zu sehen, was derzeit veröffentlicht ist:

git ls-remote --tags https://github.com/se7enxweb/exponential.git 'v6*'

oder, innerhalb eines Klons, nach git fetch --tags:

git tag -l 'v*' --sort=version:refname | tail -5

was die fünf neuesten Tags ausgibt, den neuesten zuletzt (hier die Ausgabe vor dem Tag v6.0.15):

v6.0.10
v6.0.11
v6.0.12
v6.0.13
v6.0.14

Sortieren Sie immer nach Version (--sort=version:refname oder sort -V), niemals nach Namen: Nach Namen sortiert steht v6.0.10 vor v6.0.8, und ein Skript, das die letzte Zeile einer Namenssortierung nimmt, wählt die falsche Release. Die Releases des Projekts sind mit ihren Release Notes unter GitHub Releases aufgeführt.

Ein Release-Tag ändert sich nie. Einmal veröffentlicht, sind ein Tag und die Paketversion, die Packagist daraus gebaut hat, dauerhaft; eine Korrektur kommt immer als nächste Version. Sie können einen Tag festlegen und sich darauf verlassen, jedes Mal dieselben Dateien zu erhalten; genau das macht eine festgelegte Version zur richtigen Wahl für den Produktivbetrieb.

Welche Version welches PHP braucht. Lesen Sie dies, bevor Sie wählen, denn Composer verweigert eine Version, deren PHP-Anforderung Ihr PHP nicht erfüllt:

Die Tags v6.0.0 bis v6.0.14 akzeptieren PHP 8.0 nicht: Verwenden Sie unter PHP 8.0 die Linie 6.0.15, also ~6.0.15 (den Tag v6.0.15, sobald er veröffentlicht ist) oder den Branch main, der diese Linie trägt.

composer.json gibt main den Branch-Alias 6.0.x-dev ("extra": { "branch-alias": { "dev-main": "6.0.x-dev" } }). Aus main installiert, hat das Root-Paket dann sowohl die Version 6.0.x-dev als auch dev-main, sodass ein Paket, das se7enxweb/exponential mit einer Versionsbedingung wie ^6.0.14 verlangt (wie expqueue), dagegen aufgelöst werden kann. Ohne den Alias erfüllt dev-main keine Versionsbedingung, und eine solche Installation bricht mit „could not be resolved“ ab.

3.2 Drei Wege zum Code #

A. git clone und composer install (empfohlen) #

Der empfohlene Weg für alle, die Websites mit Exponential bauen. Mit Git-Klonen sehen Sie, was sich geändert hat (git status, git diff), warum eine Zeile dasteht (git log, git blame) und welche Änderung etwas kaputt gemacht hat (git bisect); Sie können eine Korrektur nutzen, bevor sie veröffentlicht ist, Ihre eigenen Änderungen auf einem Branch halten, den Updates nie überschreiben, und Korrekturen als Pull Requests zurückschicken. Mit Git entwickeln erklärt jeden dieser Punkte Schritt für Schritt.

Weisen Sie Composer zuerst, einmal pro Benutzerkonto, an, jedes se7enxweb/*-Paket als Git-Klon (die Extensions und seit 6.0.15 auch die expcomponents-Bibliotheken) und alles andere (andere Bibliotheken) als Release-Archiv zu installieren:

composer config --global 'preferred-install.se7enxweb/*' source

Klonen Sie dann den Kernel, legen Sie einen eigenen Branch an und installieren Sie:

git clone https://github.com/se7enxweb/exponential.git
cd exponential
git switch -c my-site               # or: git switch -c my-site v6.0.14, to build on a release instead of main
composer install

Der Klon enthält den Kernel mit seiner gesamten Historie (mehr als 27.000 Commits, etwa 370 MB), die mit dem Kernel ausgelieferten Extensions (ezjscore, ezoe, ezformtoken, expservices) und die Designs. composer install fügt vendor/ hinzu und klont jede Extension, die composer.json verlangt, nach extension/<name>, jede als eigenes Git-Repository (67 auf main; die erste Installation dauert einige Minuten). Diese Extensions gehören nicht zum Repository des Kernels, daher führt git status sie als nicht verfolgt auf; das ist zu erwarten. Jede steht auf dem Release-Tag, den Composer gewählt hat, sodass git -C extension/<name> status HEAD detached at <tag> meldet: Das ist normal, und ein Branch ist nur ein git switch -c entfernt.

Prüfen Sie, ob die Extensions Klone sind:

composer status -v                  # "No local changes"
ls -d extension/*/.git | wc -l      # the number of extensions installed as clones
git -C extension/eztags log --oneline -3

Ohne die Einstellung preferred-install kommen die Extensions als Archive an; composer reinstall 'se7enxweb/*' macht sie später zu Klonen (Mit Git entwickeln). Um die Einstellung beim Projekt statt bei Ihrem Konto zu halten, führen Sie den Befehl composer config ohne --global innerhalb des Klons aus; er wird dann auf Ihrem Branch in composer.json geschrieben.

Um später zu aktualisieren, auf Ihrem Branch:

git fetch origin --tags
git merge origin/main               # or the release you move to: git merge v6.0.<n>
composer update

composer update, nicht composer install: Die composer.json des Kernels hat sich geändert, und die Lock-Datei (Ihre eigene, sie gehört nicht zum Repository) muss ihr folgen. composer update se7enxweb/<package> aktualisiert eine einzelne Extension. Immer zuerst Git, dann Composer. Mit Git aktualisieren beschreibt das Vorgehen auf der Kommandozeile und in der Administration (Git Manager, dann „Updates und Pakete“), für jeden Rhythmus von stündlich bis nur zu jeder Release, sowie ein automatisches Update mit cron oder einem systemd-Timer. Composer verweigert das Aktualisieren eines Klons mit nicht committeten Änderungen oder mit Commits, die nur auf Ihrem Rechner existieren, sodass Ihre Arbeit nie überschrieben wird; Wenn Composer sich weigert führt die Meldungen auf und was zu tun ist. Den Code zu bewegen ist nur die Hälfte eines Upgrades: Die Datenbank-Update-Dateien aus Kapitel 11 sind die andere Hälfte.

B. composer create-project #

Der schnellste Weg zu einer Website, die Sie nur betreiben. Composer lädt das Paket herunter, macht das Verzeichnis zu Ihrem Projekt und installiert alle Abhängigkeiten:

cd /var/www
composer create-project se7enxweb/exponential exponential
cd exponential

Ohne Versionsangabe nimmt Composer die neueste stabile Release. Um eine festzulegen oder dem Entwicklungs-Branch zu folgen:

composer create-project se7enxweb/exponential:~6.0.15 exponential
composer create-project se7enxweb/exponential:dev-main exponential

create-project behandelt die heruntergeladene composer.json als Root-Paket, daher gelten ihr config.allow-plugins (das se7enxweb/exponential-legacy-installer zulässt) und ihr Skript post-install-cmd: Die Class Maps werden am Ende erzeugt (php bin/php/ezpgenerateautoloads.php). Fügen Sie auf einem Produktivserver --no-dev hinzu, wodurch die Testwerkzeuge weggelassen werden.

Standardmäßig kommt jedes Paket, auch der Kernel, als Release-Archiv ohne Historie an. Um auch mit create-project Klone zu erhalten, geben Sie beide Optionen an:

composer create-project se7enxweb/exponential exponential --prefer-source --keep-vcs

Ohne --keep-vcs löscht Composer am Ende den .git-Ordner des Kernels. Eine aus Archiven installierte Website lässt sich später ohne Neuinstallation in Klone umwandeln: Mit Git entwickeln.

C. composer require in ein leeres Verzeichnis #

Wenn die Installation ein eigenes Projekt mit Ihrer eigenen composer.json sein soll:

mkdir exponential
cd exponential
composer require se7enxweb/exponential

Das Paket hat den Typ ezpublish-legacy. Das Installer-Plugin (LegacyKernelInstaller) installiert ein Paket dieses Typs in das Projektverzeichnis (.), sodass die Kernel-Dateien in dem Verzeichnis landen, in dem Sie sich befinden, nicht in vendor/. In einem Symfony-Projekt (einem, dessen composer.json extra.symfony-app-dir setzt) kommt es stattdessen nach ezpublish_legacy/; ein Projekt kann mit extra.ezpublish-legacy-dir ein anderes Verzeichnis angeben.

Zwei Dinge unterscheiden sich von den Wegen A und B:

• Ihre neue composer.json lässt das Installer-Plugin noch nicht zu. Composer 2.2 und neuer fragt, ob se7enxweb/exponential-legacy-installer vertraut werden soll; antworten Sie mit Ja, oder fügen Sie es vorher hinzu:

  composer config allow-plugins.se7enxweb/exponential-legacy-installer true

  Wenn Sie mit Nein antworten, landet der Kernel in vendor/se7enxweb/exponential/ und die Extensions ebenfalls in vendor/, wo nichts sie findet.

• Composer führt nur die Skripte des Root-Pakets aus, und das ist jetzt Ihres. Erzeugen Sie die Class Maps nach jeder Installation und jedem Update selbst:

  php bin/php/ezpgenerateautoloads.php

Das Ergebnis prüfen #

Gleich, welchen Weg Sie gewählt haben:

php bin/php/console --version
ls vendor/autoload.php

Die erste Zeile der Konsolenausgabe nennt die Version:

console (Exponential) 6.0.15stable

Fehlt vendor/autoload.php, ist Composer nicht fertig geworden; führen Sie composer install erneut aus und lesen Sie seine Ausgabe ab dem ersten Fehler, nicht ab der letzten Zeile. Die üblichen Ursachen sind eine fehlende PHP-Erweiterung (Composer nennt das ext-*, das es braucht), ein PHP, das für die angeforderte Version zu alt ist (3.1), oder ein Plugin, das nicht zugelassen wurde.

3.3 Installation unter PHP 8.0 bis 8.3 #

Auf der aktuellen Linie (main, 6.0.15) ist nichts Besonderes nötig: Ein einfaches composer install funktioniert unter jedem PHP von 8.0 bis 8.5. Die Entwicklungsanforderung "phpunit/phpunit": "^9.6 || ^10.5 || ^11.5 || ^12.0 || ^13.4" lässt Composer das PHPUnit wählen, das zum verwendeten PHP passt (9.6 unter 8.0, 10.5 unter 8.1, 11.5 unter 8.2, 12 unter 8.3, 13.4 unter 8.4 und 8.5). Dieser Bereich ist auch mit --no-dev wichtig: Das Repository liefert keine composer.lock aus, und ohne Lock-Datei löst Composer auch require-dev auf, obwohl es diese Pakete nicht installiert. Die eigene PHP-8.0-Prüfung des Projekts (der Job php80 in .github/workflows/quality.yml) installiert genau so, wie eine Website es tut:

composer install --no-dev --prefer-dist

Die Testsuite selbst verwendet Funktionen von PHPUnit 10 und läuft daher unter PHP 8.1 und neuer; unter PHP 8.0 sorgt der Bereich nur dafür, dass sich die Installation auflösen lässt.

Die Release-Tags v6.0.13 und v6.0.14 sind anders. Sie verlangen "phpunit/phpunit": "13.0.0", das PHP 8.4.1 braucht, sodass eine einfache Installation dieser Tags unter PHP 8.1 bis 8.3 mit einem PHP-Versionskonflikt bei PHPUnit abbricht. Entfernen Sie zuerst die beiden Entwicklungsanforderungen und installieren Sie dann, was eine Website braucht:

composer create-project --no-install se7enxweb/exponential:v6.0.14 exponential
cd exponential
composer remove --dev --no-update --no-interaction phpunit/phpunit zetacomponents/php-generator
composer install --no-dev --prefer-dist

composer remove --no-update ändert nur composer.json und installiert nichts; der zweite Befehl installiert. In einem Git-Klon dieser Tags genügen die letzten beiden Befehle, und git checkout composer.json stellt die Datei danach wieder her.

Auf einem Produktivserver ist --no-dev unter jeder PHP-Version richtig: Die Testwerkzeuge werden zum Betrieb einer Website nicht gebraucht.

3.4 Das Velocity-Paket #

Seit 6.0.15 ist Exponential Velocity, der Internet / Web Application Server und die empfohlene Engine für jede Stufe, Teil von Exponential. Es ist das Paket se7enxweb/exponential-velocity, und die composer.json im Wurzelverzeichnis verlangt es (vor 6.0.15 wurde es nur vorgeschlagen):

"se7enxweb/exponential-velocity": "~0.0.4.57"

Velocity 0.0.4.54 läuft unter PHP 8.0 und höher ("php": ">=8.0") und braucht die Erweiterung sockets ("ext-sockets": "*"), sodass dasselbe PHP, das den Kernel ausführt, auch den Server ausführt, das mitgelieferte PHP 8.0 von Red Hat Enterprise Linux 9 eingeschlossen. Ein einfaches composer install installiert es; mehr ist nicht nötig. Bis 0.0.4.54 brauchte die Engine PHP 8.1, und composer.json schlug sie nur vor; eine Installation aus dieser Zeit fügt sie so hinzu:

composer require se7enxweb/exponential-velocity:~0.0.4.57

~0.0.4.57 akzeptiert jede spätere Release 0.0.4.x (>=0.0.4.57 <0.0.5.0), sodass Composer die neueste davon installiert. Die letzte Stelle einer Velocity-Version zählt über 9 hinaus weiter (0.0.4.9, 0.0.4.10, ...), daher findet eine Versionssortierung die neueste, keine Namenssortierung.

Das Paket landet in vendor/se7enxweb/exponential-velocity/ (sein Typ ist project, daher wird es nicht nach extension/ verschoben). Die Konsole findet es dort: php bin/php/console exp:velocity status meldet die Engine, und exp:velocity start startet sie. Bevor das Paket installiert ist, kann die Engine qbix nicht starten und meldet velocity: no server script at ...; die Engine php (der eingebaute Server von PHP) funktioniert auch ohne das Paket:

php bin/php/console exp:velocity start --engine=php

Velocity wird auch als Betriebssystempakete (.deb, .rpm) und als eigenständige Binärdatei veröffentlicht; siehe Velocity-Pakete und -Binärdateien. Bevor Sie es aktualisieren, lesen Sie die Upgrade-Hinweise zur Velocity-Engine.

3.5 Extensions sind Composer-Pakete #

Jede Extension außer den vier mit dem Kernel ausgelieferten ist ein Composer-Paket vom Typ ezpublish-legacy-extension. Das Installer-Plugin se7enxweb/exponential-legacy-installer (von composer.json verlangt) legt ein solches Paket nach extension/<name>:

composer.json entscheidet also, welche Extensions eine Installation hat, und in welchen Versionen:

"se7enxweb/eztags": "~2.4.11",
"se7enxweb/cjw_newsletter": "~4.2.0",
"se7enxweb/explayouts": "~1.4.15",

Die Tilde-Bedingung lässt die letzte angegebene Stelle frei: ~2.4.11 bedeutet >=2.4.11 <2.5.0. Um eine Extension hinzuzufügen, verlangen Sie ihr Paket, aktivieren Sie sie dann und erzeugen Sie die Class Maps neu:

composer require se7enxweb/ezfind
php bin/php/ezpgenerateautoloads.php -e

Dass eine Extension auf der Festplatte liegt, macht sie noch nicht aktiv: Sie muss in [ExtensionSettings] ActiveExtensions[] aufgeführt sein. Die Installer aktivieren die Extensions des Site-Pakets; andere aktivieren Sie in der Administration (Setup > Extensions) oder in settings/override/site.ini.append.php:

[ExtensionSettings]
ActiveExtensions[]=ezfind

Leeren Sie danach den INI-Cache (php bin/php/ezcache.php --clear-tag=ini) und starten Sie Velocity neu, wenn er die Website ausliefert.

Zwei Pakete aus composer.json kommen absichtlich inaktiv an und werden eingeschaltet, wenn Sie sie brauchen: die Job-Warteschlange se7enxweb/expqueue (extension/expqueue, expqueue) und Exponential Intelligence, der Schreibassistent der Administration, se7enxweb/expai (extension/expai, expai). Beide brauchen eigene Tabellen und eine Cron-Zeile; der Assistent außerdem einen Anbieterschlüssel in settings/override/expai.ini.append.php. Abschnitt 10.13 beschreibt die Schritte.

Der Block suggest der composer.json führt weitere Extensions mit je einem Satz auf, darunter ezsi, ezscriptmonitor, ezfind, ezauthorize, bcurlaliaswithdash, sevenx_valkey, sevenx_valkey_cache, ezownerchange, adminaid, ezpm und hcaptcha. Jede Extension hat ihr eigenes Repository unter github.com/se7enxweb und trägt ihre Version in ezinfo.php und extension.xml; die Extension-Liste der Administration zeigt sie an.

Führen Sie composer update auf einer Live-Website nicht leichtfertig aus. Es hebt jedes Paket auf die neueste Version, die seine Bedingung zulässt. Aktualisieren Sie ein Paket gezielt (composer update se7enxweb/<package>) und lesen Sie vorher seine Release Notes. Klone, die Composer selbst angelegt hat (Weg A), sind sicher: Composer verweigert das Aktualisieren eines Klons mit nicht committeten Änderungen oder nicht gepushten Commits. Ein von Hand angelegter Klon (git clone nach extension/<name>) anstelle eines Pakets, das Composer als Archiv installiert hat, ist es nicht: Composer behandelt den Ordner weiterhin als Archiv und ersetzt ihn, samt Historie und Commits. Um ein Archiv in einen Klon umzuwandeln, überlassen Sie das Composer mit composer reinstall <package>, nachdem Sie preferred-install gesetzt haben (Weg A).

Mehr: Anleitung zu Extensions, Extension-Liste und Downloads, Standardverteilung der Extensions, Ladereihenfolge der Extensions, Zusätzliche Extension-Verzeichnisse.

3.6 Ein Rundgang durch das Installationsverzeichnis #

Die Einträge einer frischen Installation, in alphabetischer Reihenfolge. „Versioniert“ bedeutet, dass die Datei oder das Verzeichnis zum Git-Repository gehört; die übrigen werden von Composer oder zur Laufzeit angelegt.

Verzeichnisse #

Dateien #

Dateien, die nach einer Installation erscheinen und Ihnen gehören, die nie committet oder weitergegeben werden dürfen: settings/override/* und settings/siteaccess/* (Datenbank-Zugangsdaten), kickstart.ini (das Datenbankpasswort), config.env.php und var/log/initial-admin-password.

3.7 Rechte nach dem Beschaffen des Codes #

Der Benutzer, unter dem der Webserver oder die Worker von Velocity laufen, muss in design, extension, settings, settings/override, settings/siteaccess und var samt allem darunter schreiben können (die Liste, die der Setup-Assistent prüft, ist [directory_permissions] CheckList in settings/setup.ini). Wenn Sie Composer als ein anderer Benutzer ausgeführt haben, übergeben Sie die Dateien vor der Installation, und zwar in dieser Form (der Setup-Assistent gibt die genauen Befehle für Ihren Rechner aus):

sudo chmod -R ug+rwx design extension settings var
sudo chown -R <web user>:<web group> design extension settings var

Wenn die Kommandozeile (Cronjobs, die Konsole, Composer) und der Webserver unter verschiedenen Benutzern laufen, geben Sie beiden eine gemeinsame Gruppe, die dieselben Dateien schreiben darf, statt die Verzeichnisse für alle zu öffnen. Ausliefern und Rechte werden ausführlich in Kapitel 8 behandelt.

Referenzen #

In diesem Repository:

• Installationsüberblick, Abschnitt 3.
• Aktualisieren: eine bestehende Website auf neuen Code umstellen.
• Unterstützung für PHP 8.0: Installation mit Composer unter PHP 8.0.
• Continuous Integration und Qualitätsprüfungen.
• Velocity-Engines, Velocity-Pakete und -Binärdateien, Upgrade-Hinweise zur Velocity-Engine.
• Anleitung zu Extensions, Extensions, Extension-Metadaten.
• Eine Installation reparieren: wenn vendor/ fehlt.
• Konsole.
• Changelog 6.0.15 und die Release Notes der Extensions.
• Code: composer.json, lib/version.php, .github/workflows/quality.yml (Job php80), vendor/se7enxweb/exponential-legacy-installer/src/eZ/Publish/Composer/ (LegacyKernelInstaller, LegacyExtensionInstaller).

Extern:

• Composer: create-project, install, require, remove, Versionsbedingungen, allow-plugins, Skripte.
• Packagist: se7enxweb/exponential, se7enxweb/exponential-velocity, alle se7enxweb-Pakete.
• GitHub: se7enxweb/exponential, Releases, se7enxweb/exponential-velocity, alle se7enxweb-Repositories.
• PHPUnit: unterstützte Versionen.
• Git: git clone, git tag.

Inhalt · Zurück: 2. Voraussetzungen · Weiter: 4. Eine Installationsmethode wählen