yard/wp-hook-registrar

An Acorn package for WordPress hook registration.

v1.0.2 2024-12-06 21:53 UTC

Requires

• php: >=8.1
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• 10up/wp_mock: ^0.4.2
• larastan/larastan: ^2.0
• orchestra/testbench: ^8.23
• pestphp/pest: ^2.34
• szepeviktor/phpstan-wordpress: ^1.0
• yard/php-cs-fixer-rules: ^1.0

MIT

README

An Acorn package for WordPress Hook Registration.

Features

• Register Hooks using php attributes
• Configure Hook registration using a config file
• Load plugin-specific hooks only when the plugin is active

See config for all configuration options.

Requirements

• Sage >= 10.0
• Acorn >= 4.0

Installation

1. Install this package with Composer:

   composer require yard/wp-hook-registrar

2. Run the Acorn WP-CLI command to discover this package:

   wp acorn package:discover

3. Publish the config file with:

   wp acorn vendor:publish --provider="Yard\Hook\HookServiceProvider"

4. Register all your project hooks in the published configuration file config/hooks.php.

Installation in WordPress plugins

To use this package in a standard WordPress plugin, you can use the HookRegistrar to register hooks. You can skip step 3 and 4 from the installation instructions above and instead add the following to your plugin's main file:

/**
 * Plugin Name: My Plugin
 */

require __DIR__ . '/vendor/autoload.php';

$classNames = [
    \Plugin\ClassContainsHooks::class,
    \Plugin\AnotherClassContainsHooks::class,
];

$registrar = new \Yard\Hook\Registrar($classNames);
$registrar->registerHooks();

Hook Attributes

This package provides two Attributes: Action and Filter. They can be used to register hooks instead of the WordPress functions add_action() and add_filter()

This syntax allows you to place the hook registration directly above the method it invokes when the hook is triggered.

#[Action(string $hookName, int $priority = 10)]
public function doSomething(): void

#[Filter(string $hookName, int $priority = 10)]
public function filterSomething(): mixed

Notice that you do not need to pass the number of accepted arguments to the Action and Filter attributes as you would with add_action() and add_filter(). Instead, the number of accepted arguments is determined by the method signature.

You can add as many hooks to the same method as you want.

Example

<?php

namespace App\Hooks;

use Yard\Hook\Action;
use Yard\Hook\Filter;

class Theme
{
    #[Action('save_post')]
    public function doSomething(int $postId, \WP_Post $post, bool $update): string
    {
        // do something
    }

    #[Filter('the_content')]
    #[Filter('the_excerpt')]
    public function filterSomething(string $content)
    {
        // filter content
        return $content;
    }
}