README

🧬 About DocHooks

The Laravel or Symfony projects are using method annotations for various things. This helps to have the project organized without too much code. WordPress has no implementation of such concept and this package is a remedy.

DocHooks package allows you to do:

class Example extends HookAnnotations {

	/**
	 * @action test
	 */
	public function test_action() {}

	/**
	 * @filter test 5
	 */
	public function test_filter( $val, $arg ) {
		return $val;
	}

	/**
	 * @shortcode test
	 */
	public function test_shortcode( $atts, $content ) {
		return 'This is test';
	}

}

$example = new Example();
$example->add_hooks();

Instead of old:

$example = new Example();

add_action( 'test', [ $example, 'test_action' ] );
add_filter( 'test', [ $example, 'test_filter' ], 5, 2 );
add_shortcode( 'test', [ $example, 'test_shortcode' ] );

💾 Installation

composer require micropackage/dochooks

🕹 Usage

Annotations

@action <hook_name*> <priority>
@filter <hook_name*> <priority>
@shortcode <shortcode_name*>

The hook and shortcode name is required while default priority is 10.

You don't provide the argument count, the class will figure it out. Just use the callback params you want.

Test if DocHooks are working

When OPCache has the save_comments and load_comments disabled, this package won't work, because the comments are stripped down. See the fallback solution.

use Micropackage\DocHooks\Helper;

(bool) Helper::is_enabled();

Using within the class

You can extend the HookAnnotations class:

use Micropackage\DocHooks\HookAnnotations;

class Example extends HookAnnotations {

	/**
	 * @action test
	 */
	public function test_action() {}

}

$example = new Example();
$example->add_hooks();

Or use the Trait:

use Micropackage\DocHooks\HookTrait;

class Example {

	use HookTrait;

	/**
	 * @action test
	 */
	public function test_action() {}

}

$example = new Example();
$example->add_hooks();

Using as a standalone object

use Micropackage\DocHooks\Helper;

class Example {

	/**
	 * @action test
	 */
	public function test_action() {}

}

$example = Helper::hook( new Example() );

Fallback

Because the HookAnnotations object stores the called hooks in _called_doc_hooks property, you are able to pull them out and parse them into a list of old add_action, add_filter and add_shortcode functions.

For this you'll need a central "repository" of all objects with hooks ie. Runtime class. See the example of this approach in the Notification plugin, which uses the WP CLI to dump all the hooks into separate file.

📦 About the Micropackage project

Micropackages - as the name suggests - are micro packages with a tiny bit of reusable code, helpful particularly in WordPress development.

The aim is to have multiple packages which can be put together to create something bigger by defining only the structure.

Micropackages are maintained by BracketSpace.

📖 Changelog

See the changelog file.

📃 License

This software is released under MIT license. See the LICENSE file for more information.

micropackage / dochooks

Maintainers

Details