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!



Replies

  1. Hi Tobi :slight_smile:

    finde OXRUN sehr gut.

    Würde gerne OXRUN um den Befehl erweitern einen Shop neu zu installieren. Glaube dies gab es bereits für die alte OXID Version.

    Wenn ich OXRUN als separates Command auf meinem Webserver installiere und oxrun list vom Root Verzeichnis meines Webservers aufrufe dann sehe ich nur die Commands help und list

    Zum Vergleich habe ich mir MAGERUN auf meinem Webserver hinterlegt, wenn ich dort im Root Verzeichnisses meines Webservers n98-magerun.phar list dann sehe ich eine unglaubliche Menge von Commands

    Hättest Du eine Idee woran es liegen könnte? Welche Datei im Repo ist hier relevant? Ich bin für jeden Tipp dankbar :slight_smile:

    Update: Lese gerade OXID v6 is required. orientiere mich an https://github.com/OXIDprojects/oxrun

  2. Ich bin einen Schritt weiter… Im bin/ Verzeichnis befindet sich oxrun Skript und dort werden über die Klasse CommandFinder die Commands angemeldet über die Hauptklasse Aggreator wofür 4 Unterklassen angelegt wurden sind. 3 dieser Unterklassen benötigen das Shop Verzeichnis vom OXID v6, also probiere ich meinen ersten Command über die letzte Klasse OxrunPass() bekannt zu machen und habe mich dort an der Beispiel Datei OwnOxrunCommand.php orientiert, leider führt dies zu keiner Veränderung wenn ich auf meinem Webserver ins bin/ Verzeichnis springe und php oxrun ausführe…

    $commandFinder = (new CommandFinder())
            ->addRegister(new Aggregator\CommunityPass(), true)
            ->addRegister(new Aggregator\ModulePass(),true)
            ->addRegister(new Aggregator\CustomPass(),true)
            ->addRegister(new Aggregator\OxrunPass());
    

    Ich habe oxrun geforked und meine neue Command Datei findet man unter https://github.com/Indianer3c/oxrun/blob/master/src/Oxrun/Command/BisWeb/InstallCommand.php

    Zusätzlich habe ich mir über Composer mit composer update das Vendor Verzeichnis mit den benötigten Klassen generieren lassen.

    Wenn ich nun auf meinem Webserver php oxrun im bin/ Verzeichnis ausführe erscheint immer noch kein einziger Befehl…

    Erhalte folgende Ausgabe:

    oxrun version @package_version@
    
    Usage:
      command [options] [arguments]
    
    Options:
      -h, --help               Display this help message
      -q, --quiet              Do not output any message
      -V, --version            Display this application version
          --ansi               Force ANSI output
          --no-ansi            Disable ANSI output
      -n, --no-interaction     Do not ask any interactive question
          --shopDir[=SHOPDIR]  Force oxid base dir. No auto detection
      -m, --shopId[=SHOPID]    Shop Id (EE Relevant)
      -v|vv|vvv, --verbose     Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
    
    Available commands:
      help  Displays help for a command
      list  Lists commands
    

    Habe ich bei meinem Vorgehen was übersehen? Oder verwende ich oxrun anders als es vorgesehen ist? Wie oben bereits geschrieben wäre ich über jeden Tipp dankbar :slight_smile:

    Update: Lese gerade den Blogeintrag aufmerksam erneut zu OXRUN

    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.

    Quelle: https://oxidforge.org/de/oxrun-das-konsolentool-zum-shop.html

    Dies erklärt natürlich warum auch mein Befehl nicht angezeigt wird…

  3. Hallo indianer3c,

    sorry das ich so spät antworte. Es freut mich rießig, dass du oxrun nutzen willst. Nunja wie du es bereits herausgefunden hast muss man sich im Installtaion verzeichnis vom OXID shop befinden. Ich habe es auch auch noch mal inder REDME hinterlegt: https://github.com/OXIDprojects/oxrun#usage
    Du kann kannst auch eine Globale Enviremnt Variable hinterlegen: OXID_SHOP_DIR=... dann funktioniert oxrun von überall aus.

    Um eigene Projekt Commands zu erstellen, gibt es mittlerweie 3 wege wo die Commands abegelegt werden können. Steht hier: https://github.com/OXIDprojects/oxrun#defining-your-own-command

    Ich nutze es sehr gerne um Module Command für Cronjobs tätigkeiten zu erstellen. Es ist dadurch sehr komfortafel richtige cli commands zu programieren mit paramerter und so.

    Hier bei ist zu achten das die gefunden Commands einmal zwischen gespeichert werden und dannach nicht mehr gesucht werden. Was wiederum bedeutet: fügst du einen neuen Command hinzu wird er nicht angezeigt. Ausser du löscht die Cache Datei vendor/oxidprojects/OxrunCommands.php. Dann fängt oxrun erneut nach den commands zu suchen.

    Der unterschied zwischen https://github.com/OXIDprojects/oxrun und dem Projekt von marcharding ist, dass OXIDprojects/oxrun auf v6.x geupdatet wurde und weiterentwickelt wird, und das Projekt von marcharding auf v4.x stehen geblieben ist für ältere OXID Version die noch existieren.

    Der OXID Installation Prozess habe ich nicht Portiert. Weil zu viele Fragen aufgeworfen sind, die ich nicht beantworten wollte. Gerne kannst du es gerne übernehmen, jedoch achte auf PHPUnit Tests.

    Viel freude und Spass mit oxrun. Für Verbesserungen und Bug fix gerne weiter entwickeln. Zusammen bauen wir ein cooles oxrun tool.

    Viele Grüße
    Tobi

  4. Hey Tobi :slight_smile: super dankeschön für die ausführliche Antwort. Das mit der globalen Environment Variable werde ich direkt mal testen und dann mein eigenen Command hinterlegen zum installieren, dazu auch die Cache Datei löschen

Continue the discussion at --> OXID forums

Participants