Einleitung

Dieses Plugin integriert den Bild-Kompressions-Service von Tinify (TinyPNG) in Ihren JTL-Shop.

Hiermit können die Bilddateien ohne wahrnehmbare Qualitätsverluste in der Dateigröße reduziert werden, wodurch die Performance Ihres Shops verbessert wird.

Das Plugin unterstützt die folgenden Dateiformate:

• jpg, jpeg, jpe, jif, jfif, png und webp

Funktionsweise

Sie können im Plugin auswählen, welche Dateien (nach Bildgrößen für JTL-Wawi-spezifische Objekte, aber auch per Auswahl von Verzeichnissen) mit Tinify komprimiert werden sollen.

Das Plugin komprimiert nur bereits existierende Dateien und ersetzt diese auf dem Server.

Um unnötige doppelte Komprimierungen zu vermeiden, speichert das Plugin einen Hash der komprimierten Datei in einer Plugin-eigenen Datenbanktabelle.

Wird eine Änderung des Dateihashes erkannt (z.B. weil durch einen Wawi-Abgleich mit neuem Bild oder eine neue Bildgenerierung eine Datei verändert wurde), wird die Komprimierung für die Datei erneut ausgeführt.

Installation und Update

Systemvoraussetzungen

• JTL-Shop 5 (und die beinhalteten Bibliotheken und dessen Systemvoraussetzungen)

Weitere Voraussetzungen

Sie müssen bei Tinify (TinyPNG) registriert sein und einen API-Key für Tinify erstellt haben.

Plugin-Installation

Die Installation des Plugins erfolgt im Standardverfahren für JTL-Shop 5, wie es hier beschrieben ist.

Plugin-Update

Für ein Update laden Sie das Plugin wie bei einer Installation in der neuesten Version hoch (und überschreiben ggf. alle vorhandenen Plugin Dateien) oder folgen Sie den Hinweisen des Extension Stores.

Gehen Sie dann in die Plugin Verwaltung und betätigen Sie den Update-Button.

Konfiguration

Vorbereitung

Da das Plugin nur bereits existierende Dateien optimiert, sollten Sie im Shop möglichst alle Dateien, die dynamisch generiert werden (z.B. Produktbilder, Kategoriebilder, etc.) generiert haben. Dies passiert entweder durch Traffic auf Ihrem Shop oder Sie können diese Generierung im Shop-Admin unter Administration → Fehlerbehebung → Bilder durch anklicken der Generieren Buttons auslösen.

Einrichtung

Die Konfiguration des Plugins finden Sie im Plugin-Admin im Tab Einrichtung.

API-Key

Geben Sie hier den Tinify API-Key ein, den Sie hier erhalten können.

Max. Aufrufe pro Monat

Hier können Sie pluginseitig die maximalen Aufrufe pro Monat an die API begrenzen.

Cron-Modus

Steuert, wie der Cronjob des Plugins angesteuert werden soll:

aus

Der Cronjob wird nicht ausgeführt.

Sie können trotzdem manuell den Gesamtlauf ausführen: im Plugin-Admin oder per CLI Command

oder: Sie können das CLI Command als echten Cronjob auf dem Server ausführen lassen, falls Ihr Hosting das unterstützt (empfohlenes Vorgehen)

Wawi-Abgleich

Der Cronjob wird am Ende vom Wawi-Abgleich ausgeführt.

Dies kann den Wawi-Abgleich stark verlängern und ist die am wenigsten empfohlene Variante.

Cronjob

Der Cronjob wird zusammen mit anderen JTL Cronjobs ausgeführt.

Max. Komprimierungen pro Cron-Lauf

Steuert, wieviele Komprimierungen pro Cron-Ausführung durchgeführt werden sollen. Beachten Sie, dass die API-Aufrufe und Komprimierungen Zeit kosten und PHP nur eine begrenzte Ausführungszeit hat (außer, wenn es per Commandline ausgeführt wird). Um Fehler durch Überschreitung der Ausführungszeit zu verhindern, ist dieser Wert defensiv und niedrig zu wählen. (Mit der Zeit werden dabei trotzdem alle ausgewählten Dateien zur Komprimierung abgearbeitet.)

Denken Sie daran, die Einstellungen zu speichern!

Verzeichnisse / Dateiauswahl

Die Auswahl der zu komprimierenden Dateien ist in zwei Teile unterteilt, die separat von einander gepflegt werden können, aber beide im Tab Verzeichnisse im Plugin-Adminbereich zu finden sind.

