Hooksy

Hooksy scans WordPress plugins and themes for actions and filters, pairs them with their PHPDoc, and writes a deterministic JSON file compatible with the wp-hooks/generator schema.

Get started · Configuration · Output · Commands

Features

• Extracts do_action(), apply_filters(), and their _ref_array and _deprecated variants.
• Preserves hook descriptions and tags such as @since, @param, @see, and @link.
• Resolves hook names composed from string literals and interpolated expressions.
• Produces stable, source-ordered output suitable for documentation pipelines and CI.
• Supports configurable include/exclude globs, PHP versions from 7.0 through 8.4, and strict error handling.

Get started

Install Hooksy globally with npm:

npm install --global @sematico/hooksy

Then initialize and parse a WordPress plugin or theme:

cd path/to/your-project
hooksy init
hooksy parse

hooksy init creates hooksy.yml. By default, hooksy parse scans PHP files below the configuration file and writes hooks.json beside it.

Configuration

The generated hooksy.yml starts with practical defaults:

include:
    - '**/*.php'

exclude:
    - '**/vendor/**'
    - '**/node_modules/**'
    - '**/tests/**'

output: hooks.json
php_version: '7.4'

| Setting | Description | | ------------- | --------------------------------------------------- | | include | Glob patterns for files to scan. | | exclude | Glob patterns to omit from the scan. | | output | Output path, relative to the configuration file. | | php_version | Parser grammar version: 7.0–7.4 or 8.0–8.4. |

Output

Hooksy writes a single wp-hooks/generator-compatible document:

{
	"$schema": "https://raw.githubusercontent.com/wp-hooks/generator/1.0.1/schema.json",
	"hooks": [
		{
			"name": "user_registered",
			"file": "includes/registration.php",
			"type": "action",
			"doc": {
				"description": "Fires after a user is registered.",
				"long_description": "",
				"long_description_html": "",
				"tags": [
					{
						"name": "param",
						"content": "The user ID.",
						"types": ["int"],
						"variable": "$user_id"
					}
				]
			},
			"args": 1
		}
	]
}

Hooks marked with @ignore, hooks documented elsewhere using WordPress conventions, and calls without a determinable name are omitted. Use --strict in CI when omissions or PHP parse errors should fail the run.

Usage

$ npm install -g @sematico/hooksy
$ hooksy COMMAND
running command...
$ hooksy (--version)
@sematico/hooksy/1.0.0 darwin-arm64 node-v24.18.0
$ hooksy --help [COMMAND]
USAGE
  $ hooksy COMMAND
...

Commands

• hooksy help [COMMAND]
• hooksy init
• hooksy parse

hooksy help [COMMAND]

Display help for hooksy.

USAGE
  $ hooksy help [COMMAND...] [-n]

ARGUMENTS
  [COMMAND...]  Command to show help for.

FLAGS
  -n, --nested-commands  Include all nested commands in the output.

DESCRIPTION
  Display help for hooksy.

See code: @oclif/plugin-help

hooksy init

Write a default hooksy.yml to the current directory

USAGE
  $ hooksy init [-f]

FLAGS
  -f, --force  overwrite hooksy.yml if it already exists

DESCRIPTION
  Write a default hooksy.yml to the current directory

EXAMPLES
  $ hooksy init

  $ hooksy init --force

See code: src/commands/init.ts

hooksy parse

Parse configured PHP files and write the hooks JSON

USAGE
  $ hooksy parse [-c <value>] [-v] [-s]

FLAGS
  -c, --config=<value>  [default: hooksy.yml] path to the hooksy.yml config file
  -s, --strict          exit non-zero when any file had a parse error or a hook was dropped
  -v, --verbose         log per-line PHP parse error diagnostics

DESCRIPTION
  Parse configured PHP files and write the hooks JSON

EXAMPLES
  $ hooksy parse

  $ hooksy parse -c custom.yml

See code: src/commands/parse.ts

License

Hooksy is available under the MIT License.