humanmade/psalm-plugin-wordpress

WordPress stubs and plugin for Psalm.

3.0.0-alpha1 2022-12-01 13:36 UTC

Requires

• ext-simplexml: *
• php-stubs/wordpress-globals: ^0.2.0
• php-stubs/wordpress-stubs: ^6.0
• php-stubs/wp-cli-stubs: ^2.7
• vimeo/psalm: ^5
• wp-hooks/wordpress-core: ^1.3.0

Requires (Dev)

• humanmade/coding-standards: ^1.2
• phpunit/phpunit: ^9.0
• psalm/plugin-phpunit: ^0.15.1

MIT

• Joe Hoyle

README

Write type-safe WordPress code.

This Psalm plugin provides all WordPress and WP CLI stubs, so your WordPress based project or plugin will have type information for calls to WordPress APIs. This ensures your WordPress plugin or theme has less bugs!

• Stubs for all of WordPress Core
• Stubs for WP CLI
• Types for apply_filters return values.
• Types for add_filter / add_action
• Configuration options to use your own stubs

Installation

Please refer to the full Psalm documentation for a more detailed guide on introducing Psalm into your project.

After Psalm is installed, install this package and enable the plugin:

composer require --dev humanmade/psalm-plugin-wordpress
./vendor/bin/psalm-plugin enable humanmade/psalm-plugin-wordpress

Configuration

If you follow the installation instructions, the psalm-plugin command will add this plugin configuration to the psalm.xml configuration file.

<?xml version="1.0"?>
<psalm xmlns="https://getpsalm.org/schema/config">
	<!-- project configuration -->

	<plugins>
		<pluginClass class="PsalmWordPress\Plugin" />
	</plugins>
</psalm>

Further details about plugins can be found on Psalm's website.

Default WordPress stubs

If you do not want to use the default WordPress class/method/function stubs, which are part of this plugin, useDefaultStubs must be set to false:

<pluginClass class="PsalmWordPress\Plugin">
	<useDefaultStubs value="false" />
</pluginClass>

Default WordPress hooks

If you do not want to use the default WordPress hooks, which are part of this plugin, useDefaultHooks must be set to false:

<pluginClass class="PsalmWordPress\Plugin">
	<useDefaultHooks value="false" />
</pluginClass>

Custom hooks

You can also provide custom hooks:

<pluginClass class="PsalmWordPress\Plugin">
	<hooks>
		<directory name="some/dir/hooks" recursive="true" />
		<directory name="/absolute/other/dir/hooks" />
		<file name="my-special-hooks/actions.json" />
	</hooks>
</pluginClass>

If a directory is provided, the plugin will search for the following files:

• actions.json
• filters.json
• hooks.json

The plugin expects a JSON representation of the hooks as per wp-hooks/generator.

WordPress paths

To help Psalm analyze your project you might need to define some of WordPress' default global constants such as those for paths.

<?xml version="1.0"?>
<psalm autoloader="tests/bootstrap.php" xmlns="https://getpsalm.org/schema/config">
	<!-- project configuration -->
</psalm>

The following example bootstrap file is for a Bedrock installation:

<?php

require_once dirname( __DIR__ ) . '/config/application.php';

define( 'WPMU_PLUGIN_DIR', WP_CONTENT_DIR . '/mu-plugins' );

define( 'WP_PLUGIN_DIR', WP_CONTENT_DIR . '/plugins' );

You could require WordPress' default constants functions but that requires a lot more boilerplating to allow those functions to effectively define constants.

Interested in contributing?

Feel free to open a PR to fix bugs or add features!

In addition, have a look at Psalm's contribution guidelines.

Who made this

Created by @joehoyle, maintained by the Psalm community.