Hilfe, in Magento 1 funktioniert [Feature] nicht – was kann ich tun?

Aus aktuellem Anlass (= ich ertrinke gerade in Anfragen) ein Blogpost nach dem Motto „Hilfe zur Selbsthilfe„.

Wie löse ich mein Problem in Magento?

Bevor ich falsche Hoffnungen wecke: ich habe natürlich keine Geheimformel, die jeden Fehler aufdeckt und behebt. (Wenn ich die hätte, säße ich nicht mehr hier, sondern an einem Strand und würde mir die Sonne auf den Pelz brennen lassen. Wahrscheinlich mit einem Laptop gleich hinten unter einer schattigen Palme. :-))

Viele Probleme lassen sich jedoch mit etwas Recherche und Unterstützung der persönliche Lieblingssuchmaschine beheben, wenn man weiß, wie man an Fehlermeldungen kommt und wie man häufige Fehler vermeidet. (Hinweis: für jedes generische „Das funktioniert nicht“ stirbt ein kleines Kätzchen, habe ich gehört.)

Eine Grundregel der Software-Entwicklung und -Anwendung lautet: wenn man ein Problem hat, ist die Chance groß, dass es jemand anderer schon zuvor gehabt hat. Nun liegt die Kunst darin herauszufinden, was das Problem ist und wie es gelöst wird. Folgende Fragen sollte man sich stellen:

1. Habe ich den Cache gelöscht?

Die wohl häufigste Gegenfrage auf eine Problemmeldung bei Magento: „haben Sie schon den Cache geleert?“

Ein Cache ist ein Zwischenspeicher. Er dient zur Beschleunigung von Vorgängen und kann gerade bei Magento einiges an Performance bringen. Probleme können jedoch auftreten, wenn ein Cache veraltete Einträge enthält oder dazu führt, dass Änderungen nicht erkannt werden.

Für Magento sind diverse Caches relevant, darunter:

a. Magento-interner Cache

Die obige Frage bezieht sich zumeist auf den Magento-internen Cache. Er speichert die Konfiguration, Teile der Shop-Seiten, Übersetzungen und vieles mehr. Das führt mitunter dazu, dass Änderungen scheinbar nicht wirksam oder neu-installierte Erweiterungen nicht aktiv werden.
Dieser Cache wird im Magento-Backend über „System > Cache Management“ unter „Cache Storage Management“ geleert. Wer weiß, was er tut (!), kann zudem die Dateien unter var/cache löschen sowie gegebenfalls manuell die Caches anderer verwendeter Cache-Backends (APC, memcached, Redis, MySQL-Datenbank, …) leeren.

b. Bytecode-Cache

Ein weiterer Fallstrick sind bytecode caches wie APC, die bei falscher Konfiguration dazu führen können, dass eine alte Version des PHP-Codes verwendet wird. Viele Hoster verwenden bytecode caches, da dank ihnen der PHP-Programmcode nicht bei jedem Seitenaufruf neu analysiert werden muss, was zu einem bemerkenswerten Performance-Gewinn führen kann. Eine Extension fügt dem Cache-Management einen Button hinzu, um den bytecode cache zu leeren.

c. Gecachte Bilder, CSS- und JavaScript-Dateien

Ebenfalls im Backend unter „System > Cache Management“ können im Abschnitt „Additional Cache Management“ vorberechnete Produktbilder und zusammengefasste JS-/CSS-Dateien gelöscht werden, falls die Vermutung besteht, dass veraltete Dateien ausgeliefert werden.

Werden auch nach dem Löschen alte Daten verwendet, kann es sein, dass der Browser aufgrund falsch gesetzter Expires-Header keine aktuellen Daten anfordert. Der Webserver schickt den Expires-Header an den Web-Browser (bei Apache z.B. über das Modul mod_expires) und teilt ihm mit, wie lange er diese Datei nicht mehr vom Server abrufen muss, sondern direkt seine lokal gespeicherte Kopie verwenden darf.  Eine Extension sorgt dafür, dass zumindest bei kombinierten CSS- und JS-Dateien immer die richtige Version angefordert wird, indem bei jeder Dateiänderung ein eindeutiger Dateiname erzeugt wird.

2. Habe ich die Magento-Fehlermeldungen untersucht?

Wer im Backend unter „System > Configuration > Advanced > Developer > Log Settings“ die Option „Enabled“ auf „Yes“ setzt, erhält in den Dateien [magentoverzeichnis]/var/log/system.log bzw. [magentoverzeichnis]/var/log/exception.log Log-Meldungen, die vom Magento-Code produziert werden. Die Meldungen reichen von reinen Hinweisen über Geschehnisse im Shop-System bis zu genauen Fehlermeldungen. Verwendet man die dort protokollierten Meldungen für Suchmaschinensuchen, dann wird man oft fündig.

Fehlermeldungen werden zudem im Verzeichnis var/report aufgezeichnet. Pro fehlerhaftem Seitenaufruf wird eine Datei erzeugt. Der Inhalt der Dateien ist wiederum ein Fundus für die Suche mit Google und co.

Wer über eine Test-Installation seines Shops verfügt, kann zusätzlich die Server-Umgebungsvariable MAGE_IS_DEVELOPER_MODE und die PHP-Konfiguration display_errors setzen. Sie sorgen dafür, dass einem Fehlermeldungen direkt auf dem Bildschirm angezeigt werden, anstatt dass man nur eine weiße Seite erhält oder sich durch die Report-Dateien wühlen muss. (Aus demselben Grund muss man darauf achten, dass man diese Einstellungen nicht unreflektiert ins Live-System übernimmt.)