Standard-Bilderverzeichnisse (media/image/…)

Hier können Sie für die Bilder, die aus der JTL-Wawi kommen und welche im OPC konfiguriert sind, jeweils auswählen, welche der Bildgrößen durch Tinify optimiert werden sollen.

Denken Sie daran, die Einstellungen zu speichern!

Verzeichnisauswahl

Hier sehen Sie einen Verzeichnisbaum Ihres Online-Shops und können für Verzeichnisse auswählen, ob diese auch für die Komprimierung berücksichtigt werden sollen. Manche ausgewählte Verzeichnisse sind von der Auswahl ausgenommen, weil sie niemals Bilddateien für das Frontend des Shops enthalten sollten.

Das Verzeichnis media/image/ ist hier auch nicht auswählbar, weil es durch die Standard-Bilderverzeichnisse abgedeckt ist.

Alternativ zur Verzeichnisauswahl können Sie auch über den Bereich Eigene Verzeichnisse direkt die Pfade der Verzeichnisse angeben, die Sie komprimieren wollen.

Die Änderungen in dieser Verzeichnisauswahl werden automatisch gespeichert!

Betrieb

Dashboard

Hier finden Sie Informationen zu den aktuellen Datenbanktabellen, zum Cronjob und die manuelle Komprimierung.

Tinify-Status

Hier zeigt das Plugin an, ob Ihr API-Key korrekt ist, ob die API erreichbar ist und, falls die API erreichbar ist, wieviele API-Aufrufe Sie diesen Monat bereits verbraucht haben.

Dateientabelle aktualisieren

Das Plugin speichert in einer Tabelle ab, welche Dateien zu komprimieren sind und welchen Hash eine bereits komprimierte Datei hat. Auf diese Weise erkennt das Plugin, ob sich Dateien geändert haben und erneut komprimiert werden müssen.

Zur eventuellen Fehlerbehebung können Sie die Dateientabelle manuell aktualisieren lassen. Im Normalfall sollte das aber nicht nötig sein.

Dateientabelle auf Auswahl reduzieren

Diese Aktion entfernt alle Dateien aus der Dateientabelle, die aktuell nicht ausgewählt sind. Hierdurch lässt sich die Tabelle optimieren und Überreste alter Daten entfernen, aber dies kann dazu führen, dass eigentlich bereits optimierte Dateien in Ihrem Shop erneut komprimiert werden, wenn diese später wieder in die Dateienauswahl aufgenommen werden. (Das Plugin kennt dann den Hash der komprimierten Datei nicht mehr und geht von einer erneuten notwendigen Komprimierung aus.)

Cronjob

Hier wird der aktuelle Status des Cronjobs angezeigt.

Cronjob zurücksetzen

Bestimmte Fehler können dazu führen, dass der Cronjob sich selbst deaktiviert, weil er erkennt, dass es keinen Sinn ergibt, wenn er weiter laufen würde (z.B. Probleme beim Schreiben von komprimierten Dateien - das würde die API-Aufrufe erhöhen, ohne tatsächlichen Nutzen zu bringen).

Mit Cronjob zurücksetzen können Sie die Ausführung des Cronjobs zurücksetzen, sodass dieser erneut läuft. Achten Sie darauf, bei bestimmten Fehlern zuerst die Ursache zu beseitigen - sonst wird der Cronjob wieder in denselben Fehler laufen.

Steuerung

Manuellen Gesamt-Durchlauf starten

Hiermit können Sie die Komprimierung für alle Dateien starten. Solange Sie im Adminbereich auf dieser Seite bleiben, läuft die Komprimierung weiter und der Status wird regelmäßig aktualisiert.

Wir empfehlen, diese Funktion auch zum Test der Funktionalität des Plugins auszuführen.

Sie können die Ausführung auch jederzeit beenden - dann wird nur das aktuelle Paket von Dateien noch zu Ende verarbeitet.

CLI-Commands

Falls Ihr Hosting es zulässt, können Sie auch die Kommandozeilen-Befehle des Plugins zum Betrieb verwenden. Diese sind i.d.R. performanter als Web-basierte Skripte und haben im Regelfall nicht das Problem, dass PHP auf eine maximale Ausführungszeit beschränkt ist.

Die Shop-CLI kann über php cli in Ihrem Shop-Verzeichnis ausgeführt werden. (Der genaue Aufruf von PHP variiert nach Hosting und kann hier nicht im Detail aufgezeigt werden - fragen Sie hierzu ggf. Ihren Hoster.)

