README

重要

此插件已弃用，并在phpDocumentor 2.0稳定版发布后将予以删除。 Twig功能将集成到phpDocumentor 2.0的核心中，使用对象模型代替XML/XPath交互。

安装

此插件默认与phpDocumentor一起安装。

功能

此插件具有以下功能

一个生成输出的作者使用Twig
一个基本的扩展，包含与phpDocumentor相关的最常见功能和任务。
一个接口，第三方开发者可以基于此构建他们的Twig扩展。

使用Twig生成输出

Twig作者可以在模板中的任何转换中使用（请参阅phpDocumentor的主文档关于创建模板）。

以下行可以作为transformations元素的子元素添加

<transformation
    writer="\phpDocumentor\Plugin\Twig\Transformer\Writer\Twig"
    source="templates/my_twig_template/index.twig"
    artifact="index.html"/>

这告诉phpDocumentor使用Twig作者使用位于/data/templates/my_twig_template文件夹中的index.twig模板生成目标文件夹中的index.html文件。

完整的基本示例模板

<?xml version="1.0" encoding="utf-8"?>
<template>
  <author>Mike van Riel</author>
  <email>mike.vanriel@naenius.com</email>
  <version>1.0.0</version>
  <copyright>Mike van Riel 2012</copyright>
  <description></description>
  <transformations>
      <transformation
        query="copy"
        writer="FileIo"
        source="templates/my_twig_template/stylesheet.css"
        artifact="stylesheet.css"/>
    <transformation
        writer="\phpDocumentor\Plugin\Twig\Transformer\Writer\Twig"
        source="templates/my_twig_template/index.twig"
        artifact="index.html"/>
  </transformations>
</template>

遍历结果集

使用转换可以遍历一组元素并在它们上应用模板。

以下是一个示例来说明这一点

假设你想使用相同的模板文件生成类的详细视图

你事先不知道将有哪些类，因此你需要动态的转换。这可以通过在转换中添加'query'属性并指定xpath查找来实现。

每个类条目的示例转换

<transformation
    query="/project/file/class"
    writer="\phpDocumentor\Plugin\Twig\Transformer\Writer\Twig"
    source="templates/my_twig_template/class.twig"
    artifact="class.html"/>

重要

永远不要在搜索查询中使用//；这非常慢，在任何情况下都应该避免。

上面的示例将遍历项目中的所有class元素，并将它们传递给你的twig模板作为根元素，而不是project。

上述转换有一个大问题：目标文件class.html将被每个后续找到的类覆盖，最终你将得到一个包含最后一个找到的类的文件。

要修复这个问题，你可以在artifact属性中使用xpath查询来创建动态的目标文件名。

每个类条目的示例转换（具有动态文件名）

<transformation
    query="/project/file/class"
    writer="\phpDocumentor\Plugin\Twig\Transformer\Writer\Twig"
    source="templates/my_twig_template/class.twig"
    artifact="{@full_name}.html"/>

在上面的示例中，你可以看到在花括号中提供了一个xpath查询。此查询使用query属性找到的节点执行。因此，在这个示例中，从当前正在处理的类中取出了full_name属性。

编写自己的模板

注意

待补充

每个模板都会收到一个名为 ast_node 的全局 Twig 变量。这个全局 Twig 变量代表抽象语法树（项目）的文档根，或者如果使用了查询，则代表一个子节点。

提示

如果您要对 /project/file/class 执行查询，则 ast_node 将是 /project/file/class 的单个实例。

由于抽象语法树（及其节点）以 SimpleXMLElement 对象的形式呈现，因此您可以从 Twig 中像查询普通对象一样查询它们。

扩展

使用第三方扩展

phpDocumentor 允许您添加自己的扩展，以便它们可以被使用。

每个扩展都需要可用来自动加载（因此在这种情况下通常创建一个插件，并使用 Composer 的 'require' 部分包含它们）。

一旦可用，您可以在模板的头部定义一个名为 'twig-extension' 的参数，或者为每个单独的转换定义。

注意

具有转换定义的扩展会覆盖模板中定义的扩展。

全局定义的扩展示例

<?xml version="1.0" encoding="utf-8"?>
<template>
    <parameters>
        <twig-extension>
            \phpDocumentor\Plugin\MyPlugin\Twig\Extension
        </twig-extension>
    </parameters>
    <transformations>
        <transformation
            writer="\phpDocumentor\Plugin\Twig\Transformer\Writer\Twig"
            source="templates/twig/index.twig"
            artifact="index.html"/>
    </transformations>
</template>

具有单个转换定义的扩展示例

<?xml version="1.0" encoding="utf-8"?>
<template>
    <transformations>
        <transformation
            writer="\phpDocumentor\Plugin\Twig\Transformer\Writer\Twig"
            source="templates/twig/index.twig"
            artifact="index.html"
        >
            <parameters>
                <twig-extension>
                    \phpDocumentor\Plugin\MyPlugin\Twig\Extension
                </twig-extension>
            </parameters>
        </transformation>
    </transformations>
</template>

编写自己的扩展

注意

待编写

phpdocumentor / plugin-twig

维护者

详细信息