pronamic/wp-documentor

Documentation Generator for WordPress.

Pronamic WordPress Documentor

Pronamic WordPress Documentor is a tool to automatically extract data about the actions and filters of your WordPress theme or plugin.

Table of contents

• Getting Started
• Command Line Usage
  • Examples
• Output Examples
• Alternatives
• Links

Getting Started

Installation

To start documenting your WordPress filters and actions, require Pronamic WordPress Documentor in Composer:

composer require pronamic/wp-documentor --dev

First Run

To let Pronamic WordPress Documentor analyse your codebase, you have to use the parse command and point it to the right directory:

vendor/bin/wp-documentor parse src

Command Line Usage

--format=FORMAT

The format in which you want to export the hooks.

Format	Description
default	Symfony console table.
hookster	Hookster JSON.
markdown	Markdown.
phpdocumentor-rst	RestructuredText for phpDocumentor.

Example: --format=markdown

--template=FILE

Custom PHP template, see for examples the templates folder.

Example: --template=templates/markdown.php

--type=TYPE

Specify whether you want to export actions or filters.

Example: --type=actions or --type=filters

--output=FILE

Write output to file.

Example: --output=docs/hooks.md

--memory-limit=VALUE

Specifies the memory limit in the same format php.ini accepts.

Example: --memory-limit=-1

--exclude=GLOB

Exclude the specified folders/files.

Example: --exclude=vendor --exclude=wordpress

--ignore-vcs-ignored

If the search directory contains a .gitignore file, you can reuse those rules to exclude files and directories from the results with this option.

Example: --ignore-vcs-ignored

--prefix=PREFIX

Only parse hooks starting with the specified prefixes.

Example: --prefix=my_theme --prefix=my_plugin

Examples

vendor/bin/wp-documentor parse ./tests/source

vendor/bin/wp-documentor parse ./tests/source --format=hookster --type=actions --output=tests/docs/hookster-actions.json
vendor/bin/wp-documentor parse ./tests/source --format=hookster --type=filters --output=tests/docs/hookster-filters.json

vendor/bin/wp-documentor parse ./tests/source --format=markdown --output=tests/docs/hooks.md

vendor/bin/wp-documentor parse ./tests/source --format=phpdocumentor-rst --type=actions --output=tests/docs/phpdocumentor-actions.rst
vendor/bin/wp-documentor parse ./tests/source --format=phpdocumentor-rst --type=filters --output=tests/docs/phpdocumentor-filters.rst

Ouput Examples

• tests/docs/hooks.md
• tests/docs/hookster-actions.json
• tests/docs/hookster-filters.json
• https://github.com/wp-pay-gateways/omnikassa-2/blob/2.3.2/docs/hooks.md
• https://github.com/wp-pay-gateways/adyen/blob/1.3.1/docs/hooks.md
• https://github.com/wp-pay-gateways/mollie/blob/2.2.3/docs/hooks.md
• https://github.com/wp-pay-extensions/gravityforms/blob/2.6.0/docs/hooks.md
• https://github.com/wp-pay/core/blob/2.7.0/docs/hooks.md

Alternatives

Here is a list of alternatives that we found. However, none of these satisfied our requirements.

If you know other similar projects, feel free to edit this section!

• WP Parser by WordPress
• Hookster by Theme Blvd
• WordPress HookDoc by Matthias Günter
• GitHub Actions for WordPress by 10up
• Yoast Parser by Yoast
• WooCommerce Code Reference Generator by WooCommerce
• WordPress Hooks Reference by John Blackbourn / Human Made
• wp-hooks-generator by John Blackbourn / Human Made

Inspiration from https://github.com/TypistTech/imposter-plugin#alternatives

Links

• https://developer.wordpress.org/plugins/hooks/
• https://developer.wordpress.org/plugins/hooks/actions/
• https://developer.wordpress.org/reference/functions/do_action/
• https://developer.wordpress.org/reference/functions/add_action/
• https://developer.wordpress.org/plugins/hooks/filters/
• https://developer.wordpress.org/reference/functions/apply_filters/
• https://developer.wordpress.org/reference/functions/add_filter/
• https://developer.wordpress.org/reference/hooks/
• https://www.phpdoc.org/
• https://github.com/phpdocumentor/phpdocumentor
• https://symfony.com/doc/current/console.html
• https://symfony.com/doc/current/components/finder.html
• https://developer.wordpress.org/cli/commands/i18n/make-pot/
• https://developer.wordpress.org/cli/commands/i18n/make-json/
• https://github.com/pronamic/deployer/blob/master/bin/pronamic-deployer
• https://gitlab.com/pronamic/wp-updates/-/blob/master/index.php
• pronamic/wp-pay-core#45
• phpDocumentor/phpDocumentor#2865
• https://github.com/themeblvd/hookster