Verfügbare Commands und Hilfe anzeigen

Mit dem Befehl php cli list s360_tinify_shop5 können Sie die Commands des Plugins anzeigen lassen.

Sie können die Hilfe pro Command (und Informationen zu unterstützten Parametern) mit dem Befehl php cli help s360_tinify_shop5:<Name des Commands> anzeigen lassen.

s360_tinify_shop5:cron:reset

Dieses Kommando setzt den Cron zurück. Analog zum Plugin-Admin Dashboard.

s360_tinify_shop5:cron:run

Führt den Cronjob des Tinify-Plugins aus.

Dieser Befehl sollte regelmäßig aufgerufen werden, wenn Sie echte Cronjobs per CLI ausführen lassen wollen.
Die Einstellung im Plugin-Admin für Cronjob sollte dann aus sein, da der Server und nicht der Shop die Cronjobs ansteuert.

s360_tinify_shop5:cron:status

Gibt den Cron-Status aus. Analog zum Plugin-Admin Dashboard.

s360_tinify_shop5:run

Dieser Befehl führt Tinify komplett für alle im Plugin-Admin ausgewählten Dateien aus. Entsprechend kann die Ausführung je nach Anzahl Dateien sehr lange dauern.

Dieser Befehl entspricht in etwa dem manuellen Gesamtlauf im Plugin-Admin Dashboard, ist jedoch performanter.

s360_tinify_shop5:status

Testet die Verbindung zu Tinify und gibt die Anzahl API-Aufrufe in diesem Monat aus. Entspricht im Wesentlichen der Statusanzeige im Plugin-Admin Dashboard.

Troubleshooting

Sollten Sie Probleme mit dem Plugin beobachten, prüfen Sie zunächst die Logs im Browser, Shop und Webserver und wenden Sie sich ggf. an unseren Support oder Ihren Service-Partner, wenn Sie das Problem nicht selbständig lösen können.

Je mehr Informationen Sie dem Support bei einem Problem geben können, desto eher sind wir in der Lage, Ihnen zu helfen. Nicht reproduzierbare Probleme sind dagegen auch nur schwer zu analysieren.

Logs prüfen

Um herauszufinden, wo ein Problem liegt, helfen Ihnen und uns die Logs. Je nach Fehlerbild ist eines der folgenden 3 Logs dafür mehr oder weniger relevant.

Browser-Log

Das Browser-Log ist meist relevant, wenn irgendwas im Frontend des Shops sich merkwürdig verhält oder nicht reagiert. (Beispiel: Sie klicken einen Button und augenscheinlich passiert gar nichts.)

Das Browser-Log sehen Sie, wenn Sie im Browser F12 drücken und dort dann auf Konsole (oder Console) wechseln.

Shop-Log

Das Shop-Log ist immer dann interessant, wenn im Frontend unerwartete Fehlermeldungen ausgegeben werden oder das Plugin zwar auf Eingaben im Frontend reagiert, aber nicht das Ergebnis liefert, was erwartet wurde. Manchmal ergibt sich auch durch das Browser-Log, dass die Informationen eher im Shop-Log zu suchen sind.

Das Shop-Log finden Sie im JTL-Adminbereich unter Administration→ Fehlerbehebung → Logbuch.

Webserver-Log

Das Webserver-Log wird dann relevant, wenn Sie irgendwo auf einen Error 500 (= weiße Seite) stoßen.

Das Webserver-Log kann Ihnen Ihr Hoster zur Verfügung stellen.

FAQ

Warum werden pro Cronjob-Lauf so wenige Artikel abgearbeitet?

Der Aufruf der API kostet Zeit und PHP hat, wenn es nicht auf der Command Line (CLI) läuft, nur eine begrenzte Ausführungszeit, nach welcher es mit einem Fehler abbricht. Um dieses Problem zu vermeiden, werden nur wenige Artikel pro Lauf bearbeitet. Da die Cronjobs aber regelmäßig laufen, werden mit der Zeit auf diese Art alle ausgewählten Dateien optimiert.

Alternativ können Sie den Lauf auch manuell im Plugin-Admin anstoßen (hier läuft er dann solange, bis er fertig ist, solange Sie die Plugin-Adminseite offen lassen) oder den Cronjob per CLI-Command ausführen.

Changelog

v1.0.0 (März 2024)

• Initiales Release

Support und Kontakt

siehe Support und Kontakt