TYPO3 (Extension-) Debugging mit Eclipse und XDebug

Wie man generell PHP Projekte mit Eclipse und XDebug bearbeitet und debuggt habe ich bereits im Tutorial “PHP Entwicklung mit Eclipse” beschrieben. Bitte vorher lesen, da dort auch beschrieben ist, wie man XDebug installiert und verwendet. – Bei TYPO3 gibt es jedoch einen Fallstrick:

Man kann eine komplette TYPO3 Installation sehr einfach debuggen, indem man die gesamte TYPO3 Installation zu einem Eclipse PHP Projekt macht. Das funktioniert soweit sehr gut.

Wenn man nun aber die verschiedenen TYPO3 Extensions einzeln per Subversion (SVN) verwalten möchte geht dies nicht. Eclipse/Subclipse kann nur ganze Eclipse Projekte in SVN als Projekte bereitstellen (mittels “Team”->”Share Projekt…” im Kontextmenü des Projektes). Damit die Projekte einzeln per SVN verwaltet werden können, müssen sie auch als einzelne PHP Projekte in Eclipse angelegt sein. Beim obigen Beispiel (komplette TYPO3 Installation als Eclipse Projekt) geht dies jedoch nicht, da Eclipse es nicht zulässt Projekte zu verschachteln. In unserem Fall ist es also nicht möglich, TYPO3 als Gesamtprojekt, und die TYPO3 Extensions als Unterprojekte anzulegen.

Aber auch hierfür gibt es in Eclipse eine Lösung, zumal wir TYPO3 ja gar nicht als echtes eigenes Projekt bearbeiten wollen, sondern lediglich dessen Extensions (zumindest als Extension-Entwickler).

Wir gehen nun davon aus, dass die TYPO3 Installation im htdocs Verzeichnis des lokalen Webservers liegt (z.B. “C:\xampp\htdocs“) – die TYPO3 index.php also unter C:\xampp\htdocs\index.php zu finden ist. In Eclipse legen wir dementsprechend nun den Workspace auf das TYPO3 Extension Verzeichnis C:\xampp\htdocs\typo3conf\ext. Man kann dort bereits existierende TYPO3 Extensions öffnen, indem man im Eclipse PHP Explorer ein neues PHP Projekt anlegt (Rechtsklick im PHP Explorer, “New”->”PHP Project”), und als “Project Name” den Verzeichnisnamen der zu öffnenden Extension angibt. Dies kann man natürlich mit allen zu bearbeitenden Extension machen.

Um das Debugging für die einzelnen Extensions zu Nutzen müssen wir nun ein neues Projekt anlegen (“New”->”Project…”->”General”->”Project”), welches wir hier “_linkToTypo3Root” nennen wollen (kann natürlich frei gewählt werden). Dieses Projekt ist notwendig, da wir sonst in der Konfiguration des Debuggers nicht die TYPO3 index.php auswählen können. In diesem Projekt legen wir nun einen File-Link an:

  • “New”->”File” auswählen
  • Im Dialogfeld unten auf “Advanced >>” klicken
  • “Link to file in the filesystem” anwählen
  • Mittels “Browse” die TYPO3 index.php auswählen (in unserem Beispiel C:\xampp\htdocs\index.php)
  • Mit “Finish” den Link erzeugen

Nun müssen noch die TYPO3 Extensions in den Include Path des “_linkToTypo3Root”-Projektes eingebunden werden:

  • Rechtsklick auf das Projekt “_linkToTypo3Root” und “Properties” auswählen
  • Im sich öffnenden Fenster im Navigationsmenü “PHP Include Path” auswählen
  • Dort unter “Projects” mittels des Buttons “Add…” die TYPO3 Extensions einbinden
  • Fenster mit “OK” schließen

Nun geht es an die Konfiguration des PHP Servers:

  • Mittels klick auf “Windows”->”Preferences” in der Menüleiste die Eclipse Einstellungen öffnen.
  • Dann unter “PHP”->”PHP Servers” den Default Server auswählen und mit einem Klick auf “Edit” bearbeiten
  • Unter “Server” sollte die URL “http://localhost” lauten
  • Unter “Path Mapping” fügen wir nun die einzelnen Eclipse Projekte mit deren Pfad auf dem Server hinzu:
    • Bei einer lokalen Installation kann unter “Path on Server” entweder der absolute Pfad auf dem Server oder der Pfad relativ zum DocumentRoot angegeben werden.
    • Unter “Path in Workspace” wählt man das entsprechende Projekt aus
  • Zuerst fügen wir das “_linkToTypo3Root” Projekt hinzu: als “Path on Server” geben wir “C:\xampp\htdocs” an, und bei “Path in Workspace” wählen wir natürlich das Projekt “_linkToTypo3Root”
  • Das gleiche machen wir dann mit allen TYPO3 Extensions und deren entsprechenden Eclipse PHP Projekten. Um sich etwas Tipparbeit zu sparen kann hier auch einfach die relativen Pfade zum DocumentRoot angeben. Beispielsweise also /typo3conf/ext/my_extension für das Projekt “my_extension”
  • Zweimal mit “OK” bestätigen, und der PHP Server ist für das Debugging vorbereitet.

Jetzt fehlt uns nur noch die Debugger Konfiguration:

  • In der Menüleiste “Run”->”Debug Configurations…” auswählen.
  • Unter “PHP Web Page” mit einem Klick auf das Icon “New launch configuration” eine neue Konfiguration erstellen
  • Unter “Server” wählen wir als “Server Debugger”->”XDebug” aus.
  • Als File wählen wir mittels “Browse” aus dem Projekt “_linkToTypo3Root” die verlinkte index.php aus.
  • “Break at First Line” deaktivieren wir
  • Unter “URL” deaktivieren wir das “Auto Generate” und sorgen dafür, dass als URL http:// localhost/index.php eingetragen ist.

Das war’s. Breakpoint in der zu debuggenden Extension setzen (z.B. mittels Doppelklick im Editor am linken Rand in der gewünschten Zeile), und den Debugger z.B. mit F11 starten. Im sich öffnenden Browser kann man nun zu der Seite navigieren, auf welcher sich das Plugin befindet. Sollte sich kein externer Browser öffnen, kann man diesen über “Window”->”Preferences” und dann unter “General”->”Web Browser” mit “Use external web browser” aktivieren und auswählen.

TYPO3 als Bibliothek einbinden

Um im PHP Editor bei der Code-Completion auch die ganzen TYPO3 Klassen angezeigt zu bekommen muss das typo3src Verzeichnis als PHP Bibliothek verlinkt werden:

  • In der Menüleiste über “Window”->”Preferences” die Eclipse Einstellungen öffnen.
  • Unter “PHP”->”PHP Libraries” mittels “New…” eine neue Bibliothek anlegen (als “User library name” einfach “TYPO3” eingeben)
  • Nun die neue “TYPO3” Bibliothek markieren und mittels “Add external folder…” eine Referenz auf das typo3src Verzeichnis setzen (in unserem Beispiel auf C:\xampp\htdocs\typo3src)

Nun muss die TYPO3 Bibliothek noch in den einzelnen Projekten der TYPO3 Extensions verlinkt werden:

  • Dazu die Eigenschaften des gewünschten Projektes öffnen (Rechtsklick->”Preferences”)
  • Die Seite “PHP Include Path”->”Libraries” öffnen
  • Mittels “Add Library…”->”User Library” die eben erstellte “TYPO3” Library auswählen (mit Häkchen markieren) und dem PHP Projekt hinzufügen

Im PHP Editor stehen nun die verschiedenen TYPO3 Klassen zur Verfügung (t3lib_* und tslib_*).