wp-hooks/vscode-wordpress-hooks

VS Code extension that provides intellisense and autocomplete for WordPress hooks, actions, and filters

WordPress Hooks Intellisense for VS Code

This extension provides intellisense and autocomplete for WordPress hooks, actions, and filters.

• Autocomplete for action and filter names
  • Supports all actions and filters up to WordPress 6.4
• Autocomplete for action and filter callback functions
  • Supports functions, class methods, closures, arrow functions, and more
  • The parameter types, return type, and a docblock are included where appropriate
  • Various options can be controlled in the settings for the extension
• Hover information on action and filter names
  • Includes a useful link to the developer.wordpress.org documentation site

Usage

Start typing the name of a WordPress action or filter within add_action() or add_filter() and you'll get an autocomplete list of all matching actions or filters, plus information about the parameters and usage:

Autocomplete is also provided for the callback function. It's contextually aware and provides options for a function, a class method, a closure, an arrow function, and WordPress' built-in utility functions:

An autocompleted closure callback looks like this:

Hover information for an action or filter name looks like this:

FAQ

Which functions does the autocomplete list and hover information work with?

• add_action()
• add_filter()
• remove_action()
• remove_filter()
• has_action()
• has_filter()
• doing_action()
• doing_filter()
• did_action()
• did_filter()

How can I trigger the autocomplete list if it doesn't show up?

Place your cursor within the first parameter of one of the supported functions, eg add_action() or add_filter(), and hit ctrl+space. This works with any autocomplete provider, not only this extension.

Can I disable or adjust the type declarations / type hints / docblock?

Yes, open the preferences for VS Code and go to the Extensions -> WordPress Hooks Intellisense section.

Where does the list of hook names come from?

They're generated directly from the WordPress core software and updated in time for each new release. They're bundled with this extension so there's no requirement for your project to include WordPress if you don't want to, and the extension doesn't scan the files in your project looking for actions and filters.

Sponsors

The time that I spend maintaining this extension and other tools is in part sponsored by:

Plus all my kind sponsors on GitHub:

Click here to find out about supporting this extension and my other WordPress development tools and plugins.

License

This extension is free and open source software. It's licensed under the GNU GPL version 3.

Thanks

• This extension uses the wp-hooks library as the hook information provider.
• This extension uses some code inspired by the Autocomplete WordPress Hooks extension for Atom.

vscode-wordpress-hooks's Issues

Bundle the extension dependencies

https://code.visualstudio.com/api/working-with-extensions/bundling-extension

Automatic docblock insertion

When inserting the closure callback, it would be great if a corresponding docblock was inserted above the function.

Looks like additionalTextEdits() is what we want.

Woocommerce support

Are there any plans for Woocommerce support for their different hooks? 😊

WooCommerce Support!

It's a very nice and useful plugin for WordPress hooks -no doubt-. But is it possible to add support for WooCommerce hooks as well?
WooCommerce is a second most important tool in WordPress after WordPress itself so considering its support in this extension might be worthy.

Thanks.

Provide autocomplete for a function when the are no symbols

For when the aren't yet any other symbols in the file.

https://github.com/johnbillion/vscode-wordpress-hooks/blob/0f6c10c5bcdfb45674cf6c17d5dd6f28fb6bafbd/src/extension.ts#L447-L450

Feature request: Add return value to filters

All filters should return a value, so please add it :)

add_filter( 'template_directory', function( string $template_dir, string $template, string $theme_root ) {
    |
    return $template_dir;
}, 10, 3 );

Bug: Callback prefix in a class method

When I add a hook to a class method;

1. If I have a namspace, __NAMESPACE__ is prefixed the callback name:

<?php
declare( strict_types = 1 );
namespace Soderlind\Test;

class Test {
	public function __construct() {
		add_filter('the_content',__NAMESPACE__ . '\\filter_the_content' );
		add_action('init',__NAMESPACE__ . '\\action_init' );
	}
.
.
.
}

2. If I don't have a namespace:

	public function __construct() {
		add_filter('the_content','filter_the_content' );
		add_action('init','action_init' );
	}

In both cases, the correct is

	public function __construct() {
		add_filter('the_content', [ $this, 'filter_the_content' ] ); 
		add_action('init', [ $this,'action_init' ] );
	}

