Tutorial: Dein erstes modified eCommerce Shop Modul mit dem MMLC programmieren

Bearbeitungszeit: ca. 25 min.

In diesem Tutorial lernst du, wie du per Hand ein eigenes Modul für einen modified eCommerce Shop mit der Hilfe des MMLC programmieren kannst. Dazu werden dir alle Schritte gezeigt, die du hierfür kennen solltest. Es ist empfehlenswert, das einmal selber zu machen, um ein generelles Verständnis für die einzelnen Komponenten zu erlangen.

Vorbedingungen #

• Du hast eine lokale Enwicklungsumgebung aufgesetzt.
• Du hast eine modified-shop Version 2.0.7.2 oder höher installiert.
• Du hast den MMLC 1.23.0 oder höher installiert und kannst Module installieren.
• Du hast einen Code Editor wie VS Code oder PhpStorm.
• (Optional aber empfohlen) Du hast git installiert und kannst die einfachen Basics.

Los gehts #

Stelle dir vor du hast eine Firma mit dem Namen "My Company" und diese Firma möchte ein neues Modul mit dem Namen "Mein erstes Modul" entwickeln.

Verzeichnisstruktur erstellen #

Gehe in das Verzeichnis ModifiedModuleLoaderClient, welches du im Root-Verzeichnis deines Shops findest.

Wir erstellen als erstes einen neuen Vendor-Ordner im Verzeichnis ./Modules. Den Ordner nennen wir my-company. In diesem Vendor-Ordner liegen später alle Module, die du entwickelst. Module von anderen Entwicklern liegen in deren jeweiligen Vendor-Ordnern, welche sich ebenfalls in dem Verzeichnis ./Modules befinden. Wenn du noch keine Module von einem anderen Entwickler installiert hast, gibt es nur deinen Vendor-Ordner.

Als nächstes erstellen wir einen neuen Modul-Ordner im Verzeichnis ./Modules/my-company. Den Modul-Ordner nennen wir my-first-module.

Bei dem Modul-Namen handelt es sich um den technischen Namen des Moduls. Das ist nicht der Name, der dem User später angezeigt wird. Den Anzeigename legen wir im nächsten Schritt fest. Die Verzeichnisstruktur sollte jetzt folgendermaßen aussehen:

# Verzeichnisstruktur
└── Modules
    └── my-company
        └── my-first-module

moduleinfo.json erstellen #

Nun erstellen wir in dem neuen Modul-Ordner die moduleinfo.json Datei.

Die moduleinfo.json Datei füllen wir mit folgendem Inhalt (achte auf die geschweiften Klammern):

{
    "name": "Mein erstes Modul",
    "archiveName": "my-company/my-first-module",
    "srcDir": "src",
    "version": "auto",
    "modifiedCompatibility": [
        "3.1.5"
    ]
}

Das Feld name können wir frei wählen. Das ist der Anzeigename für den User im MMLC. Das Feld archiveName muss der Vendor-Ordner-Name und der Modul-Ordner-Name getrennt mit einem Slash-Zeichen sein. In unserem Fall ist das my-company/my-first-module.

Nachdem du die Datei gespeichert hast, wird dir das Modul im MMLC unter "Sonstige Module" angezeigt. Gehe in den MMLC, um dir das Modul anzeigen zu lassen.

Git Repository erstellen (optional aber empfohlen) #

Wenn bis hierhin alles geklappt hat, ist es eine gute Gelegenheit den aktuellen Zwischenstand mit git zu speichern. Erstelle im Verzeichnis ./Modules/my-company/my-first-module ein neues git-Repository. Das kannst du z. B. über die Konsole machen oder mit einem git-Tool wie SourceTree. Hier das Beispiel mit der Konsole:

> cd ./Modules/my-company/my-first-module
> git init
> git add .
> git commit -m "feat: Initialer commit"

Dateien für ein System Modul erstellen #

Wenn du es bis hier geschafft hast, können wir uns an die Arbeit machen, alle nötigen Dateien zu erstellen, die ein Modified Shop für ein System Modul benötigt.

