OXRUN – Das CLI Tool zum Shop

Wir leben in Zeiten, in denen der manuelle FTP-Upload der Dateien „Old School“ ist. Die Shell ist unsere Arbeitsumgebung auf den Servern. Per SSH verbinden wir uns mit unseren Servern und versprühen die Magie, die niemand sieht. Daher ist es durchaus angebracht, unseren OXID eShop nun auch über die Kommandozeile bedienen zu können.

Die „Gute Fee“ OXRUN erfüllt uns diesen Wunsch. Dieses Entwickler-Tool bietet sehr viele Funktionen, die das Deployen, Debuggen und Entwickeln leichter machen können.

OXRUN Features

  • OXRUN hilft beim Continuous-Integration-Prozess Module zu aktivieren und fest definierte OXID-Einstellungen zu übernehmen.
  • OXRUN kann den OXID-Cache leeren. Diese Funktionalität dürfte besonders beliebt sein, weil sie häufige Probleme löst 😉
  • Mit OXRUN kann man einen SQL-Dump mit anonymisierten Daten erstellen, was sich insbesondere für Entwicklungs- und Staging-Umgebungen eignet: Es kann praktisch ein Clone der Produktivdatenbank ohne Kundendaten angelegt werden.
  • Beim Importieren eines Datenbankdumps kann es vorkommen, dass View-Tabellen fehlen oder fehlerhaft erstellt werden und oft können diese Views nicht mehr über die Weboberfläche gefixt werden. OXRUN kann auch hierbei hilfreich sein.
  • Mit OXRUN kannst Du schnell ein neues, leeres Modul-Skelleton erstellen und kannst sofort mit dem Programmieren anfangen, ohne Dich um die Infrastruktur kümmern zu müssen.

Installation

Es gibt zwei Möglichkeiten der Installation:

  1. Einmal kann OXRUN mit composer require installiert werden. Damit ist es im Shop immer verfügbar, jedoch muss immer der genaue Pfad zur ausführbaren Datei aufgerufen werden, z.B. ./vendor/bin/oxrun.
  2. Bequemer ist es jedoch, OXRUN als eigenständiges Programm systemweit z.B. in /usr/local/bin verfügbar zu machen: Damit kann das Tool von jeder Stelle aus aufgerufen werden, jedoch muss die Installation in diesem Fall manuell erfolgen. Weitere Informationen gibt es in der Installationsanleitung für OXRUN auf GitHub.

Bedienung

Wenn ich von Commands spreche, sind Aktionen und Funktionen gemeint, die mit OXRUN benutzt werden können. Z.B. wäre dann ./vendor/bin/oxrun ist das „Script“, die ausführbare Datei und cache:clear das „Command“. Ein zusammengefasster Aufruf lauten ./vendor/bin/oxrun cache:clear.

OXRUN versucht beim ersten Aufruf, den OXID eShop Code zu finden, indem es die bootstrap.php sucht. Wird diese Datei nicht gefunden, sind alle Commands deaktiviert. Aus diesem Grund ist es wichtig, dass Du Dich beim Aufruf irgendwo im Shopverzeichnis befindest.

Anwendungsbeispiele

Im Grunde gibt es drei wichtige Bereiche, bei denen OXRUN hilfreich sein kann.

1. Continuous Integration

Zunächst sollten Vorbereitungen getroffen werden, um Konfigurationen und Modul Einstellungen zu sichern – dadurch wird der Shop pro Umgebung richtig gesteuert.

  • Mit oxrun misc:generate:yaml:module wird eine YAML-Datei mit allen aktiven Modulen im Shop erzeugt. Um Module in den richtigen Umgebungen zu aktivieren empfehlt es sich, YAML-Dateien dementsprechend zu benennen, z.B. dev_module.yaml, stage_module.yaml.
  • Mit oxrun misc:generate:yaml:config werden OXID-Konfigurationen in den YAML-Dateien gespeichert; das ist ideal für Zahlungsarten oder Tracking Einstellungen, da diese pro Umgebung immer anderes sind. TIPP: Der Command hat Filteroptionen, um nur bestimmte Konfigurationen zu speichern. Hier kannst Du gern mehrere YAML-Dateien erstellen, z.B. stage_[art der Konfig].yaml. Diese Dateien werden standardmässig unter oxrun_config/ abgelegt.

In diesem Zusammenhang werden häufig noch folgende Commands benötigt:

  • oxrun views:update – Bei neu eingerichtet Datenbanken werden die Views erstellt.
  • oxrun config:multiset [YAML Name] – um die Konfigurationen wieder einzulesen.
  • oxrun module:multiactivate [YAML Name] – um die Module zu aktivieren.
  • oxrun cache:clear – Leert den Cache und wird eigentlich ständig benötigt.

2. SQL-Dump erstellen

oxrun db:dump

Voraussetzung bei diesem Command ist, dass auf dem Rechner das Paket mysql-utilities installiert ist; dieses enthält das bekannte mysqldump tool.

  • Ein Aufruf mit oxrun db:dump macht dann natürlich einen kompletten 1-zu-1-Dump.
  • Es ist wirklich zu empfehlen, sich die Hilfe des Commands anzusehen. (oxrun db:dump –help) – dort gibt es noch mehr Beispiele.
  • Die „verbose option“ oxrun db:dump -v hilft zu verstehen, wie es gedumpt wird: Es wird angezeigt, wie der mysqldump Command auf gerufen wird.

oxrun db:anonymize

  • Dieser Aufruf anonymisiert die Datenbank nachträglich.
  • Bitte achtet darauf, dass dieser Aufruf keinesfalls im Produktivsystem gestartet wird!

Oder sicherer ist der Befehl oxrun db:dump –anonymous dabei wird direkt einen anonymisierten Dump erstellen, bei dem keine Bestellungen, Benutzer (inkl. aller Benutzerdaten) nicht mit exportiert werden. Da diese Felder leer bleiben, sollte nach einem Import oxrun user:create genutzt werden, um einen neuen Admin-Benutzer zu generieren.

3. Neues Modul erstellen

Einer meiner liebsten Commands ist oxrun module:generate. Seit OXID 6 ist es etwas knifflger geworden Module zu erstellen. Mit diesem Befehl wird ein neues Modulverzeichnis erstellt und gleich in composer.json registriert. Dadurch ist es sofort einsatzbereit und kann aktiviert werden. Danach kannst Du Dich direkt an die Programmierarbeit setzen.

Vorlage für das neue Modul ist das GitHub-Repository oxid-module-skeleton.

Tipp: Du kannst dieses Repository clonen und auf Deine eigene Modulvorlage anpassen. Du brauchst dazu lediglich die Option –skeleton= auf das neue Repository angeben.

Fazit

OXRUN als CLI-Tool für OXID eShop wird ständig weiterentwickelt und damit immer mächtiger. Hier findet Ihr eine Liste der bisher verfügbaren Commands, aber natürlich kann man OXRUN auch um eigene Befehle erweitern (Pull Requests welcome!).

Eine Idee wäre z.B. im Modulverzeichnis Befehle bereitzustellen, die eigens dafür konzipiert sind, Cronjobs abzuarbeiten. Damit könnte man leicht eigene Cronjobs über OXRUN starten 😉

Es gibt bereits ein weiteres, ähnliches Projekt namens „OXID Console„. Dieses Projekt wird zu oxrun migriert.

Happy Coding!



Start the discussion at OXID forums