Feature request: Add your own hooks

It would be very nice if I could add my own hooks, i.e:

• Generate hooks using your wp-hooks-generator
• Point to the hooks using vscode preferences, and add support for per workspace eg:

{
    "wordpress-hooks.core" : 1,
    "wordpress-hooks.local-actions": "${workspaceFolder}/hooks/actions.json",
    "wordpress-hooks.local-filters": "${workspaceFolder}/hooks/filters.json"
}

re wordpress-hooks.core, if (when) you're adding this option, it might be nice to be able to disable core hooks

Support all the action and filter functions

• has_action
• did_action
• has_filter

Add a trailing semicolon after the callback

When the user autocompletes a callback, let's see if the trailing semicolon can be appended if it's not present.

Register hook name usage as a symbol

This might be a silly idea but let's try it.

If each usage of a hook name gets registered as a symbol, this will allow the user to navigate to it from the various Go to Symbol... commands. This will give the user a quick way of navigating to uses of a given hook name.

`void` return type being given to some filters

It looks like when you use a filter that originates from apply_filters_ref_array(), its callback return type gets set to void. I've seen this affecting the_posts and found_posts_query.

Needs investigating.

Example:

/**
 * Filters the array of retrieved posts after they've been fetched and internally processed.
 *
 * @param \WP_Post[] $posts Array of post objects.
 * @param \WP_Query  $this  The WP_Query instance (passed by reference).
 */
add_filter( 'the_posts', function( array $posts, \WP_Query $this ) : void {
	
}, 10, 2 );

Only show appropriate helper functions in the callback autocomplete list

The autocomplete list for the callback function for a filter lists all the available helper functions that WordPress provides:

• __return_true
• __return_false
• __return_zero
• __return_null
• __return_empty_array
• __return_empty_string

This list should be dynamic based on the type of the first parameter passed to the filter.

If the type isn't known, the complete list should be shown. If the type is known, only show the appropriate functions for that type.

Deployment action is broken

See https://github.com/wp-hooks/vscode-wordpress-hooks/actions/runs/6424761970/job/17446332033

Reformat parameter docs that wrap onto multiple lines

Parameters with hash notation and lines that wrap onto multiple lines need to have the spacing sorted out when they're used in the docblock.

Hopefully can do something like replace any occurrence of several spaces with a linebreak and the same spaces.

Support arrow function callback

Limited use, but they're fun, so why not.

`<code>` tags are stripped from descriptions

The @since tags support HTML in their descriptions, but this gets stripped, resulting in a description such as @since 5.5.1 Added the parameter.

wp_admin_notice isn't recognized as a function

wp_admin_notice(), which was added in WordPress 6.4, isn't recognized by this plugin as a valid function.

On the other hand, I wonder if there's something unusual going on with the WordPress developer documentation page for that function, because the function doc also doesn't show up on https://devdocs.io/wordpress/.

Rebrand

I'm planning on adding intellisense features beyond autocomplete, so a rebrand is in order.

Options:

• WordPress Hooks IntelliSense
• WordPress Hook IntelliSense
• WordPress Action and Filter IntelliSense

[Feature] Make this extension available for VSCode web

I'm often using VSCode web on GitHub and would love to have the same feature available.

Disable GitHub Copilot when using WordPress Hooks IntelliSense.

I use Copilot (love it), but when I use your extension, Copilot creates unwanted noise (suggestions). I am uncertain if it works, but it would be nice if Copilot was disabled while using WordPress Hooks IntelliSense.

Maybe you can use github.copilot.toggleCopilot (toggle on / off)?

Make this extension available on Open VSX

Is it possible to add this extension to the Open VSX repository ? This way, it could be installed and updated automatically for users using VS Code in environments such as GitPod.

The publishing process is available here: https://github.com/eclipse/openvsx/wiki/Publishing-Extensions#how-to-publish-an-extension

The GitPod team explains why they use Open VSX here: https://www.gitpod.io/blog/open-vsx

Thanks :-)

Publish extension updates via GitHub Actions

Doing it manually is a pain. Should be simple enough to do via Actions.

https://www.visualstudiogeeks.com/github/extensions/publish-vscode-extension-using-github-actions