3. Ist mein XML-Code valide?

Die Magento-XML-Konfiguration ist knifflig. Ein Tippfehler ist leicht passiert. Das XML ist dann nicht mehr valide bzw. „wohlgeformt“ und wird von Magento ignoriert. Hat man XML-Code geschrieben, der nicht tut, was er soll, dann ist validieren angesagt. Beim Validome-XML-Validator den gesamten XML-Code der Datei in das „Quellcode“-Formularfeld kopieren, die Option „Nur auf Wohlgeformtheit prüfen“ auswählen und los geht’s.

4. Habe ich alle Dateien und Ordner richtig angelegt, dabei auf die Groß-/Kleinschreibung geachtet?

Jede Datei muss am richtigen Ort sein. Die Groß-/Kleinschreibung muss überall richtig sein. Bei Ordernamen. Bei Dateinamen. Bei Klassendefinitionen. In XML-Dateien. Ü-B-E-R-A-L-L.

Und wenn man sich noch so sicher ist, dass man alles richtig gemacht hat: wenn der Code nichts bewirkt, noch einmal stupide Buchstabe für Buchstabe kontrollieren. Wer die Caches geleert hat, keine Fehlermeldungen erhalten hat und keinen XML-Fehler gemacht hat, hat ganz gute Chancen, dass die Groß-/Kleinschreibung ihm einen Strich durch die Rechnung macht. Im Gegensatz zu Windows-Systemen kennen Linux-Systeme (auf denen Webserver normalerweise laufen) nämlich keine Toleranz.

Natürlich müssen die Dateien auch am richtigen Ort erstellt werden. Ein paar grobe Hinweise:

• Die eigene Extension muss in app/code/community oder app/code/local abgelegt werden. Ob der Code-Pool „community“ oder „local“ verwendet wird, wird in der XML-Aktivierungsdatei festgelegt.
• Magento sucht Dateien in unterschiedlichen Verzeichnissen. Die Reihenfolge lautet:
  1. app/code/local/
  2. app/code/community/
  3. app/code/core/
  4. lib/

  Hat man den Eindruck, dass eine Datei trotz richtiger Platzierung nicht geladen wird, dann sollte man überprüfen, ob es eine gleichnamige Datei in einem höher priorisierten Verzeichnis gibt.

• Die Template-Dateien, die vorrangig für die Generierung des HTML-Codes zuständig sind, liegen in app/design. Es ist darauf zu achten, dass die Dateien im richtigen Theme (oder einem Fallback-Theme) abgelegt sind.

5. Habe ich ausgeschlossen, dass andere Extensions schuld sind (bzw. meine neue Extension das Problem verursacht)?

Extensions werden deaktiviert, indem in der jeweiligen XML-Aktivierungsdatei (die im Verzeichnis [magentoverzeichnis]/app/etc/modules) die Zeile

<active>true</active>

auf

<active>false</active>

umgestellt wird. Im Backend können zwar über den Menüpunkt „System > Configuration > Advanced > Advanced“ Modulausgaben deaktiviert werden, aber das deaktiviert nicht die Extension an sich!

Über diese Methode kann erstens die neueste / in Entwicklung befindliche Extension deaktiviert werden, um zu überprüfen, ob sie Probleme verursacht. Zweitens können gleich mehrere Extensions deaktiviert werden, um festzustellen, ob es zu Konflikten kommt bzw. andere Extensions schuld sind.

Je größer die Anzahl der eingesetzten Extensions, desto größer ist die Gefahr von Rewrite Conflicts. Die Extension firegento-debug hilft dabei, Abhängigkeiten zwischen Modulen und Rewrite-Konflikte festzustellen.

6. Habe ich die angegebene Magento-Version verwendet?

Im WWW gibt es viele Lösungen für viele verschiedene Magento-Versionen. Leider ändert sich der Magento-Code immer wieder so, dass der Code für Magento 1.5 nicht mehr in Magento 1.6 oder 1.7 funktionieren muss.

7. Kann ich das Problem auf einer ansonsten originalen Magento-Installation nachvollziehen?

Diese Frage ist eine Erweiterung von Frage Nr. 5 und insbesondere für Fehler relevant.

Selbst wenn Magento wie jede Software seine Fehler hat, muss man im ersten Schritt davon ausgehen, dass das Ding funktioniert. Ist man bis hierher gekommen, wäre es also an der Zeit, eine frische Testinstallation aufzusetzen und nur die allernötigsten Anpassungen vorzunehmen, um zu überprüfen, ob der Fehler / das Phäomen dann auch noch auftritt. (Hint: zu dem Schritt muss ich in den meisten Fällen greifen, wenn mich jemand etwas zu seinem Shop fragt.)

Wer häufiger in diese Lage kommt, könnte von MageSpawner profitieren.

Läuft auf der Testinstallation alles wie gewünscht, ist der Fehler in den Modifikationen zu suchen.

Und wenn ich immer noch ein Problem habe?

Wenn diese Schritte durchgeführt worden sind und Google selbst unter Gewaltandrohung kein brauchbares Suchergebnis herausrückt, dann, ja dann kann man sich langsam mit dem Gedanken anfreunden, sich mit ausführlichen Informationen aus den obigen Schritten und viel Geduld und Verständnis an Magento @ Stack Exchange, ein Forum oder gar eine/n fleißige/n Blogger/in zu wenden. 😉