README

关于PhPuml

PhPuml可以从PHP代码生成PlantUML类图。

这是一个由自身创建的工具类图

特性

• 通过composer方便地安装
• 无需安装PlantUML即可生成PlantUml文件，或使用plantuml.jar可执行文件生成所有支持的格式（png、svg、latex等）
• 从命名空间生成包
• 生成类、接口和特性之间的继承关系
• 生成类属性和方法签名，包括来自@var文档注释的类型提示
• 从构造函数参数类型推断依赖项（假设依赖注入）
• 从"new"表达式(<<创建>>)和"throw"语句(<<抛出>>)推断关联
• 可以使用完全限定名或短名渲染类型（可独立配置接口、特性、类、属性和方法参数）
• 在Linux（已测试）、Windows（已测试）、macOS（可能）上工作

安装

安装PhPuml最简单的方法是将它作为composer项目。

$ composer create-project jhofm/ph-puml

在构建过程中会创建工具的phar版本，但目前无法可靠地下载。但是，在项目已安装的情况下，您可以使用clue/phar-composer自己创建phar。

$ curl -JL -o phar-composer.phar https://clue.engineering/phar-composer-latest.phar
$ php phar-composer.phar ph-puml
$ php ph-puml.phar

快速入门

当不带任何参数运行时，ph-puml脚本将输出描述当前文件夹中所有PHP文件的PlantUML语法。

$ cd mycode/src
$ ph-puml 

您可以将目标目录或文件的相对或绝对路径指定为第一个参数。

$ ph-puml mycode/src

第二个可选参数是输出路径。如果没有指定，将使用控制台的标准输出。

以下两个命令会产生相同的结果

$ ph-puml mycode/src > class.puml
$ ph-puml mycode/src class.puml

高级功能

输出格式

PhPuml默认生成PlantUML puml文件语法，但您也可以直接导出PlantUML支持的多数输出格式。

目前包括以下格式

• eps (Postscript)
• latex (LaTeX/Tikz)
• latex:nopreamble (LaTeX/Tikz without preamble)
• png (PNG图像)
• svg (SVG矢量图像)
• scxml (SCXML状态图，在PlantUML版本1.2020.26中似乎有故障)
• txt (ASCII艺术)
• utxt (带有Unicode字母的ASCII艺术)
• vdx (VDX图像)
• xmi (XMI元数据描述)

这需要在运行PhPuml的机器上安装Java运行环境。有关更多信息，请参阅PlantUML指南。您还需要提供以下之一

• plantuml.jar文件的路径

$ ph-puml /my/code/dir -p /somedir/plantuml.jar -f svg > ~/mycode.svg

• 或安装可选的jawira/plantuml包

$ composer create-project jhofm/ph-puml
$ cd ph-puml
$ composer require jawira/plantuml
$ ph-puml /my/code/dir -f svg > ~/mycode.svg

路径过滤器

如果输入路径是目录，PhPuml将使用一组包含和排除规则确定要分析的代码文件。默认情况下，文件扩展名为.php的目录树中的文件被包含，前提是其父目录中没有名为vendor的目录。

您可以使用命令行选项覆盖过滤器规则。所有规则都是正则表达式。您可以使用多个规则。例如，以下命令将不会跳过vendor文件夹中的文件，并且还将分析文件扩展名为.inc的includes文件夹中的文件。

$ ph-puml -e -i "/\.php$/" -i "/^includes/.*\.inc$/"

当尝试解析不包含有效PHP代码的文件时，命令将失败。

命名空间

命名空间中的类、接口和特性默认使用完全限定名进行渲染，而属性和方法参数类型则不是。可以使用 namespaced-types/t 选项来自定义此行为。

$ ph-puml -t cmp # render all types as FQNs
$ ph-puml -t # render short types only
$ ph-puml -t c # render only classlikes (classes, interfaces & traits) as FQNs  

外部类型关系

默认情况下，不会渲染尚未分析的类型的关系，以减少生成的图中的杂乱。这包括内置类型，如 \Exception 等。添加以下选项以包含这些关系。

$ ph-puml -x false # include relations to types that were not analyzed

帮助

PhPuml 使用 symfony/command，因此有一个包括所有支持参数和选项的帮助页面。

$ ph-puml -h

省略类、接口或特性命名空间可能会导致在分析源中重复非限定类型名称时绘制关系错误。

局限性

• 自动生成的类图可能永远无法完全满足您的需求，但它提供了一个手动细化的起点（并节省了令人头疼的工作）。
• PhPuml 能够处理大量代码文件，但将图表限制为所需的最少数量的类始终是一个好主意。
• 更干净的代码会产生更好的结果。类型提示和命名空间有很大帮助，例如。
• 还有很多需要抛光的地方，比如推断额外的关系类型或提供更多自定义。

故障排除

• 未捕获错误：找不到类 Composer\InstalledVersions：PhPuml 需要 Composer 2。
• require(): 打开所需的 ... 失败：运行 composer install。

致谢

如果没有 Nikita Popov 的 PHP-Parser，这将要难得多，所以非常感谢。 Symfony 也帮了很大忙。基本上，我使用的每一个依赖都由国王、王后和传奇人物维护。 <3