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