phpDocumentor
v3.5.3
phpDocumentor ist das De-facto-Dokumentationstool für PHP-Projekte und bietet eine robuste Lösung für die mühelose Erstellung umfassender Dokumentation. Durch die Analyse Ihres PHP-Quellcodes und der DocBlock-Kommentare generiert phpDocumentor eine vollständige API-Dokumentation und ist damit ein unverzichtbares Werkzeug für Entwickler, die nach klaren und gut dokumentierten Codebasen streben.
Über seine Fähigkeiten in der API-Dokumentation hinaus geht phpDocumentor noch einen Schritt weiter, indem es zusätzliche Funktionen bereitstellt. Es verfügt über die Möglichkeit, UML-Diagramme zu erstellen, was es zu einem vielseitigen Werkzeug zur Visualisierung der Codestruktur macht. Darüber hinaus bietet phpDocumentor einen Markup-Sprachparser mit vollem Funktionsumfang, der sowohl die RestructuredText- als auch die Markdown-Syntax unterstützt. Diese Flexibilität ermöglicht es Ihnen, Ihr Projekt mit der Auszeichnungssprache zu dokumentieren, die Ihren Vorlieben am besten entspricht.
Eine bemerkenswerte Funktion von phpDocumentor ist die Möglichkeit, Teile Ihrer API-Dokumentation direkt in Ihre RestructuredText-Dokumentation einzubinden. Durch diese Integration wird sichergestellt, dass Ihre Dokumentation und Ihr Code synchron bleiben, sodass Sie Zeit und Aufwand bei der Aufrechterhaltung einer genauen und aktuellen Projektdokumentation sparen.
Inspiriert von seinen Vorgängern phpDocumentor 1 und JavaDoc entwickelt phpDocumentor weiterhin Innovationen und bleibt mit den neuesten Technologien und PHP-Sprachfunktionen auf dem neuesten Stand. Dieses Engagement stellt sicher, dass Entwickler Zugriff auf die bestmögliche Dokumentationserfahrung haben, die mit modernen Entwicklungspraktiken übereinstimmt.
In diesem Leitfaden werden wir die verschiedenen Funktionen von phpDocumentor untersuchen, von seiner Kernfunktionalität beim Generieren von API-Dokumentation bis hin zu seinen erweiterten Funktionen beim Parsen von Auszeichnungssprachen. Egal, ob Sie Anfänger oder erfahrener Entwickler sind, phpDocumentor ist Ihr Verbündeter bei der Erstellung gut dokumentierter, wartbarer und verständlicher PHP-Projekte.
v3 ist die neueste stabile Version.
Ausführlichere Informationen finden Sie in unserer Online-Dokumentation unter https://docs.phpdoc.org/.
phpDocumentor unterstützt Folgendes:
PHP 7.0+-kompatibel , vollständige Unterstützung für Namespaces, Schließungen und mehr wird bereitgestellt.
Docblock über Typen , Docblocks können expliziter über Typen sein, nicht alle Formate werden von nativem PHP unterstützt.
Zeigt alle Tags an . Einige Tags fügen phpDocumentor zusätzliche Funktionen hinzu (z. B. @link).
Geringe Speichernutzung , die maximale Speichernutzung beträgt für kleine Projekte weniger als 20 MB, für mittlere Projekte 40 MB und für große Frameworks 100 MB.
Beim inkrementellen Parsen erhalten Sie, wenn Sie die Strukturdatei aus einem vorherigen Lauf beibehalten haben, zusätzlich zur oben erwähnten Erhöhung der Verarbeitungsgeschwindigkeit eine zusätzliche Leistungssteigerung von bis zu 80 %.
Einfache Vorlagenerstellung . Wenn Sie ein Branding erstellen möchten, müssen Sie nur eine Aufgabe aufrufen und drei Dateien bearbeiten.
In einem zweistufigen Prozess generiert phpDocumentor zunächst einen Cache mit Ihrer Anwendungsstruktur, bevor die Ausgabe erstellt wird. Wenn Sie möchten, können Sie damit Ihre eigenen Tools oder Formatierer betreiben!
Die Unterstützung von Generika mit mehr statischer Analyse in PHP-Typen ist komplexer geworden. phpDocumentor versteht diese Typen. Und wird sie als erstklassige Typen darstellen.
Für die Ausführung von PHPDocumentor ist PHP 8.1 oder höher erforderlich. Allerdings kann Code früherer PHP-Versionen analysiert werden.
Alle mit phpDocumentor bereitgestellten Vorlagen unterstützen Klassendiagramme basierend auf der gelesenen Codebasis. Dazu muss die Anwendung [PlantUml] auf dem Computer installiert sein, auf dem phpDocumentor ausgeführt wird. Das Rendern der Klassendiagramme mit [PlantUml] ist optional und Warnungen über fehlendes [PlantUml] können ignoriert werden. In diesem Fall enthält Ihre Dokumentation jedoch einige tote Links. Das Klassendiagramm wird mit der Option --setting=graphs.enabled=true erstellt.
Es gibt 4 Möglichkeiten, phpDocumentor zu installieren:
Verwendung von Phive (empfohlen)
Verwendung des PHAR (manuelle Installation)
Über Docker
Über Komponist
$ phive install phpDocumentor --trust-gpg-keys 8AC0BAA79732DD42
Weitere Informationen zu Phive finden Sie auf deren Website. Nachdem Sie phpDocumentor installiert haben, kann es wie folgt ausgeführt werden:
php tools/phpDocumentor
Laden Sie die Phar-Datei von https://github.com/phpDocumentor/phpDocumentor/releases herunter
Sie können den Phar wie folgt ausführen: php phpDocumentor.phar
$ docker pull phpdoc/phpdoc
$ docker run --rm -v $(pwd):/data phpdoc/phpdoc
Aber warten? Was ist mit dem Komponisten?
Ah, Sie haben unser Geheimnis entdeckt. Es gibt ein phpDocumentor Composer-Paket, mit dem Sie phpDocumentor installieren können.
Allerdings: phpDocumentor ist eine komplexe Anwendung und seine Bibliotheken werden in unzähligen anderen Bibliotheken und Anwendungen verwendet (zwei unserer Bibliotheken haben jeweils mehr als 150 Millionen Downloads); und das bedeutet, dass die Wahrscheinlichkeit eines Konflikts zwischen einer unserer Abhängigkeiten und Ihrer hoch ist. Und wenn ich hoch sage, dann ist es wirklich hoch.
Aus den oben genannten Gründen empfehlen wir weder die Installation von phpDocumentor mit Composer noch unterstützen wir diese aktiv.
Der einfachste Weg, phpDocumentor auszuführen, besteht darin, den folgenden Befehl auszuführen:
$ phpdoc run -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY>
Dieser Befehl analysiert den mit dem Argument -d bereitgestellten Quellcode und gibt ihn in den durch das Argument -t angegebenen Ordner aus.
phpDocumentor unterstützt eine ganze Reihe von Optionen, um die Ausgabe Ihrer Dokumentation zu konfigurieren. Sie können den folgenden Befehl ausführen oder auf unserer Website nach einer detaillierteren Liste der verfügbaren Befehlszeilenoptionen suchen.
$ phpdoc run -h
phpDocumentor unterstützt auch die Verwendung von Konfigurationsdateien (standardmäßig phpdoc.xml oder phpdoc.dist.xml genannt). Informationen zum Format und den unterstützten Optionen finden Sie in der Dokumentation.
PHPDocumentor verfügt nicht über nächtliche Veröffentlichungen. Allerdings wird bei jeder Pipeline ein Phar-Artefakt erstellt. Wenn Sie die neueste Version von phpDocumentor testen möchten, werfen Sie einen Blick in den Abschnitt „Aktionen“ dieses Repositorys. Jeder erfolgreiche QA-Workflow verfügt unten über einen Abschnitt „Artefakte“, in dem das Phar-Artefakt erstellt wird.
Die Kontaktaufnahme zu uns ist ganz einfach und kann wie folgt erfolgen:
Twitter: @phpDocumentor
Website: https://www.phpdoc.org
GitHub: https://www.github.com/phpDocumentor/phpDocumentor
E-Mail: [email protected]
