README

此脚本是针对提供钩子以便其他插件使用的WordPress插件的。通过解析其源代码，它会在Github Wiki中创建文档。

通常，您首先创建一个extract-wp-hooks.json，并在仓库上方的文件夹中检出Github Wiki。相应地修改extract-wp-hooks.json并执行extract-wp-hooks.php。这将创建wiki文件夹中的markdown文件。然后您可以执行git commit和git push以提交更改。

示例

• https://github.com/akirk/extract-hooks/wiki/Hooks (从example.php提取)
• https://github.com/akirk/friends/wiki/Hooks
• https://github.com/akirk/enable-mastodon-apps/wiki/Hooks

工作原理

PHP脚本没有依赖项。它使用PHP的内部解析器（使用token_get_all）来识别对apply_filters()或do_action()的PHP函数调用。

它为每个过滤器生成一个适合Github Wiki的markdown文件。页面包含可能提供的文档（通过源代码中的注释），一个（自动生成）示例，参数，返回值，对源代码的引用（包括提取的源代码片段）。

示例：通过注释提供文档

对于每个过滤器，它查看过滤器之前的注释，以便您可以对其进行文档记录，例如

/*
 * This is example filter 1.
 *
 * @param string $text The text to modify.
 * @param string $mode Extra information that might be useful.
 * @return string The modified text.
 */
$result = apply_filters( 'example_filter1', $text, $mode );

这将生成一个包含文本This is an example filter和参数列表及返回值的example_filter1.md

example_filter1

This is an example filter.

参数

• string $text 要修改的文本。
• string $mode 可能有用的额外信息。

返回值

string 修改后的文本。

但是不仅如此，它还将包含一个自动生成的示例

自动生成示例

add_filter(
    'example_filter1',
    function(
        string $text,
        string $mode
    ) {
        // Your code
        return $text;
    },
    10,
    2
);

提供示例

您也可以在注释中提供自己的示例，以覆盖自动生成的示例

/*
 * This is example filter 2.
 *
 * Example:
 * ```php
 * add_filter( 'example_filter2', function ( $text ) {
 *     return strtolower( $text );
 * } );
 * ```
 *
 * @param string $text The text to modify.
 * @param string $mode Extra information that might be useful.
 * @return string The modified text.
 */
$result = apply_filters( 'example_filter2', $text, $mode );

它生成这个输出：example_filter2

示例

add_filter( 'example_filter2', function ( $text ) {
    return strtolower( $text );
} );

无文档

最后，如果您有一个没有任何文档的过滤器，脚本会尝试创建有用的自动生成示例。例如，您有如下代码

$result = apply_filters( 'example_filter3', $text, $mode );

它生成这个输出：example_filter3

自动生成示例

add_filter(
    'example_filter3',
    function (
        $text,
        $mode
    ) {
        // Your code here
        return $text;
    },
    10,
    2
);

参数

• $text
• $mode

安装

通过composer

composer require --dev akirk/extract-wp-hooks

然后您可以从供应商bin目录运行extract-wp-hooks.php

./vendor/bin/extract-wp-hooks.php

在您的项目目录中放置一个.extract-wp-hooks.json或extract-wp-hooks.json来使用它。