Wie wir in der moduleinfo.json Datei sehen können, haben wir für das Feld srcDir das Verzeichnis src eingetragen. In diesem Verzeichnis befinden sich später alle Dateien, die der MMLC in das Modified Shop System bei einer Installation kopieren/verlinken soll. Lege jetzt das Verzeichnis src in ./Modules/my-company/my-first-module bzw. in ... an.

Für ein System Modul benötigt das Modified System eine PHP Datei in dem Verzeichnis SHOP_ROOT/admin/includes/modules/system/. Damit der MMLC diese Datei in dieses Verzeichnis kopiert/verlinkt, müssen wir das Verzeichnis in .../src anlegen. Wir legen also die Verzeichnisstruktur .../src/admin/includes/modules/system/ an.

Jetzt können wir anfangen unsere erste PHP HookFile Datei zu erzeugen. Eine HookFile Datei ist eine Datei, die der MMLC bei der Installation eines Moduls in den Shop kopiert und nicht im Ordner SHOP_ROOT/vendor-mmlc landet. Der Dateiname einer HookFile sollte wenn möglich immer mit dem VendorPrefix beginnen. Für den VendorName my-company bietet sich das VendorPrefix mc an.

Mit diesem Wissen nennen wir die neue Datei mc_my_first_module.php und speichern diese in das eben erstellte Verzeichnis .../src/admin/includes/modules/system/. Jetzt sollte deine Verzeichnisstruktur folgendermaßen aussehen:

...
├── moduleinfo.json
└── src
    └── admin
        └── includes
            └── modules
                └── system
                    └── mc_my_first_module.php

Die StdModule Klasse #

In die Datei mc_my_first_module.php schreiben wir folgenden PHP Code:

<?php

use RobinTheHood\ModifiedStdModule\Classes\StdModule;

class mc_my_first_module extends StdModule
{
    public function __construct()
    {
        parent::__construct('MODULE_MC_MY_FIRST_MODULE');
    }

    public function display()
    {
        return $this->displaySaveButton();
    }

    public function install()
    {
        parent::install();
    }

    public function remove()
    {
        parent::remove();
    }
}

Durch diese Datei wird uns das Module im Shopbackend unter dem Menüpunkt Module > System Module angezeigt. Damit diese Datei mit den wenigen Zeilen Programmcode auskommt, verwenden wir das Library Modul Standard Modul für Modified.

Warum StdModule? Das Standard Modul für Modified spart dir wiederholte Boilerplate wie Install/Remove-Logik, Statusverwaltung und Button-Ausgabe. Du konzentrierst dich auf deine eigentliche Funktionalität. Wobei dir das Modul alles hilft ist unter Dokumentation zur StdModule-Klasse beschrieben.

Für uns ist erst einmal wichtig, dass wir das Modul mit der Konstanten MODULE_MC_MY_FIRST_MODULE initialisieren.

Abhängige Module in die moduleinfo.json hinzufügen #

Damit wir das Modul Standard Modul für Modified verwenden können, müssen wir es als Abhängigkeit in unserer moduleinfo.json hinzufügen. Auch brauchen wir das Composer Autoload Library Modul. Beide Module fügen wir durch das require Array in unserer moduleinfo.json hinzu.

"require": {
    "composer/autoload": "^1.9.0",
    "robinthehood/modified-std-module": "^0.16.0"
}

Danach sollte die gesamte moduleinfo.json wie folgt aussehen:

{
    "name": "Mein erstes Modul",
    "archiveName": "my-company/my-first-module",
    "srcDir": "src",
    "version": "auto",

    "modifiedCompatibility": [
        "3.1.5"
    ],

    "require": {
        "composer/autoload": "^1.9.0",
        "robinthehood/modified-std-module": "^0.16.0"
    }
}

Sprachdatei für das System-Modul erstellen #