Link to the developer site from within documentation

In the autocomplete lists, hovers, etc, there should be a link to the developer.wordpress.org site for the given hook.

To save having to convert a hook name to a valid slug as used on developer.wordpress.org, the search result URL could be used instead, eg https://developer.wordpress.org/?post_type=wp-parser-hook&s=_get_page_link .

Implement resolveCompletionItem for hook descriptions

Implementing the resolveCompletionItem() method when registering a completion item provider means the construction of properties such as documentation get deferred until each individual completion item is selected.

This should improve performance as the extension won't need to construct the docs for every hook at the point where it provides the initial completion list.

Docs: https://code.visualstudio.com/api/references/vscode-api#CompletionItemProvider

Add autocomplete for the callback even if the hook isn't known

For example, callback autocomplete should work for the following:

add_filter( 'i_dont_exist', |

It should provide a generic callback signature, something like:

function filter_i_dont_exist( $value ) {
    |
    return $value;
}

Support nullable type declarations

Parameters and the return type can be nullable if the list of types contains exactly two entries, one of which is null. For example, this parameter in a core action or filter:

@param bool|null $param Description

can be treated as a nullable type in PHP 7.1+

function( ?bool $param ) :? bool {
    ...
}

Support class method and procedural function callback types

Unfortunately VS Code doesn't expose contextual information about the location of the cursor, for example its not possible to determine whether the cursor is currently within a class methid.

However, it looks like we can construct this information ourselves using a combination of the vscode.executeDocumentSymbolProvider command to fetch the symbol list, and a filter that checks vscode.DocumentSymbol.range.contains to iteratively determine which symbol, if any, the cursor is in, and its type (method, global function, namespaced function).

The callbackProvider completion items can then include a method or function callback as appropriate. The additionalTextEdits property on each one will need to be used to insert the method or function as appropriate, immediately after the current containing symbol.

Add navigation to callback declaration

Need to map the callback parameter of add_action() and add_filter() to its corresponding declaration. This will allow the user to navigate to the declaration, eg by cmd-clicking or by using the Go to Definition command.

Needs to work for:

• Namespaced functions (__NAMESPACE__ . '\\foo')
• Global functions ('foo')
• Class instance methods ([ $this, 'foo' ] and array( $this, 'foo' ))
• Static class methods ('className::foo', [ 'className', 'foo' ], and array( 'className', 'foo' ))

Add a hover provider for hook names

There are some neat APIs in VS Code which I think will allow me to provide some of the intellisense that is missing when WordPress action and filters are used.

One of these is the hover provider which can be used to provide docs for an action or filter hook name when the user hovers over it. It should be confined to the appropriate parameter of supported functions (eg add_action() and add_filter()).

Rename $this in callback function parameter list

Some parameters are documented with the name $this. These need to be renamed when used as parameters in callback functions because it's not a valid parameter name. It should be renamed to the name of the class, if it's hinted, with a fallback to $object or $_this otherwise.

Example:

add_action( 'customize_post_value_set', function( $setting_id, $value, $this ) {
    
}, 10, 3 )

should become:

add_action( 'customize_post_value_set', function( $setting_id, $value, $wp_customize_manager ) {
    
}, 10, 3 )

Additional type declarations in PHP 8

PHP 8 allows unions in type declarations, eg:

function my_function( Foo|Bar $param )

It also introduces false as a type (although not true because ¯\_(ツ)_/¯).

For anyone writing code for PHP 8 only, it would be useful to allow union types and false to be expressed in the type declarations.

More info: https://php.watch/versions/8.0/union-types

Go to filter/action reference when click on hook name

Hello
This feature is very useful

Conflict with "PHP Tools for VS Code"

macos: 10.15.5 (19F101)
vs code: 1.47.1
php tools: 1.0.4908
vscode-wordpress-hooks: 0.2.1

Feature request: Add type hints

When adding an autocompleted closure callback, please add type hints (could be toggled on/off in settings), eg:

add_filter( 'template_directory', function( string $template_dir, string $template, string $theme_root ) {
    |
}, 10, 3 );

If the type hint is an object, it should be escaped, as in:

add_action( 'pre_get_posts', function( \WP_Query $this ) {
	
}  );