Laravel 5.7/6.x 的 PhpDocumentor

Question

这可能是一个非常新手的问题，但是，您究竟如何使用 phpDocumentor 通过 Laravel 生成文档？在我的 Laravel 项目中，vendor/bin 目录中没有 phpdoc，并且尝试通过 composer 安装 phpDocumentor 失败（如 GitHub 页面上的建议） .

我找不到任何关于它的最新资源，我唯一幸运的是运行来自终端的 phpDocumentor.phar 文件，但最新版本立即失败。

Answer 1

要使其正常工作，请降级到 PHP 7.1。然后从 [http://www.phpdoc.org/phpDocumentor.phar] 下载最新的 phpDocumentor.phar 文件。将 phpDocumentor.phar 放入您的 Laravel 6.x 项目的 /vendor/bin/ 目录中。

然后使用 Homebrew 安装其他需要的包...

brew install intltool
brew install graphviz

最后，cd 到 /vendor/bin 和运行...

php phpDocumentor.phar -d  ../../app/Http/Controllers

您的文档输出应该在 /vendor/bin/output.

Answer 2

添加一个更完整的解决方案，该解决方案适用于为我的 Laravel 项目创建文档，系统环境包括 MacOS Catalina、Laravel 6 和 PHP 7.2.

访问https://docs.phpdoc.org/3.0/guide/getting-started/installing.html。要安装依赖项，建议将自制软件更新为 brew update 和 brew upgrade。更新自制软件后，执行以下命令： brew install graphviz brew install plantuml
依赖安装完成后，从上面的link下载phpDocumentor.phar，并使文件可执行，如下所示： chmod +x phpDocumentor.phar 然后，将此文件复制并粘贴到 /vendor/bin 下的 laravel 应用中我还将此文件放在本地 bin mv phpDocumentor.phar /usr/local/bin/phpDocumentor 下以便于访问（如下面的第 6 步所示）。
出于测试目的，在 /vendor/bin/docs/test.php 目录下创建一个简单的 test.php 文件，其中包含 https://docs.phpdoc.org/3.0/guide/getting-started/your-first-set-of-documentation.html[= 中提到的以下内容25=]

<?php

    /**
     * This is a DocBlock.
     */
    function associatedFunction()
    {
    }

然后从与以下相同的 /vendor/bin 位置执行 phpdoc 脚本： phpDocumentor.phar -d docs/test.php -t docs/test 这将生成几个文件。
打开在您的网络浏览器中生成的 index.html 文件（例如 Chrome）以查看文档： open -a "Google Chrome" ./docs/test/index.html
值得注意的是，因为我们把phpDocumentor.phar放在了/usr/local/bin/phpDocumentor/phpDocumentor.phar中，我们可以轻松访问 phpdoc 并轻松创建我们整个应用程序的文档，如下所示（文档将存储在文件夹 DOCS 中） phpDocumentor.phar -d app/ -t DOCS/

Answer 3

我发现大多数 PHP 文档解决方案的问题是它们需要大量代码才能获得您可以实际使用的东西。这需要花费大量时间和反复试验来设置。

我对生成的文档也有疑问。通常它甚至没有排序！也很难导航和理解整个 class。作为 class 的消费者，您对私有甚至受保护的事物不感兴趣（除非您试图扩展它）。但通常文档只向您展示当前 class 的方法和属性，而不是它继承的内容（这是 OO 的全部要点！）。

无论如何，我厌倦了 PHP 文档的当前状态，并决定做对。我写了 PHPFUI/InstaDoc 来解决我在现有解决方案中遇到的所有问题。 InstaDoc 是最快的文档生成器，因为它只扫描 class 目录结构并将其保存。每次生成（发布时，或者如果您在开发环境中添加新的 class），这通常只需要几秒钟（对于大型代码库）。然后它在运行时间呈现特定 class 的文档，因为，嘿，反正谁看过文档？只有我们这些书呆子，人数不多，我们可以等待几分之一秒让服务器即时生成文档。此外，您不需要服务器磁盘 space 来存储您的所有文档。它们是动态生成的。当然，如果你有一个高容量的网站，InstaDoc 可以生成静态 HTML 文件，但是谁有一个高容量的 PHP 文档网站（就像没有人一样）。

无论如何，请查看 PHPFUI/InstaDoc 上的实例，看看它是否符合您的需要。它不是 Laravel 模块或插件，但您应该能够在 Laravel 下轻松地运行它。只是 return 控制器中控制器的输出，它应该可以正常工作。

Laravel 5.7/6.x 的 PhpDocumentor

PhpDocumentor for Laravel 5.7/6.x

php

phpdoc

laravel

laravel-5.7

laravel-6