README

phpDocumentor

什么是 phpDocumentor？

phpDocumentor 是 PHP 项目的默认文档工具，提供了一种强大的解决方案，可以轻松生成全面的文档。通过分析您的 PHP 源代码和 DocBlock 注释，phpDocumentor 生成一套完整的 API 文档，成为力求代码库清晰和详尽的开发者不可或缺的工具。

除了 API 文档的强大功能之外，phpDocumentor 还提供了其他功能。它具有创建 UML 图的能力，使其成为可视化代码结构的多功能工具。此外，phpDocumentor 提供了一个功能齐全的标记语言解析器，支持 RestructuredText 和 Markdown 语法。这种灵活性允许您使用最适合您偏好的标记语言来记录项目。

phpDocumentor 的一个显著特点是它可以将 API 文档的部分内容直接包含到 RestructuredText 文档中。这种集成确保了文档和代码保持同步，节省了您在维护准确和最新的项目文档中的时间和精力。

受其前辈 phpDocumentor 1 和 JavaDoc 的启发，phpDocumentor 继续创新，保持与最新技术和 PHP 语言特性的同步。这种承诺确保开发人员能够获得最佳的文档体验，符合现代开发实践。

在本指南中，我们将探讨 phpDocumentor 的各种功能，从生成 API 文档的核心功能到解析标记语言的先进功能。无论您是初学者还是有经验的开发者，phpDocumentor 都是您创建良好记录、易于维护和理解的 PHP 项目的盟友。

phpDocumentor v3（稳定版）

v3 是最新稳定版。

文档

有关更详细的信息，您可以在我们的在线文档中查看 https://docs.phpdoc.org/。

功能

phpDocumentor 支持以下功能

• PHP 7.0+ 兼容，提供对 Namespaces、Closures 等的全支持。
• Docblock 类型覆盖，docblocks 可以更明确地表示类型，但不是所有格式都受原生 PHP 支持。
• 显示任何标签，一些标签为 phpDocumentor 提供了额外的功能（例如 @link）。
• 低内存使用，小型项目的峰值内存使用量小于 20MB，中型项目 40MB，大型框架 100MB。
• 增量解析，如果您保留了上一次运行的结构文件，您将获得额外的性能提升，最高可达 80%，在上述提到的处理速度提升之上。
• 易于构建模板，如果您想进行品牌定制，您只需调用 1 个任务并编辑 3 个文件。
• 两步过程，phpDocumentor 首先生成您的应用程序结构的缓存，然后再创建输出。如果您愿意，可以使用它来为您的工具或格式化程序提供动力！
• 泛型支持，随着 PHP 类型在静态分析中变得更加复杂，phpDocumentor 理解这些类型。并将它们作为一流类型呈现。

安装

PhpDocumentor 需要 PHP 8.1 或更高版本才能运行。但是，可以分析早期 PHP 版本的代码。

phpDocumentor 提供的所有模板都支持基于读取代码库的类图。这需要在运行 phpDocumentor 的机器上安装 [PlantUml] 应用程序。使用 [PlantUml] 渲染类图是可选的，可以忽略关于缺少 [PlantUml] 的警告。然而，在这种情况下，您的文档将包含一些无效链接。类图将使用选项 --setting=graphs.enabled=true 创建。

安装 phpDocumentor 有 4 种方法

1. 使用 phive（推荐）
2. 使用 PHAR（手动安装）
3. 通过 Docker
4. 通过 Composer

使用 Phive

$ phive install phpDocumentor --trust-gpg-keys 8AC0BAA79732DD42

有关 phive 的更多信息，请访问他们的 网站。现在您已安装 phpDocumentor，可以像这样执行

php tools/phpDocumentor

使用 PHAR

1. 从 https://github.com/phpDocumentor/phpDocumentor/releases 下载 phar 文件
2. 您可以像这样执行 phar：php phpDocumentor.phar

通过 Docker

1. $ docker pull phpdoc/phpdoc
2. $ docker run --rm -v $(pwd):/data phpdoc/phpdoc

通过 Composer（不推荐）

但是，Composer 呢？

啊，您发现了我们的秘密。有一个 phpdocumentor composer 包，您可以使用它来安装 phpDocumentor。

然而：phpDocumentor 是一个复杂的应用程序，其库被无数其他库和应用使用（我们的两个库各有超过 1.5 亿次下载）；这意味着我们的依赖与您的依赖发生冲突的可能性很高。当我说是很高的时候，确实是很高的。

因此，鉴于上述原因：我们不推荐也不积极支持使用 Composer 安装 phpDocumentor。

如何使用 phpDocumentor？

运行以下命令是运行 phpDocumentor 的最简单方式

$ phpdoc run -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY>

此命令将解析使用 -d 参数提供的源代码，并将其输出到由 -t 参数指示的文件夹。

phpDocumentor 支持一系列选项来配置文档的输出。您可以执行以下命令，或检查我们的网站，以获取可用的命令行选项的更详细列表。

$ phpdoc run -h

配置文件

phpDocumentor 还支持使用配置文件（默认情况下命名为 phpdoc.xml 或 phpdoc.dist.xml）。请参阅文档以了解格式和支持的选项。

夜间构建

PhpDocumentor 没有夜间版本。然而，在每次管道中都会构建一个 phar 艺术品。如果您想测试 phpDocumentor 的最新版本，请查看此存储库的 操作 部分。每个成功的 QA 工作流底部都有一个包含构建的 phar 艺术品的 艺术品 部分。

联系

联系我们很容易，可以通过

• Twitter: @phpDocumentor
• 网站: https://www.phpdoc.org
• GitHub: https://www.github.com/phpDocumentor/phpDocumentor
• 电子邮件: mike@phpdoc.org