smart | Webentwicklung
Alles rund um HTML5, PHP, WordPress & Co.

PHP: API-Doku mit PHPDocumentor & PHPStorm generieren

9. Januar 2013
Stephan
PHP-Projekt-Dokumentation (mittels PHPDocumentor) mit PHPStorm generieren

Sowohl bei größeren Projekten an denen mehrere Entwickler arbeiten als auch bei kleineren Projekten, ist es ratsam Code zu dokumentieren und eine API-Dokumentation zu erzeugen.

Für meine PHP-Pojekte bevorzuge ich hierfür PHPDocumentor. Da es doch sehr lästig ist, immer über einen Befehl in der Konsole PHPDocumentor auszuführen, zeige ich euch, wie ihr PHPDocumentor in PHPStorm integrieren könnt. Hat einfach den Vorteil, dass ich so direkt aus meiner IDE heraus die Doku für meine PHP-Projekte erzeugen kann.

Hinweis: Diese Anleitung bezieht sich auf die Installation sowie Einrichtung der benötigten Komponenten unter Windows 7 (64bit).

PHP installieren

Falls ihr noch kein PHP auf eurem System installiert habt, solltet ihr das nun nachholen. Dazu laden wir uns die neueste PHP Version – aktueller Stand zum Zeitpunkt als ich diesen Artikel schrieb ist PHP 5.4.3 – für Windows 64bit herunter: PHP 5.4.3 (Thread Safe).

Die heruntergeladene Zip-Datei entpacken wir nun in ein beliebiges Verzeichnis. Ich habe es bei mir unter D:/PHP5 entpackt.

Anschließend müssen wir das PHP-Verzeichnis unserem Systempfad hinzufügen. Hierfür klickt ihr in der Systemsteuerung von Windows der Reihenfolge nach auf:

  • System
  • Erweiterte Systemeinstellungen
  • Umgebungsvariablen

Im sich öffnenden Dialogfenster klickt ihr nun doppelt auf den Systemvariable-Eintrag „Path“ und fügt euren PHP-Pfad hinzu:

PHP-Pfad dem Windows Systempfad hinzufügen

Zum Testen ob alles funktioniert, öffnet die Windows-Konsole und tippt Folgendes ein:

php -v

Als Ausgabe solltet ihr die PHP Version, die ihr installiert habt, angezeigt bekommen.

Pear installieren

Diejenigen die neben PHP auch schon Pear installiert haben, können direkt zum nächsten Abschnitt übergehen. Alle anderen laden nun Pear herunter: Pear – go-pear.phar. Die heruntergeladene go-pear.phar-Datei kopiert ihr in euer PHP-Verzeichnis. In meinem Fall ist das D:/PHP5.

Als nächstes öffnet die Windows-Konsole und wechselt in das besagte Verzeichnis und führt diesen Befehl aus:

php go-pear.phar

Bei der Installation werdet ihr als erstes gefragt, ob die Pear systemweit oder nur lokal installiert werden soll. In meinem Fall habe ich es einfach bei systemweit belassen. Anschließend werden die jeweiligen Pfade der Installation angezeigt. Beim Eintrag 12 achtet darauf, dass euer PHP-Verzeichnis, indem sich die php.exe befindet, angegeben ist. Danach werdet ihr noch gefragt, ob eure php.ini aktualisiert werden soll, was ihr mit einem Y mit Ja quittiert.

Danach klickt ihr in eurem PHP-Verzeichnis auf die durch die Pear-Installation erzeugte PEAR_ENV-Datei. Dadurch werden automatisch die richtigen Systempfade gesetzt.

Jetzt können wir durch Aufruf von pear in unserer Konsole testen, ob alles funktioniert. Ist dem so, dann solltet ihr die verschiedenen Parameter für den pear-Befehl aufgelistet bekommen.

PHPDocumentor installieren

Keine Angst, die Installation von PHPDocumentor ist nicht so langwierig wie die von PHP und Pear. Öffnet eure Windows-Konsole und führt folgende zwei Befehle aus:

pear channel-discover pear.phpdoc.org
pear install --alldeps phpdoc/phpDocumentor-alpha

Das wars schon! Zum Testen könnt ihr einfach das Folgende in eure Konsole eintippen:

phpdoc

PHPDocumentor aus PHPStorm heraus ausführen

Nun kommen wir endlich zum letzten und eigentlichen Punkt: der Integration von PHPDocumentor in PHPStorm.

Als erstes öffnet PHPStorm und klickt dann der Reihenfolge nach auf:

  • File (Datei)
  • Settings (Einstellungen)
  • External Tools (Externe Werkzeuge)
  • + (Hinzufügen)

In dem erscheinden Dialogfenster gibt ihr nun alles so an, wie auf der folgenden Abbildung zu sehen:

PHPDocumentor in PHPStorm integrieren

Den Pfad zu eurer PHP-Installation müsst ihr gegebenenfalls anpassen. Außerdem müsst ihr den Pfad zu eurem PHP-Projekt anpassen. Nach -d folgt der Pfad zum PHP-Projekt und nach -t der Pfad zum Ausgabe-Verzeichnis. Also dem Verzeichnis, wo die PHP-Doc-Dateien gespeichert werden.

Nun können wir endlich PHPDocumentor direkt aus PHPStorm heraus ausführen. Dazu klickt einfach im Tools-Menü auf den Eintrag PHPDocumentor. Daraufhin wird eine PHP-Doku für euer Projekt erstellt.

Fazit

Anstatt nun jedes mal die Konsole öffnen zu müssen, um die Dokumentation für das eigene PHP-Projekt zu erstellen, reicht nun ein Klick in eurer Entwicklungsumgebung PHPStorm.

Falls ihr irgendwo nicht weiterkommen solltet bzw. sonstige Fragen habt, dann schreibt mir einfach ein Kommentar.

Kommentare  
2 Kommentare vorhanden
1 Stefan schrieb am 10. April 2013 um 13:18 Uhr

Hey,
vielen Dank für die Anleitung. Ich habe nur einen kleinen Verbesserungsvorschlag.

Und zwar kann man bei dem Feld „Parameters“ auch eine Variable benutzen für den Projekt-Pfad. Das sieht dann z.B. so aus:

phpdoc.php -d $ProjectFileDir$ -t $ProjectFileDir$\docs\api

Dann muss man nicht immer den Pfad ändern 😉

Getestet mit phpStorm 6.0

Gruß,
Stefan

2 Stephan L. schrieb am 10. April 2013 um 14:56 Uhr

Hallo Stefan,

danke für den tollen Tipp! Daran habe ich gar nicht gedacht, dass PHPStorm dafür auch Variablen bereitstellt. Wieder was neues dazu gelernt. 🙂

Grüße

Stephan

0 Trackbacks/Pingbacks vorhanden
Du bist herzlich eingeladen auch ein Kommentar zu hinterlassen!
Kommentar schreiben

Vielen Dank für dein Kommentar!