wp-documentor's Issues

Empty list of arguments when `apply_filters` is used in a conditional clause instead of assigned to a variable

This issue is similar to #11.

The list of arguments is empty when apply_filters is used inside a conditional clause instead of assigned to a variable first.

So, when using the right doc block, the following code doesn't output the correct result:

if ( apply_filters( 'some_condition_filter', $some_condition, $some_other_parameter ) ) {
    do_something();
}

and must be replaced with as follows:

$some_condition = apply_filters( 'some_condition_filter', $some_condition, $some_other_parameter );

if ( $some_condition ) {
    do_something();
}

Improve support for @since tag

Add phpDocumentor guide example

Add support for external URL in relative markdown links

Add support for `@ignore` tag

Add support for the @ignore tag:

• #13

Also see:

• https://docs.phpdoc.org/guide/references/phpdoc/tags/ignore.html
• https://pear.php.net/package/PhpDocumentor/docs/latest/phpDocumentor/tutorial_tags.ignore.pkg.html

@ignore

The @ignore tag is used to tell phpDocumentor that Structural Elements are not to be processed by phpDocumentor.

Syntax

@ignore [<description>]

List of arguments is empty when `apply_filters` is returned instead of assigned to variable

There seems to be a difference in the output between the two following occurrences:

<?php
/**
 * My plugin filter assigned to a variable
 *
 * @param string $first_param This is the first argument
 * @param string $second_param This is the second argument
 */
$some_variable = apply_filters( 'my_plugin_filter', $first_param, $second_param );

return $some_variable;

<?php
/**
 * My plugin filter directly returned
 *
 * @param string $first_param This is the first argument
 * @param string $second_param This is the second argument
 */
return apply_filters( 'my_plugin_filter', $first_param, $second_param );

In the first case, the full list of arguments is correctly parsed. In the second case, the list of arguments is empty.

Add support for `--output` option instead of piping output to a file

https://curl.se/docs/manpage.html

Empty list of arguments when casting the value returned by `apply_filters`

Same happens when casting the value returned by apply_filters

$should_do = (bool) apply_filters( 'should_we_do_it', true, $some_value );

Originally posted by @irshadahmad21 in #17 (comment)

Add ability to ignore a specific hook

I think we as developers should be able to add something to the phpdoc of a hook to let wp-documentor know that it should NOT be documented. This is because some applications enqueue hooks so dynamic that it has no value.

Maybe something like this?

/**
 * @ignore
 */
$result = apply_filters($hook, $queue, $parameter);

edit: this could also be handy when using the result of native WP hooks in your project, such as https://developer.wordpress.org/reference/hooks/the_content/

Dynamic filter

Hi there!

Thank you for the amazing library. We're doing some tests for it in our plugin, and it seems that it cannot handle "dynamic" filters. For example this code (shamefully not documented yet, we plan on start adding the comments now..):

https://github.com/tainacan/tainacan/blob/f1257907999111409fdfcc6fb42357ed909c4bda/src/classes/repositories/class-tainacan-taxonomies.php#L35C18-L35C18

Would generate an error, since it cannot call get_name(). Is there a way to solve this? I suppose it is not simple to do, since it would require a running instance of the plugin.

Add Progress Bar

https://symfony.com/doc/current/components/console/helpers/progressbar.html

Render @link tags in markdown template

Currently the @link tags are not rendered in the markdown template.

/**
 * Prints scripts or data in the head tag on the Adyen checkout page.
 * 
 * This action can be used, for example, to register and print a custom style.
 *
 * See the following link for an example:
 * https://github.com/wp-pay-gateways/adyen#pronamic_pay_adyen_checkout_head
 *
 * @link https://github.com/WordPress/WordPress/blob/5.7/wp-includes/general-template.php#L3004-L3009
 *
 * @since 1.1
 */
do_action( 'pronamic_pay_adyen_checkout_head' );

https://github.com/wp-pay-gateways/adyen/blob/62425e3706d32c63697cd31dbd57ba0894a60118/views/head.php#L8-L19

https://github.com/wp-pay-gateways/adyen/blob/develop/docs/hooks.md#pronamic_pay_adyen_checkout_head

Add a way to separate actions and filters in different (markdown) files

bin/wp-documentor parse wordpress --format=markdown --type=actions --relative=tests/docs --memory-limit=-1 --output=tests/docs/wordpress-actions.md

