Download the PHP package brain/striatum without Composer

Striatum

Striatum is a package (not full plugin) to handle WordPress hooks OOP way.

It makes use of composer to be embedded in larger projects and implements Observer pattern to deal with WordPress hooks. It takes the two pattern interfaces, Subject and Observer, from PHP SPL library.

It is a Brain Project module.

Table of contents

• Quick Start
• Features
• More Info
  • WordPress core compatible
  • The key "hook id" concept
  • API
  • Embed in OOP projects
  • Gotchas!
  • Requirements
  • Installation
  • Codename: Striatum
  • Developers and Contributors
  • License

Read also

• API documentation

Quick Start

Striatum is very easy to use, e.g. adding an action is as easy as:

or fire a custom action or filter

All the functions available through the Brain\Hooks API facade are documented in the API doc page. (Before teasing the static approach, read here).

Features

1. Add action and filters to core hooks, in absolutely core-compatible way
2. Remove (or edit) any type of callback added, even objects methods or closures
3. Auto-removing hooks: add callback that auto-remove themselves after a specific number of times they have been performed
4. Hooks freezing and unfreezing: temporarily disable callbacks added to one or more hooks, and then enabling them again
5. Add same callback to more than one hook using one function
6. Advanced debug for hooks
7. Fluent (chained) coding style

More info

In WordPress there are hooks and callbacks. An hook is identified by a tag (e.g. 'init', 'the_content') and for every tag is possible to have multiple callbacks attached. Every callback has two additional properties: priority and accepted arguments. In Striatum, a tag has its own subject object, and rather than callbacks, Striatum uses observer objects, and every observer has properties that coincides with WordPress ones: callback, priority and accepted arguments. Additionally, Striatum observers have some additional properties, main one is id, but there are also 'times' and 'debug'. Another important property is 'is_filter', that when true makes a subject object be a filter rather than an action.

WordPress core compatible

Striatum is fully compatible with WordPress core hooks: in the concrete implementations of observer pattern interfaces, the subject methods attach, detach and notify are internally implemented using WordPress Plugin API functions.

The key "hook id" concept

To identify a specific callback, WordPress builds an unique id. When the callback is a string (plain functions) or an array of two strings (object static methods) that unique id is predictable, but when dynamic object methods are used, or worse, anonymous functions (closures), than WordPress uses spl_object_hash and to identify a specific callback becomes a pain. For further info worth reading these two WordPress Development (Stack Exchange) answers, this one by @toscho (Thomas Scholz), and this one by myself. Striatum force to set an id property for every hook (observer) added, in this way is possible to use that id to retrieve, remove, edit or debug the hook object.

API

Striatum package comes with an API that ease its usage, without having to get, instantiate or digging into package objects. API is defined in a class, stored in the Brain (Pimple) container with the id: "hooks.api". So is possible to get it using Brain instance, something like: $api = Brain\Container::instance()->get("hooks.api"), and then call all API function on the instance got in that way. However that's not very easy to use, especially for people used to just use a plain function to add and trigger hooks. This is the reason why package also comes with a facade class. The term is not referred to façade pattern, but more to Laravel facades, whence the approach (not actual code) comes from: no real static method is present in the class, but a single __callstatic method that proxy API methods to proper instantiated objects.

The facade class is named Hooks inside Brain namespace. Using it, add an hook is as easy as:

addAction method is designed using almost same signature of core add_action function, so take almost same arguments. It differs for first argument that is the hook id: using 'plugin.init', is possible to retrieve, to edit, to remove and to debug the hook added.

All the functions available through the Brain\Hooks facade are documented in the API documentation.

Embed in OOP projects

The static facade class is easy to use, however using in that way inside other classes, create there hardcoded dependency to Striatum. In addition, unit testing other classes in isolation becomes pratically impossible. To solve these problems, the easiest way is to use composition via dependency injection. In facts, the Brain\Hooks facade class can be used in dynamic way, like so:

Looking at Brain\Hooks class code, you'll see there is absolutely no difference in the two methods, but using the latter is possible to inject an instance of the class inside other classes. See the following example:

The method get_a_filtered_value makes use of $this->hooks property to call the Striatum API method. Testing the method in isolation is very simple too, an example using PHPUnit and Mockery:

So the method is tested in isolation, mocking the behavior of a filter: easy and straightforward.

If the classes had used the core apply_filters this simple test would be very hard and had required a testing package like the awesome wp_mock by 10up or the simpler, but less powerful HooksMock by myself.

Gotchas!

Striatum is a Brain module. As you can read in Brain readme, it bootstrap itself and its modules on after_setup_theme with priority 0, this mean that you can't use Striatum to attach callbacks to hooks that are triggered before after_setup_theme.

There are not so many hooks fired before after_setup_theme, and all are available only for plugins and not themes, so if you use Striatum in themes you will not miss anything. Main hooks not available in Striatum are: muplugins_loaded (only for mu-plugins), plugins_loaded, sanitize_comment_cookies, setup_theme and load_textdomain.

Requirements

• PHP 5.4+
• Composer (to install)
• WordPress 3.9 (it maybe works with earlier versions, but it's not tested and versions < 3.9 will never supported).

Installation

You need Composer to install the package. It is hosted on Packagist, so the only thing needed is insert "brain/striatum": "dev-master" in your composer.json require object

{
    "require": {
        "php": ">=5.4",
        "brain/striatum": "dev-master"
    }
}

See Composer documentation on how to install Composer itself, and packages.

Codename: Striatum

The Striatum, also known as the neostriatum or striate nucleus, is a subcortical part of the forebrain. Seems that human perception of timing resides in that part of brain.

Striatum is so called because is a Brain module, and it's function regards the timing aspect of WordPress: hooks.

Developers & Contributors

Package is open to contributors and pull requests. It comes with a set of unit tests written for PHPUnit suite. Please be sure all tests pass before submit a PR. To run tests, please install package in stand-alone mode (i.e 'vendor' folder is inside package folder). When installed in dev mode Striatum also install Mockery, a powerful mocking test utility, and HooksMock a package that was written expressly to test Striatum.

License

Striatum own code is licensed under GPLv2+. Through Composer, it install code from:

• Composer (MIT)
• Brain (GPLv2+)
• Pimple (MIT) - required by Brain -
• PHPUnit (BSD-3-Clause) - only dev install -
• Mockery (BSD-3-Clause) - only dev install -
• HooksMock (GPLv2+) - only dev install -