User System Modul benötigt noch eine Sprachdatei, damit der User etwas angezeigt bekommt. Die Sprachdatei muss später in dem Verzeichnis SHOP_ROOT/lang/german/modules/system liegen. Damit der MMLC diese Datei in dieses Verzeichnis kopiert/verlinkt, müssen wir das Verzeichnis in .../src anlegen. Wir legen also die Verzeichnisstruktur .../src/lang/german/modules/system/ an.

Die Sprachdatei bennen wir wieder nach der HookFileName Convention mc_my_first_module.php und speichern diese in das eben erstellte Verzeichnis .../src/lang/german/modules/system/. Jetzt sollte deine Verzeichnisstruktur folgendermaßen aussehen:

...
├── moduleinfo.json
└── src
    ├── admin
    |   └── includes
    |       └── modules
    |          └── system
    |              └── mc_my_first_module.php
    └── lang
        └── german
            └── modules
                └── system
                    └── mc_my_first_module.php

Der Inhalt der Datei sieht wie folgt aus:

<?php
define('MODULE_MC_MY_FIRST_MODULE_TITLE', 'Mein erstes Modul');
define('MODULE_MC_MY_FIRST_MODULE_LONG_DESCRIPTION', 'Beschreibung ...');
define('MODULE_MC_MY_FIRST_MODULE_STATUS_TITLE', 'Modul aktivieren?');
define('MODULE_MC_MY_FIRST_MODULE_STATUS_DESC', '');

MMLC config.php von copy auf link umstellen #

Wenn du es bis hier geschafft hast, könnten wir jetzt bereits unser neues Modul mit dem MMLC installieren. Das Problem ist nur, dass wir bei jeder Änderung, die wir an einer Datei in unserem Ordner src machen würden, wieder erneut auf "Installieren" im MMLC klicken müssten. Das macht auf Dauer keinen Spaß.

Aus diesem Grund können wir bei der Entwicklung von Modulen den MMLC so konfigurieren, dass er die Dateien aus dem src Ordner nicht in den SHOPT_ROOT kopiert, sondern die Dateien nur verlinkt. Das hat den großen Vorteil, dass jede Änderung, die wir an einer Datei im Ordner src machen auch direkt in der entsprechenden Datei in SHOP_ROOT verfügbar wird. Lediglich, wenn wir eine neue Datei im Ordner src hinzufügen, müssen wir einmal auf "Installieren" oder auf "Änderungen verwerfen" im MMLC klicken, damit der MMLC auch diese neue Datei in den SHOPT_ROOT verlinkt.

Die Konfiguration hierfür können wir in der /config/config.php deines MMLCs vornehmen. Ändere das Feld installMode auf den Wert link. Jetzt verlinkt der MMLC deine Dateien, anstatt die Dateien zu kopieren.

Deine config.php sollte wie folgt aussehen:

<?php
$configuration = [
    // ...
    'installMode' => 'link',
    // ...
];

Modul im MMLC installieren #

Nach dem wir alle Dateien für unser Systemmodul erstellt haben und die nötigen Einstellungen im MMLC gemacht haben, können wir unser Modul installieren. Dazu rufen wir wieder den MMLC auf, suchen in der Suche unser Moduel "Mein erstes Modul" und klicken es an. Jetzt können wir auf der Moduldetailseite unser Modul installieren.

Modul im Shopbackend installieren #

Damit wir das Modul nutzen können, müssen wir unser Modul ebenfalls im Shopbackend installieren. Das Modul befindet sich unter Admin > Module > System Module. (Dein Modul erscheint möglicherweise etwas weiter unten in der Liste.)

Modul veröffentlichen #

Herzlichen Glückwunsch, wenn du es bis hierher geschaft hast. Du hast dein erstes Modul für den MMLC programmiert. Es ist nur sehr schade, wenn keiner etwas davon erfährt. Als nächstes kannst du dir anschauen, wie du dein Modul im MMLC veröffentlichst, so das es bei allen im MMLC erscheint, die den MMLC installiert haben.

Tutorial: Dein erstes Modul veröffentlichen