bin/wp-documentor parse wordpress --format=markdown --type=filters --relative=tests/docs --memory-limit=-1 --output=tests/docs/wordpress-filters.md

Fix "Deprecated: Creation of dynamic property"

Deprecated: Creation of dynamic property Pronamic\WordPress\Documentor\Documentor::$type is deprecated in /Users/remco/Projects/wp-pronamic-pay-mollie/vendor-bin/wp-documentor/vendor/pronamic/wp-documentor/bin/wp-documentor on line 129

Deprecated: Creation of dynamic property Pronamic\WordPress\Documentor\Documentor::$relative is deprecated in /Users/remco/Projects/wp-pronamic-pay-mollie/vendor-bin/wp-documentor/vendor/pronamic/wp-documentor/bin/wp-documentor on line 133

Deprecated: Creation of dynamic property Pronamic\WordPress\Documentor\Hook::$arguments is deprecated in /Users/remco/Projects/wp-pronamic-pay-mollie/vendor-bin/wp-documentor/vendor/pronamic/wp-documentor/src/Hook.php on line 82

Deprecated: Creation of dynamic property Pronamic\WordPress\Documentor\Hook::$arguments is deprecated in /Users/remco/Projects/wp-pronamic-pay-mollie/vendor-bin/wp-documentor/vendor/pronamic/wp-documentor/src/Hook.php on line 82

Deprecated: Creation of dynamic property Pronamic\WordPress\Documentor\Hook::$arguments is deprecated in /Users/remco/Projects/wp-pronamic-pay-mollie/vendor-bin/wp-documentor/vendor/pronamic/wp-documentor/src/Hook.php on line 82

Deprecated: Creation of dynamic property Pronamic\WordPress\Documentor\Hook::$arguments is deprecated in /Users/remco/Projects/wp-pronamic-pay-mollie/vendor-bin/wp-documentor/vendor/pronamic/wp-documentor/src/Hook.php on line 82

Deprecated: Creation of dynamic property Pronamic\WordPress\Documentor\Hook::$arguments is deprecated in /Users/remco/Projects/wp-pronamic-pay-mollie/vendor-bin/wp-documentor/vendor/pronamic/wp-documentor/src/Hook.php on line 82

Deprecated: Creation of dynamic property Pronamic\WordPress\Documentor\Hook::$arguments is deprecated in /Users/remco/Projects/wp-pronamic-pay-mollie/vendor-bin/wp-documentor/vendor/pronamic/wp-documentor/src/Hook.php on line 82

Deprecated: Creation of dynamic property Pronamic\WordPress\Documentor\TemplatePrinter::$documentor is deprecated in /Users/remco/Projects/wp-pronamic-pay-mollie/vendor-bin/wp-documentor/vendor/pronamic/wp-documentor/src/TemplatePrinter.php on line 32

Deprecated: Creation of dynamic property Pronamic\WordPress\Documentor\TemplatePrinter::$output is deprecated in /Users/remco/Projects/wp-pronamic-pay-mollie/vendor-bin/wp-documentor/vendor/pronamic/wp-documentor/src/TemplatePrinter.php on line 33

Deprecated: Creation of dynamic property Pronamic\WordPress\Documentor\TemplatePrinter::$template is deprecated in /Users/remco/Projects/wp-pronamic-pay-mollie/vendor-bin/wp-documentor/vendor/pronamic/wp-documentor/src/TemplatePrinter.php on line 34

Add support for exclude

https://linuxize.com/post/how-to-exclude-files-and-directories-with-rsync/

symfony/symfony#37781

Cannot exclude single file

I have an issue trying to exclude single files, using the --exclude argument

It works fine when I exclude a whole folder, yet I just want to exclude one file.
It seems to ignore the --exclude statement, if I pass a valid filename, but it works when I pass a valid folder name.

Example:
--exclude=foldername => works (excludes whole foldername folder)
--exclude=filename.php => fails (does not exclude that file)

I have also tried with foldername/filename and different other syntax, inclusive brackets, and it just seems to ignore it when the name passed is not a folder.

According the description however it seems it should be possible to exclude single files?
Even better would be to exclude occurrences it cannot parse and just skip. I have a peculiar plugin that does something like this:
do_action( $atts['hook_name'] );

Of course, that hook fails in the parser with these errors:

Not supported hook tag expression `PhpParser\Node\Expr\ArrayDimFetch`: $att  
  s['hook_name'].   
Could not convert tag argument value to a name in path/to/file/filename.php#N. 

This is why I want to exclude that file, but of course if there's an easy way to just skip when failing, instead of halting, that would be the best!