DEV Community: Marcus Kober

Elevate Your Plugin Development with Hook-Driven-Development

Marcus Kober — Thu, 25 May 2023 06:45:30 +0000

After the previous article in this series was very technical, today we'll take a breather and indulge in a slightly more theoretical piece. Our topic is Hook-Driven-Development and why you too should implement it in your plugins.

In WordPress plugin development, hooks are a fundamental and indispensable tool. Hooks ensure that a plugin is extendable, scalable, and remains cleanly structured. Hook-Driven-Development is an approach in plugin development that not only involves using the existing hooks of WordPress and other plugins but also incorporating your own hooks and using them within the plugin itself.

In this article, I assume a basic understanding of hooks and their use in developing WordPress plugins.

Advantages of Hook-Driven-Development

We don't want to use Hook-Driven-Development just for fun – its application also has some compelling advantages.

Advantage 1: Modularity and Flexibility

By consistently using hooks in your plugin, you enhance its modularity and flexibility.

Ease of Modification and Expansion
Hooks allow for easier code adaptation to individual or new needs. They also facilitate the addition of extra functions without changing existing code. New functions, when using hooks, can either be defined in the actual plugin code, or added via additional plugins (e.g., addons). This enables you to offer a plugin in a free and a paid version. You develop the free version as a complete plugin, and the additional functions of the paid version are then integrated as a paid addon plugin. However, if you want to implement such a model of a free and paid version, please ensure the free version provides real added value and avoid angering your users with an inadequate free version that wants to sell the paid version at every turn! There are already far too many such plugins.
Replacement of Components
The modular nature of plugins developed via Hook-Driven-Development allows individual components of the plugin to be easily replaced without affecting the rest of the code.

Maintainability and Scalability

The maintainability and scalability of your plugin also benefit from hook-based development.

Better Structuring of Large Projects Here we are back to my favorite topic! By strictly using hooks as a fundamental element of code structuring, it becomes much easier to implement well-designed plugins that can naturally grow and remain transparent. The question of where to put newly implemented code will rarely (if ever) arise.
Easier Updating and Debugging With clearly defined hooks and the corresponding callbacks in small classes, updating individual components and troubleshooting becomes significantly easier – all without affecting the entire system.

Interoperability and Collaboration

The use of hooks facilitates interoperability between plugins and cooperation among developers.

Interoperability As a clear interface, hooks facilitate communication between plugins. To reflect the adaptability of WordPress and many plugins in your plugin, you should offer hooks at important points in your plugin. Of course, it's absolutely permitted to leave certain things without hooks if these things should not be changeable for security reasons.
Easier Cooperation through Shared Standards Hooks form the common basis in plugin development, which is familiar to all plugin developers. This makes it easier to win developers for collaborative development. But your plugin will also gain respect in the developer community when you define enough hooks so that your plugin can be customized to individual needs.

Principles of Hook-Driven-Development

All this sounds great, but what should it look like in practice? I will outline that here.

Actions and Filters as the Central Concept in Plugin Development

We define Actions and Filters as the central concept in plugin development. You are probably familiar with the MVC pattern (Model, View, Controller). In a way, one could say that in hook-driven development, the hooks (or the classes whose methods serve as callbacks for hooks) take on the role of the controllers from the MVC approach. In the MVC pattern, the controller is the central control unit between the model (i.e., the business logic) and the view.

In our hook-driven approach, the hooks, or the classes containing hooks, form the central control unit.

Designing Plugin Architecture Around Hooks

An effective hook-driven development strategy requires that the plugin architecture be designed from the ground up to integrate hooks. This means structuring the code in a way that it is broken down into smaller, reusable modules and these modules then communicate via hooks.

This promotes the efficient structuring of the plugin into reusable modules, a clear separation of functions and responsibilities. As a result, the plugin can be easily and quickly extended in the future and is simple to maintain and test.

Definition and Use of Own Hooks

If your plugin already uses hooks from WordPress and/or other plugins (which it should), it probably still does not automatically already rely on hook-driven development. Only the definition and use of own hooks in sufficiently extensive plugins forms the basis for well-implemented and successful hook-driven development.

By using your own hooks, you open up your plugin to the outside world and allow other developers to build upon your plugin or modify individual aspects while simultaneously ensuring a good structure for your code.

Best Practices for Hook-Driven-Development

For your hook-driven approach to be truly successful and to facilitate the structuring of your plugin on the one hand, and to meaningfully open up your plugin to the outside on the other hand, you should consider a few best practices. Only in this way is effective and sustainable implementation possible.

Naming Conventions

Choosing unique and meaningful names for hooks is crucial for the readability and understandability of the code. Here are some recommendations for effective naming conventions:

Use of a Prefix So that the hooks of your plugin are directly recognizable as such, they should consistently use their own prefix. This also makes it less likely that identical hook names will be defined by WordPress or other plugins. The prefix could be the name of your plugin, if it is short enough, or you could use an abbreviation of the plugin name. The hooks of WooCommerce, for example, all start with woocommerce_.
Use Descriptive Names Choose descriptive names for your hooks. It should be as clear as possible what your hook is used for. It should be clear that a name like myplugin_hook_1 is of little use, while myplugin_menu_items suggests that it could be a filter for menu entries.
Consistent Notation Maintain a consistent notation of your hook names. How you write the hooks is not very relevant - the important thing is not to mix different notations. WordPress and therefore many plugins use the underscore (myplugin_menu_items), while others also use camelCase (mypluginMenuItems). For particularly extensive plugins with many hooks, the use of slashes (myplugin/navigation/menuItems) could lead to more clarity, and there are some examples of this in the plugin world, such as the well-known plugin Elementor.

Documentation

Not only developers of other plugins need good documentation of your plugin's hooks. You yourself (or especially your team, if you have one) also need this documentation. After some time, you will be very happy to be able to look up what a certain hook does and where it is used.

There are two approaches:

Inline Comments For you and other developers, it is especially important to rely on inline comments when there are functions and dependencies that are not directly evident from the hook name and the underlying code. The general rule of PHP comments applies here: use as few inline comments as possible, but as much as necessary.
External Documentation Especially for extensive plugins, it can be advantageous to create external documentation. You can create this on your website or plugin website, or you can use services that are already designed for this purpose, such as GitBook or Read the Docs. There is also an interesting project that automatically documents your hooks: the Pronamic WordPress Documentor. It automatically generates documentation in various formats based on your hook declarations.

Testing the Hooks

Since hooks often serve as interfaces to other plugins or parts of WordPress, it is important to ensure their stability and reliability. This requires careful testing, for example, with PHP Unit, which we will cover in a later article. It is important to consider the following points:

Test Coverage Make sure that all hooks, or their corresponding callbacks, are covered by tests.
Testing Dependencies on External Plugins Dependencies on other plugins should be avoided as much as possible during plugin development. However, if your plugin still requires another plugin, it is important to clearly communicate the dependencies, and your plugin should check if the required plugin is installed and activated during activation using appropriate methods. All dependencies must be tested, and when external plugins are updated, it must be ensured that the communication still works smoothly.
Testing Incompatibilities with Other Plugins Test your plugin in a WordPress installation that has popular plugins installed and activated. Do problems with your hooks occur here, such as name collisions? All of this must be tested to ensure smooth operation.

Backward Compatibility When Renaming Hooks

It may happen that you need or want to rename hooks. Perhaps because you just read this article and have been thinking about your naming conventions.

As long as your plugin is still in development, you only need to make sure to change all occurrences of the hook accordingly.

However, the situation is different if your plugin is already being used on websites. In that case, other plugins (or themes) may be using your hooks. If you were to simply rename your hooks and the new version of your plugin is updated on the websites, the hooks used by other plugins would no longer work. And this could potentially affect the users' websites who use your plugins.

To avoid such conflicts, you need to respond to hook renaming in an appropriate manner.

Let's imagine that you noticed that a hook in your plugin from the early stages of development still uses a hook with the not-so-nice name myplugin_hook_01. While creating your external documentation, you get annoyed by it and decide that the hook should have the new name myplugin_menu_items.

There is a perfect way to achieve backward compatibility in case other developers have already been using myplugin_hook_01 in their plugins (and have already been frustrated by the name)!

For this example, let's assume that the call with the old hook name looks like this:

$menuItems = apply_filters('myplugin_hook_01', $menuItems, $menuId, $menuObject);

In the first step, you rename the hook:

$menuItems = apply_filters('myplugin_menu_items', $menuItems, $menuId, $menuObject);

In the second step, you create a file in your plugin called DeprecatedHooks.php. In this file, you register a callback for the new(!) hook using our PHP attribute method from previous article:

<?php

namespace MK\MyPlugin\Main;

use MK\Attributes\Filter;

class DeprecatedHooks
{
    #[Filter('myplugin_menu_items', 0, 3)]
    public function menuItems(array $menuItems, int $menuId, object $menuObject): array
    {
    }
}

Now we can simply fire the old hook and we're done:

#[Filter('myplugin_menu_items', 0, 3)]
public function menuItems(array $menuItems, int $menuId, object $menuObject): array
{
    return apply_filters('myplugin_hook_01', $menuItems, $menuId, $menuObject);
}

However, this would silently fire the old hook, and other developers would only become aware of the renaming if they read your changelogs.

That's why we have the functions apply_filters_deprecated() and do_action_deprecated.

In our example, we are focusing on filters, but the same applies to actions. Let's take a look at apply_filters_deprecated():

apply_filters_deprecated(
    string $hook_name, 
    array $args, 
    string $version, 
    string $replacement = '', 
    string $message = '' 
)

Great! We can pass the old hook name to the function, all the arguments in the $args array, the version from which the hook was deprecated in $version, and the new hook name in $replacement. Additionally, we can even provide a message regarding the renaming in $message.

In our case, it would look like this:

#[Filter('myplugin_menu_items', 0, 3)]
public function menuItems(array $menuItems, int $menuId, object $menuObject): array
{
    return apply_filters_deprecated(
        'myplugin_hook_01', // Old hook name
        [$menuItems, $menuId, $menuObject], // Arguments as an array
        '1.1.0', // Version of our plugin where the renaming took place
        'myplugin_menu_items', // New hook name
        'Changed the hook name.' // Message
    );
}

Now, the old hook still works as if nothing has changed. However, WordPress will throw a deprecation notice that will be displayed if the WP_DEBUG constant in the wp-config.php file is set to true:

Deprecated: Hook myplugin_hook_01 is deprecated since version 1.1.0! Use myplugin_menu_items instead. Changed the hook name.

The same concept applies to actions using the do_action_deprecated() function.

By following this approach, we have achieved everything that is important when renaming a hook:

The hook has been renamed.
The old hook continues to function for backward compatibility.
Other developers or our development team will be warned when using old hooks.

Examples of Successful Hook-Driven Plugins

There are already many excellent plugins that utilize hook-driven development. The extent to which a plugin is entirely based on hooks may vary. The following plugins can serve as good examples, although they may not be suitable examples in all aspects of architectural decisions.

WooCommerce

WooCommerce is the E-Commerce plugin for WordPress, developed by Automattic, the company founded by Matt Mullenweg, the creator of WordPress. WooCommerce:

Offers a wide range of hooks that allow for extensive extension and customization of WooCommerce.
Utilizes the hooks defined within the plugin extensively for its own functionality.
Serves as a great example of the possibility for extension through standalone add-on plugins, which WooCommerce distributes as modular paid plugins.

Advanced Custom Fields

The well-known plugin Advanced Custom Fields, commonly loved by developers, especially during the pre-Gutenberg era, is another excellent example of hook-driven development. Originally developed by Elliot Condon, acquired by Delicious Brains, and now driven by WP Engine.

Even today, the plugin remains powerful and essential and can serve as a good example of hook-driven development. ACF provides many hooks for developing great extensions.

These are just a few examples of successful hook-driven plugins. While the level of implementation may vary, they demonstrate the benefits and possibilities of hook-driven development.

Code Example

While we can't develop a complete plugin using hook-driven development in this text, I can provide a small example to illustrate the concept. Please note that due to space limitations, the example may be simplified.

Let's assume you have developed a plugin that needs to add menu items to a specific menu with the slug main-menu. You're already using the hook "wp_nav_menu_{$menu->slug}_items" to achieve this (documentation):

class FrontendMenu
{
    #[Filter('wp_nav_menu_main-menu_items', 10, 2)]
    public function addMenuItems(string $items, object $args): string
    {
        $newItems = [
            'dashboard' => [
                'url' => esc_url(get_permalink(get_option('myplugin_dashboard_page_id'))),
                'title' => 'Dashboard',
            ],
            'faq' => [
                'url' => esc_url(get_permalink(get_option('myplugin_faq_page_id'))),
                'title' => 'FAQ',
            ],
        ];

        $newItems = array_map(function($menuItem) {
            return sprintf(
                '<li><a href="%s">%s</a></li>',
                $menuItem['url'],
                $menuItem['title']
            );
        }, $newItems);

        $items .= implode("\n", $newItems);

        return $items;
    }
}

In this code, we register the addMenuItems() method as a callback for the wp_nav_menu_main-menu_items hook. Inside the method, we define an array $newItems that contains the new menu items. We use array_map() to transform the menu item arrays into HTML list item strings. Finally, we concatenate the new items to the $items string and return it.

Now, let's take a step towards hook-driven development and expose the new menu items to the outside so that we and other developers can manipulate the items. We introduce a new filter called myplugin_menu_items:

#[Filter('wp_nav_menu_main-menu_items', 10, 2)]
public function addMenuItems(string $items, object $args): string
{
    $newItems = apply_filters('myplugin_menu_items', [], 'main-menu', $args);

    $newItems = array_map(function($menuItem) {
        return sprintf(
            '<li><a href="%s">%s</a></li>',
            $menuItem['url'],
            $menuItem['title'],
        );
    }, $newItems);

    $items .= implode("\n", $newItems);

    return $items;
}

We pass an empty array as the default value to our new filter, along with the menu slug and the $args object of the original filter, in case we or other developers need it. In the original class, we can then populate the menu:

class FrontendMenu
{
    #[Filter('wp_nav_menu_main-menu_items', 10, 2)]
    public function addMenuItems(string $items, object $args): string
    {
        $newItems = apply_filters('myplugin_menu_items', [], 'main-menu', $args);

        $newItems = array_map(function($menuItem) {
            return sprintf(
                '<li><a href="%s">%s</a></li>',
                $menuItem['url'],
                $menuItem['title'],
            );
        }, $newItems);

        $items .= implode("\n", $newItems);

        return $items;
    }

    #[Filter('myplugin_menu_items', 10, 3)]
    public function generateMenuItems(array $items, string $menuSlug, array $args): array
    {
        if ('main-menu' !== $menuSlug) {
            return $items;
        }

        $newItems = [
            'dashboard' => [
                'url' => esc_url(get_permalink(get_option('myplugin_dashoboard_page_id'))),
                'title' => 'Dashboard',
            ],
            'faq' => [
                'url' => esc_url(get_permalink(get_option('myplugin_faw_page_id'))),
                'title' => 'FAQ',
            ],
        ];

        return array_merge($items, $newItems);
    }
}

So, first, we apply the filter using apply_filters with an empty array to populate it in the generateMenuItems() method.

What have we achieved with this approach?

Flexibility:
- We can now add new menu items from anywhere in our code by using the myplugin_menu_items hook. For example, we can conditionally display a login or logout link based on whether a user is logged in.
- By decoupling the addition of menu items from the wp_nav_menu_main-menu_items hook, we have the flexibility to insert new menu items before the Dashboard link by using the myplugin_menu_items hook with a priority of 9.
Extensibility:
- We allow other plugins to modify the list of new menu items. Other plugins can add or remove menu items to our plugin's menu.
- Our own code or add-on plugins can also influence the menu by utilizing the myplugin_menu_items hook.
Testability:
- The array containing the new menu items can now be the subject of tests.

This was just a small and perhaps somewhat contrived example, but it demonstrates the approach and benefits of hook-driven development. In the remaining articles, the concept will become even clearer.

Conclusion and Outlook

In this article, we learned about what Hook-Driven Development is, the benefits it brings to WordPress plugin development, and the best practices involved. We also saw a small code example that demonstrated how this approach can be implemented in real-world scenarios.

In the next article, we will learn about using Dependency Injection in WordPress plugins. We will explore why Dependency Injection may be necessary, especially when utilizing hook registration via PHP attributes.

How to register WordPress hooks with PHP attributes: A step-by-step guide

Marcus Kober — Fri, 19 May 2023 07:11:47 +0000

In this article, I will discuss how and why WordPress hooks are used in plugins, and how we will use PHP attributes for registering hooks in classes effectively and clearly.

What are hooks and how do they work?

Since I assume a certain level of knowledge about WordPress plugin development for this article series, there is a good chance you are already familiar with hooks. If not, you should learn about hooks now. However, I still want to provide a brief overview as an introduction.

A brief introduction to hooks

Hooks are the most important tool for plugin developers. With hooks, code can be executed at specific predefined points, and data can be modified. Hooks are somewhat similar to events that are fired at certain points in the code, and they are what allow plugins to extend and modify WordPress in the first place!

Please NEVER use methods other than hooks if you want to create a clean and secure plugin! Other methods here refer to modifying core files or any other types of hacks.

There are two types of hooks:

Filters, which allow you to modify data
Actions, which allow you to execute code at specific points

Hooks consist of a hook name and a callback function that can be attached to the hook.

The callback functions of filters always have a return statement, while the callbacks of actions usually do not require one.

Filters

Let’s briefly take a look at the function apply_filters() (documentation). This function allows us to execute the callbacks that have been added to a filter name. Any number of callbacks can be added to a filter name.

Suppose you want to allow another plugin to modify your plugin’s data. Let’s say you have developed a book management system as a WordPress plugin, and you have decided that the book management system should only allow science fiction books and horror thrillers. However, you want other developers to be able to create their own plugins that extend your book management system.

In your plugin, you use a method called isGenreValid() to check if the book belongs to the correct genre. This could look like this:

public function isGenreValid(string $genre): bool
{
    $genres = [
        'Science Fiction',
        'Horror thriller'
    ];

    return in_array($genre, $genres);
}

With that, both genres are hard-coded inside the function and can’t be changed from outside. To allow another plugin to modify your genre list, you can work with apply_filters():

public function isGenreValid(string $genre): bool
{
    $genres = [
        'Science Fiction',
        'Horror thriller'
    ];

    $genres = apply_filters('myplugin_book_genres', $genres);

    return in_array($genre, $genres);
}

Now, another plugin (or even your own code, as we’ll see later) can hook into the myplugin_book_genres filter and extend or completely replace the list. If there is no callback for this filter, the original list will be returned, which you specify as the second argument in apply_filters().

The other plugin can then register a callback using add_filter() that modifies the genre array. This could look like this, using an anonymous function, for example:

add_filter('myplugin_book_genres', function(array $genres) {
    $genres[] = 'Drama';

    return $genres;
});

Now, if the genre drama is passed to the isGenreValid() method, it will return true!

Let’s say, in your book management plugin, it’s possible to create virtual bookshelves. Perhaps it’s important for the code hooking into the filter to know which virtual bookshelf is currently selected. The ID of the bookshelf is stored in the class variable $shelfId.

You can add any number of additional arguments to the apply_filters() function to provide more information to the callback that hooks into the hook. This is where we can pass the ID of the bookshelf:

$genres = apply_filters('myplugin_book_genres', $genres, $this->shelfId);

In the callback function of this hook, we are now able to modify the genre list depending on the shelf ID:

add_filter('myplugin_book_genres', function(array $genres, int $shelfId) {
    switch ($shelfId) {
        case 1:
            $genres[] = 'Drama';
            break;
        case 2:
            $genres[] = 'Comedy';
            break;
    }

    return $genres;
}, 10, 2);

There are added two additional arguments to add_filter(): 10 and 2. 10 is the priority of the callback in the list of callbacks registered to the hook, and 2 is the number of arguments passed to the callback. The number of passed arguments has to be 2 here, because we need to get $genres and $shelfId.

The priority specifies, in which order the callbacks get called if multiple callbacks are registered for a hook. In case you want your code to run earlier than the other callbacks, you have to choose values lower than the default value of 10. Should the code run later, choose values greater than 10. Callbacks registered with the same priority are called in the order they were registered.

Let’s look at the syntax of add_filter():

add_filter( string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1 ): true

As you can see, the default value for $priority is 10, and the default for $accepted_args 1.

Actions

While filters allow data to be modified in specific ways with their callbacks returning the corresponding value, actions interrupt the flow of the code to allow for other additional (external) code to be executed.

The function to run an action is named do_action(). Let’s compare it to its counterpart apply_filters():

apply_filters( string $hook_name, mixed $value, mixed $args ): mixed

do_action( string $hook_name, mixed $arg )

As we can see, do_action() lacks the $value argument, which contains the value that gets filtered, and there’s no return value. However, like its filter counterpart, do_action() can also be given required arguments.

The callback, that gets registered via add_action(), runs immediately where do_action() is called.

The function add_action() has the same syntax as add_filter():

add_action( string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1 ): true

Let’s assume, you want to load a specific CSS file in frontend. In this case you have to use the action hook wp_enqueue_scripts:

add_action('wp_enqueue_scripts', function() {
    wp_enqueue_style('myplugin-style', plugins_url('assets/dist/css/my-plugin.css'));
});

This ensures that the wp_enqueue_style() function is called exactly where it is needed for working properly!

Actions are actually filters

Actions are essentially a special case of filters. This becomes clearer, when we take a closer look at the source code of the add_action() function:

function add_action( $hook_name, $callback, $priority = 10, $accepted_args = 1 ) {
    return add_filter( $hook_name, $callback, $priority, $accepted_args );
}

Behind the scenes, add_action() simply calls add_filter(), passing all arguments – we will use this fact to our advantage below!

But please don’t use add_filter() only

Nevertheless, you should not simply start using only add_filter() from now on – after all, there is a significant difference between actions and filters, and it should always be clear from the code whether a callback is being assigned to an action or a filter.

How do I find out which hooks exist?

As previously mentioned, hooks are essential for WordPress plugin development. The WordPress core has a wealth of hooks to modify almost every aspect of WordPress. Additionally, many plugins leverage hooks, allowing other developers to change the flow and data.

There are basically four different ways to find out which hooks exist. Each method has different advantages and disadvantages and use cases.

1. Google it:

We can search for hooks on Google. This is useful when we wonder if there is a hook for the problem we want to solve. A Google query could look like this: “wordpress hook for adding a class to the body tag”. In this way, the desired hook can usually be found quickly and easily.

2. ChatGPT

We can ask ChatGPT:

Version: ChatGPT 4

Here, we notice how extensively ChatGPT responds, not only providing a code example but also pointing out that the theme must support adding a CSS class to the body tag by using the function body_class().

As always, caution is advised with ChatGPT: firstly, the tool’s knowledge base currently ends in September 2021 (so it cannot know any recent changes), and secondly, it is always better to check and test the provided results!

Nevertheless, this type of hook research is superior to a Google search.

3. Documentation and hook directories

WordPress itself has a list of hooks, and the hooks themselves have their own subpages explaining their usage: Hook Reference
Plugins that use hooks often provide a corresponding directory as well. For example, WooCommerce
There used to be a service called hookr.io, a website that listed Core and Plugin hooks. However, I just discovered that this site no longer exists. This is what it used to look like.

Documentations are often easy to search and provide a good overview of the use of specific hooks. However, they are less suitable for searching for the right hook to solve a particular problem.

4. Searching in the source code of WordPress or plugins

The method that brings you the most from a didactic point of view is the direct search in, or reading of, the source code. As a developer, you should spend a significant amount of time reading and studying other people’s code. And, of course, it’s important to know at least the parts of the code that are relevant to you, which you want to change with hooks. So, open the WordPress core (usually, this will be the files in /wp-includes/) in the code editor of your choice (I recommend VS Code) and search for apply_filters and do_action.

1.681 times apply_filters is found

In this way, you are able to find all filter hooks WordPress is using, and you are learning, how WordPress uses hooks internally. Search for add_filter and add_action too and you will see, that WordPress uses its Hook itself. A method we will talk about later.

405 times add_filter is found

Of course, you should also know the code of a plugin whose hooks you want to use, at least partially, or have it read once. Here you can also search for the used hooks.

Registering hooks inside a class

Now we have found the hook we’ve been looking for and we want to use it in our WordPress plugin. Let’s follow the basic example from above: we have to add a class to the <body> tag using the body_class filter. We assume that this is the first step in the development of a comprehensive plugin, where it will be worthwhile to use advanced programming methods.

We want to define hook registrations inside a class by using class methods for callbacks.There are three classic approaches to this.

Approach 1: Use the class constructor

class Frontend
{
    public function __construct()
    {
        add_filter('body_class', [$this, 'addBodyClass']);
    }

    public function addBodyClass(array $classes): array
    {
        $classes[] = 'my-added-class';

        return $classes;
    }
}

At an appropriate place, such as in the main file of the plugin or the main class (we’ll learn more about this in a later article), the class is then instantiated in some way. To keep things simple here, as this step is irrelevant for our discussion, let’s imagine that in the main file of the plugin, the instantiation takes place: $frontend = new Frontend();.

When the class is instantiated, the constructor is executed, and thus the add_filter function is called. Our callback in the array notation [$this, 'addBodyClass'] is added to the body_class filter with the default priority of 10 and the default number of arguments of 1.

In a lenient view, this is a valid approach to register a filter callback. However, this approach has some drawbacks, especially in large plugins:

We are misusing the class constructor to execute the add_filter call. Strictly speaking, the constructor of a class should be used to assign the correct values to its parameters at the time of instantiation, in other words, to initialize the object.
When we learn about unit testing later in this series, we will see that calling add_filter() in the constructor makes testing the class more difficult. We haven’t covered unit testing yet, but I would like to briefly mention here the points that make using add_filter() in the constructor challenging for testing:
1. By calling add_filter(), the class becomes tightly coupled with WordPress. This makes it harder to test the class in isolation from WordPress, and we would have to work with elaborate mocks just to be able to test it properly.
2. We violate the rule stating that class constructors should not have side effects but should only be responsible for object initialization. The side effect of adding the callback to the filter makes testing more complicated. Therefore, we need an approach that allows us to avoid calling add_filter() from the constructor.

Approach 2: Register from outside the class

In the second approach, we will remove the add_filter() call from the class context and perform the call after the class is instantiated:

class Frontend
{
    public function addBodyClass(array $classes): array
    {
        $classes[] = 'my-added-class';

        return $classes;
    }
}

$frontend = new Frontend();
add_filter('body_class', [$frontend, 'addBodyClass']);

This is a significant improvement for the class itself. The class is now better suited for unit testing, and we no longer misuse the class constructor. In our example, the class no longer needs a constructor.

However, there are also drawbacks to this approach.

Drawback 1: Separation of add_filter() call and class/method

When considering the overall structure of our plugin, contemplating its architecture, the question quickly arises as to where the class should be instantiated. Since we want to rely entirely on autoloading (it wouldn’t be ideal to use autoloading for some classes while loading others with require_once()), the instantiation of the class cannot happen in the PHP file of the class itself.

We have the class file src/Main/Frontend.php:

<?php

namespace MK\MyPlugin\Main;

class Frontend
{
    public function addBodyClass(array $classes): array
    {
        $classes[] = 'my-added-class';

        return $classes;
    }
}

The call of add_filter() is then done, however, e.g. in the main file my-plugin.php:

<?php
/*
 * Plugin Name: My Plugin
*/

use MK\MyPlugin\Main\Frontend;

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

$frontend = new Frontend();
add_filter('body_class', [$frontend, 'addBodyClass']);

So, the registration of the addBodyClass() method of the Frontend class using add_filter() is located in a different file from the class itself. This can lead to a state of unmanageable complexity and that makes changes more difficult, especially in large plugins.

For example, if we realize that the number of arguments needs to be adjusted for a filter, we are forced to edit two files: we have to pass the number of arguments to the add_filter() call in the main plugin file and then add the arguments themselves to the method in the class file.

Furthermore, just by looking at the Frontend class in our example, we cannot tell that the addBodyClass() method is a callback for a hook. We would need to indicate this through a suitable PHP comment:

/**
 * Callback for Filter body_class
 */
public function addBodyClass(array $classes): array

Here, we would need to establish a standard for such comments because if a team is working on the plugin, the hook comments should always have a consistent structure.

Drawback 2: Complexity of registration code

This structure quickly leads to an ever-growing list of registration calls and class instantiations:

<?php
/*
 * Plugin Name: My Plugin
*/

use MK\MyPlugin\Main\Frontend;
use MK\MyPlugin\Admin\Dashboard;

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

$frontend = new Frontend();
$backendDashboard = new Dashboard();
// ...

add_filter('body_class', [$frontend, 'addBodyClass']);
add_action('wp_enqueue_scripts', [$frontend, 'enqueueAssets']);
add_action('admin_init', [$backendDashboard, 'registerDashboard']);
// ...

The long lists of class instantiations and hook registrations quickly become unwieldy. More questions arise:

How should the calls be organized – alphabetically, by class, by hook?
How do we maintain an overview and create a quick reference in the code to determine which methods belong to which class?

Approach 3: Back to the class

Approach 3 is the version I have used in my plugins for a long time. In this approach, we bring the hook registration back into the class to have the registrations closer to the methods:

class Frontend
{
    public static function register(): void
    {
        $self = new self();

        add_filter('body_class', [$self, 'addBodyClass']);
    }

    public function addBodyClass(array $classes): array
    {
        $classes[] = 'my-added-class';

        return $classes;
    }
}

The class can then be instantiated with just one call, for example, in the main plugin file:

<?php
/*
 * Plugin Name: My Plugin
*/

use MK\MyPlugin\Main\Frontend;

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

Frontend::register();

If we have many classes, the list of ::register() calls can become long, and we will need to consider how to organize it differently. However, at least:

We are not using the constructor for hook registration with add_filter().
The hook registration is happening within the class that also contains the callback method.
This construction is somewhat better for unit testing, as the aforementioned side effect is easier to control through the static method, making the class more suitable for unit testing.

Nevertheless, this method also has its drawbacks:

If multiple hooks are registered within a class, the static method may contain long lists of add_filter() and add_action() calls.
With multiple hooks, the code becomes less organized as the registration calls in the static method are relatively far from their associated methods. Again, we would need to use appropriate comments to indicate which method belongs to which hook.
For unit testing, this method is more suitable, but it would still be nice if the static method could be eliminated.

Registering hooks using PHP attributes

I occasionally enjoy reading the source code of non-WordPress projects and I’m interested in the structure of large frameworks like Symfony and Laravel.

In Symfony’s routing, I came across the use of PHP attributes for defining routes (see here).

It looks something like this:

#[Route('/api/posts/{id}', methods: ['GET', 'HEAD'])]
public function show(int $id): Response

I found that very elegant and immediately saw the resemblance to the registration of hooks in WordPress plugins!

What are PHP attributes?

PHP attributes are metadata used to provide additional information about declarations such as classes, methods, properties, or functions. They allow you to write declarative code that influences the behavior of the corresponding elements in a clean and organized way.

How are PHP attributes defined?

PHP attributes serve as metadata for classes, methods, functions, parameters, properties, and constants, and they are declared directly on the line above the element that should be adorned with an attribute.

An attribute begins with the hash sign (#), while the attribute itself is enclosed in square brackets. The simplest declaration looks like this:

#[AttributName]

Attributes can also have parameters:

#[AttributName('value')]

We mainly use attributes on methods in this article, so the examples provided focus on that usage.

What is important for us is also the ability to use attributes multiple times since it may be necessary to define two different hooks for a method:

#[Attribut1('value')]
#[Attribut2('value')]
public function someMethod(): void

Attributes for hook registration

Now, we want to achieve the ability to bind hook declarations directly to the method, so that our class looks like the following example. I have expanded the class with an additional hook to make it more illustrative:

class Frontend
{
    #[Filter('body_class')]
    public function addBodyClass(array $classes): array
    {
        $classes[] = 'my-added-class';

        return $classes;
    }

    #[Action('wp_enqueue_scripts')]
    public function enqueueAssets(): void
    {
        wp_enqueue_style('my-plugin', 'style.css');
    }
}

At a glance, we can see the advantages that PHP attributes offer compared to the other methods!

No more need for a static method.
By using PHP attributes, the declaration of the hook is in direct proximity to the respective method. This is clear and concise, and we immediately know that the method is a callback for a hook. We can make changes in direct correlation to the method.
The class is not only easier to cover with unit tests, but we can even establish tests to verify that the correct attributes, i.e., the correct hook registrations, are used.

However, we still have two major issues to address:

How do PHP and WordPress know what to do with these attributes?
How and where should classes with hooks be instantiated? Fortunately, these questions are answered by each other, as we will see shortly.

Defining Attributes

First, we need to inform PHP that we want to use two attributes named Filter and Action, which accept the hook name, priority, and number of arguments as parameters.

To do this, we create the folder Attributes inside src/ and create the file Filter.php inside it. With this addition, our sample plugin now has the following structure:

my-plugin
├── src
│   ├── Attributes
│   │   └── Filter.php
│   └── Main
│       └── Frontend.php
└── my-plugin.php

An attribute in PHP is nothing more than a simple class with its constructor setting the parameters for the attribute. We use constructor property promotion to define the parameters:

File src/Attributes/Filter

<?php

namespace MK\MyPlugin\Attributes;

class Filter
{
    public function __construct(
        public string $hookName,
        public int $priority = 10,
        public int $acceptedArgs = 1
    )
    {}
}

To inform PHP that our simple class is an attribute definition, we can use, ironically, an attribute itself. The attribute declares our Filter class as an attribute:

<?php

namespace MK\MyPlugin\Attributes;

use Attribute;

#[Attribute]
class Filter
{
    public function __construct(
        public string $hookName,
        public int $priority = 10,
        public int $acceptedArgs = 1
    )
    {}
}

With that, we have successfully defined our Filter attribute. We can further specify that the Filter attribute can only be used on methods and that we can use the attribute multiple times on a single method. We do this by specifying the corresponding flags for the attribute: Attribute::TARGET_METHOD and Attribute::IS_REPEATABLE:

#[Attribute(Attribute::TARGET_METHOD|Attribute::IS_REPEATABLE)]
class Filter

Here you can find more about attribute declaration in PHP.

So, we have established the Filter attribute, but it doesn’t do anything yet. We now have three steps ahead of us:

Find a method for instantiating classes with hooks.
Find a way to recognize that a class uses hooks.
Actually register the hooks using add_filter() and add_action().

Loading, parsing, and instantiating classes with hooks

We will now take care of steps 1 and 2 from the previous section. To do this, we need to tell our plugin where to find the classes that we want to check for hooks.

For the overall architecture, it is important that the classes using hooks should not be instantiated elsewhere. They should only be instantiated through the code we are about to develop. Since classes should generally do only one thing and not have too much responsibility, this should not be a problem.

There are different ways to locate the classes that use hooks. We could search through all classes, but that wouldn’t be very performant.

First, we create a directory in the root folder of our plugin, which we can name config, and create a file inside it, which can be named hooked-classes.php, for example:

my-plugin
├── config
│   └── hooked-classes.php
├── src
│   ├── Attributes
│   │   └── Filter.php
│   └── Main
│       └── Frontend.php
└── my-plugin.php

In the PHP file, we now list our only class that uses hooks:

<?php

use MK\MyPlugin\Main\Frontend;

/**
 * List of classes with hooks
 */
return [
    Frontend::class,
];

So, the file simply returns an array with the fully qualified class name of Frontend (::class is a static constant that contains the fully qualified class name, more here).

Next, we want to remove the main code from the plugin file my-plugin.php and establish a plugin main class called App, which we include under Main:

my-plugin
├── config
│   └── hooked-classes.php
├── src
│   ├── Attributes
│   │   └── Filter.php
│   └── Main
│       ├─── App.php
│       └── Frontend.php
└── my-plugin.php

Now, the App class in the _App.php _file is lean:

<?php

namespace MK\MyPlugin\Main;

class App
{
    public function init(): void
    {
    }
}

And the my-plugin.php file is now very clean as well, but we need to define a constant that contains the path of the plugin:

<?php
/*
 * Plugin Name: My Plugin
 */

use MK\MyPlugin\Main\App;

define('MYPLUGIN_DIR', plugin_dir_path( __FILE__ ));

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

(new App())->init();

In the main class, we now establish a private method that will handle our classes with hooks, and in the constructor of the class, we load the list of class names:

<?php

namespace MK\MyPlugin\Main;

class App
{
    public function __construct(
        private array $classNames = [];
    )
    {
        $this->classNames = require MYPLUGIN_DIR . 'config/hooked-classes.php';

    }

    public function init(): void
    {
        $this->registerHooks();
    }

    private function registerHooks(): void
    {
        foreach ($this->classNames as $className) {
            // Code for registering hooks
        }
    }
}

In the registerHooks() method, we process the class names in a foreach loop. But what exactly do we do with the class names we obtain in this way? How can we find out if and which hooks are registered here?

We make use of PHP’s Reflection API for this purpose. With this API, we can examine classes at runtime of the script.

In our loop, we first create a reflection class of the original class using new ReflectionClass() (more about ReflectionClass). The reflection class can then provide us with all the methods of the class to be examined using the getMethods() method (more about this method).

foreach ($this->classNames as $className) {
    $reflectionClass = new ReflectionClass($className);

    foreach ($reflectionClass->getMethods() as $method) {
        // Check methods for attributes
    }
}

Now we check if the method has attributes. The getAttributes() method (more info) can return all Filter attributes in an array by passing the class name of our attribute to the method. If filter attributes are defined, we can then iterate over them with another foreach loop:

foreach ($reflectionClass->getMethods() as $method) {
    $attributes = $method->getAttributes(Filter::class);

    foreach ($attributes as $attribute) {
        // Check attributes
    }
}

In this final loop, we finally instantiate our class containing hooks and then need to figure out how to register the callback using add_filter(). To do this, it would be good if we could first instantiate the attribute class Filter. Fortunately, we can do this using the newInstance() method of $attribute:

foreach ($attributes as $attribute) {
    // Instantiate class with hooks
    $hookedClass = new $className();

    // Instantiate filter class
    $filterClass = $attribute->newInstance();
}

Now we have everything we need in one place: we have an instance of the Frontend class, an instance of the attribute class Filter, and the method adorned with a filter attribute. We want to define the registration process within the Filter class itself. To do this, we establish a register() method that passes the callback as an array:

#[Attribute]
class Filter
{
    public function __construct(
        public string $hookName,
        public int $priority = 10,
        public int $acceptedArgs = 1
    )
    {}

    public function register(callable|array $method): void
    {
        add_filter(
            $this->hookName,
            $method,
            $this->priority,
            $this->acceptedArgs
        );
    }
}

Now that the register method is established, we can call it within the loop in the registerHooks method in the App.php file:

foreach ($attributes as $attribute) {
    // Instantiate class with hooks (Frontend in our case)
    $hookedClass = new $className();

    // Instantiate filter class
    $filterClass = $attribute->newInstance();
    $filterClass->register(
        [
            $hookedClass,
            $method->getName()
        ]
    );
}

Now we are almost finished with the filter. We just need to ensure that each class with hooks is instantiated only once in registerHooks. Multiple instantiation is not necessary here. To achieve this, we create an instance array and check whether the class has already been instantiated. For clarity, here is the complete method again:

private function registerHooks(): void
{
    $instances = []; 

    foreach ($this->classNames as $className) {
        $reflectionClass = new ReflectionClass($className);

        foreach ($reflectionClass->getMethods() as $method) {
            $attributes = $method->getAttributes(Filter::class);

            foreach ($attributes as $attribute) {
                // Instantiate class if not instantiated
                if (! array_key_exists($className, $instances)) {
                    $instances[$className] = new $className();
                }

                // Instantiate filter class
                $filterClass = $attribute->newInstance();
                $filterClass->register(
                    [
                        $instances[$className],
                        $method->getName()
                    ]
                );
            }
        }
    }
}

Indeed, we have now completed the registration of filters! We would now need to do the same for actions. But of course, this can be done more easily.

Let’s take another look at this line:

$attributes = $method->getAttributes(Filter::class);

And now let’s check what we can do with getAttributes():

public ReflectionFunctionAbstract::getAttributes(?string $name = null, int $flags = 0): array

Interesting, so we can provide flags! A look at the documentation shows that we can set the flag ReflectionAttribute::IS_INSTANCEOF, which means that filtering is no longer done by the exact name of the attribute class, but instead instanceof is used for filtering.

This naturally leads us to the idea of using an interface for the attributes. We create two new files in our Attributes folder: Action.php and HookInterface.php:

my-plugin
├── config
│   └── hooked-classes.php
├── src
│   ├── Attributes
│   │   ├── Action.php
│   │   ├── Filter.php
│   │   └── HookInterface.php
│   └── Main
│       ├── App.php
│       └── Frontend.php
└── my-plugin.php

In the HookInterface.php file, we establish our interface that requires our hook attributes to implement a register() method:

<?php

namespace MK\MyPlugin\Attributes;

interface HookInterface
{
    public function register(callable|array $method): void;
}

In the Filter.php file, we now need to declare the Filter class as an implementation of HookInterface:

#[Attribute(Attribute::TARGET_METHOD|Attribute::IS_REPEATABLE)]
class Filter implements HookInterface

With that, we are indeed completely done with the filter.

Creating the Action Attribute

Creating the Action attribute class is now the easiest task. As we saw earlier, add_action() internally just calls add_filter(), which is why we can work with inheritance here. We open the Action.php file and create the following code:

<?php

namespace MK\MyPlugin\Attributes;

use Attribute;

#[Attribute(Attribute::TARGET_METHOD|Attribute::IS_REPEATABLE)]
class Action extends Filter
{
}

So, we only create a new class that completely extends the Filter class. All properties from Filter are inherited in Action.

As the last step, we now need to adjust the getAttributes() method in the App::registerHooks() method:

$attributes = $method->getAttributes(HookInterface::class, ReflectionAttribute::IS_INSTANCEOF);

Thus, getAttributes() returns all attributes that implement the HookInterface, which in our case are the attribute classes Filter and Action.

Conclusion and Outlook

In this article, you have learned what hooks in WordPress are and how to register callbacks for hooks. We have seen the methods for registering hooks in classes and how to use autoloading, namespaces, and PHP attributes to implement hook registration in a simple, clear, and unit-test-compatible way.

The solution we have developed is complex but can now be used in any of your plugins that require it. All you have to do is drag the Attributes folder into your new plugin and adjust the namespaces.

In my opinion, we have created a good foundation that defines hooks exactly where the callback is located and ensures that everything is loaded almost magically through autoloading without endless require and instantiation lists. In a later step, we should optimize the registerHooks() method, or create a separate class for it. This will be covered in one of the upcoming articles.

In the next article, we will focus on structuring your plugin in such a way that you can rely solely on hooks. This will make your plugins virtually infinitely extensible and even more maintainable. A nice side effect is that you open your plugin for modifications and adjustments by other plugins.

In a further article, we will return to the techniques described here and learn why dependency injection is a must in this architecture.

Plugin code

You can find the entire plugin code here on GitHub.

Note: Usually, you would add the vendor directory to the .gitignore file, as it has no place in the repository. For the sake of clarity, however, I made an exception here so you can see which code is generated by Composer.

Coding standards part 2: .editorconfig, documentation and strict types

Marcus Kober — Tue, 16 May 2023 09:23:59 +0000

In the previous article, we already learned a lot about coding standards, and today I like to discuss three more points: the file .editorconfig, the documentation of your code, and the declaration of strict types.

The file .editorconfig

The .editorconfig file is a text file you create in the root folder of your plugin. This file ensures, that you and your team use the same standards for line breaks, indentations, and character sets throughout the project. Editors like Visual Studio Code can read this file and apply the formatting and settings automatically. Visual Studio Code requires this extension for that purpose.

The extension for Visual Studio code supports these settings:

indent_style: Indentation style: spaces or tabs
indent_size: Size of indentation when spaces are used (soft tabs)
tab_width: Size of indentation when tabs are used
end_of_line (applied when saving): Type of line breaks
insert_final_newline (applied when saving): Specifies whether an empty line should be added to the end of the file (see PSR-2)
trim_trailing_whitespace (applied when saving): Removes any whitespace after the actual code line

In the .editorconfig, you can set the styles for each programming language or file extension.

My file usually looks like this:

# http://editorconfig.org

root = true

[*]
charset = utf-8
end_of_line = lf
indent_size = 2
indent_style = space
trim_trailing_whitespace = true

[*.php]
indent_size = 4
insert_final_newline = true

[*.scss]
insert_final_newline = true

[*.md]
trim_trailing_whitespace = false

With root = true, it is specified that the file is located in the root directory of your plugin. Text editors like VS Code initially search for a .editorconfig file in the folder of the currently opened code file. If none is found, it searches one folder above, and so on. The line root = true means that the search can end here and the file can be used since root has been reached.

With the declarations under [*], the general settings are made, and below the settings for specific file extensions are overwritten. I want the final newline only in PHP and SCSS files, for example.

Even if you don’t work in a team, I recommend using a .editorconfig file. This ensures that you use the same styles in every project and on every device.

More infos: editorconfig.org.

Documentation

Hated by many developers, it is still an important tool for you and your team. I would like to emphasize here that documenting your code is also important when developing your plugin alone. I promise you will love your documentation when you have to go through your code again after two to three months! Code quickly becomes distant, and after just a few months, you won’t remember specific details, like why you implemented something in a particular way and not differently.

When it comes to documentation, we generally distinguish between two types of documentation:

Documentation in the code itself.
External Documentation.

Documentation inside your code

In PHP, we distinguish not only single-line documentation with a preceding double slash (//) and multi-line documentation in the following form:

/* This is a comment, 
   that spans
   over multiple lines
*/

We also distinguish between documentation at the file, class, and function/method level. I recommend documenting in the PHPDoc format, as used, for example, by phpDocumentor. A PHPDoc block starts not with /*, but with two asterisk symbols: /**. Text editors like Visual Studio Code can quickly create these blocks when typing /**, which reduces typing work.

Here is an example of the various doc blocks.

<?php

/**
 * At the very top appears the file-level documentation. Here you can discuss
 * what exactly is happening in this file. As with all documentation:
 * 
 * Document as much as necessary and as little as possible!
 * 
 * What this means, you can read further below.
 * 
 * Here you can, for example, specify the author and the version with which
 * this file was created:
 * 
 * @author: Marcus Kober
 * @since: 1.2.1
 */ 

declare(strict_types=1);

namespace MK\Test\Main;

use MK\Test\Attributes\Filter;

/**
 * DocBlock at the class level
 * 
 * The DocBlock is created directly before the class to be documented and indicates
 * what the class is for.
 */
class Frontend
{
    /**
     * DocBlock at the variable level
     * 
     * Here you can explain what this variable does
     *
     * @var array
     */
    protected array $addedClasses = [];

    /**
     * DocBlock at the method level
     * 
     * Here you can explain what the method does.
     * 
     * The DocBlock comes before the declaration of attributes, if
     * any are used.
     *
     * @param array $classes
     * @return array
     */
    #[Filter('body_class')]
    public function addClass(array $classes): array
    {
        // Single-line comment, very briefly, explaining something specific
        $this->addedClasses[] = 'my-class';

        return array_merge($classes, $this->addedClasses);
    }
}

The statements starting with @, such as @author or @since, are called “tags” of the DocBlock syntax. Here you can find a list of possible tags. For variables and methods, you can additionally specify types with @var, or @param and @return.

Commenting your code with DocBlocks not only makes your code more transparent for you and your team. You can also use phpDocumentor to create external API documentation from sufficiently well-documented code. This can be added to your external documentation (if you need it) or even replace it.

External Documentation

For very extensive plugins, you can create external documentation either publicly or just for yourself and/or your team. External documentation takes place outside of your code, for example, on a website, or you can use services designed for it, such as GitBook or Read the Docs.

External documentation is particularly important for documenting your own hooks. There is also an interesting project that automatically documents your hooks: the Pronamic WordPress Documentor. It automatically generates documentation in various formats from your hook declarations. You can find more about hooks in the upcoming article on Hook-Driven Development.

Declare strict types

Although the corresponding declaration is missing in most examples in the early articles of this series due to space constraints, I strongly recommend enabling PHP’s strict types check.

The declaration is made with declare(strict_types=1). This should be done in every file of your plugin, and it must be this way to ensure that you fundamentally activate strict type checking. The declare statement is placed immediately after the opening PHP tag at the beginning of the file and before the namespace declaration:

<?php

declare(strict_types=1);

namespace MKMyPlugin;

// use statements

// ...

Refer to this as well: PSR-12: Declare Statements, Namespace, and Import Statements

What does declare(strict_types=1) do exactly?

The statement declare(strict_types=1) enables strict type-checking in PHP. This leads to improved code quality and stability, as using strict type-checking allows errors to be detected more quickly and seen during development in the text editor.

This checks the so-called scalar types, which are int, float, string, and bool.

Let’s take a look at the following function as an example:

function add(float $a, float $b): float
{
    return $a + $b;
}

Without enabling strict type checking, we can run the following without any issues and error messages:

echo add('1.2', 2.4);
// -> 3.6

PHP silently converts the string('1.2') to float(1.2) and then returns the calculated float(3.6).

Since this is a potential source of errors that can be difficult to find, we enable strict type checking in every PHP file with declare(strict_types=1).

Let’s see this in the example:

<?php

declare(strict_types=1);

function add(float $a, float $b): float
{
    return $a + $b;
}

echo add('1.2', 2.4);

This leads to the following error:

Fatal error: Uncaught TypeError: Argument 2 passed to add() must be of the type float, string given

Of course, this also applies to the return value:

<?php

declare(strict_types=1);

function add(float $a, float $b): float
{
    return (string) $a + $b;
}

echo add(1.2, 2.4);

Here, we correctly pass two floats to the add() function. However, since return type hinting is enabled and we specify that the function should return a float, but at the same time cast the result of the addition as a string, we will encounter the following error message:

Fatal error: Uncaught TypeError: Return value of add() must be of the type float, string returned

Important: In order to use type checking correctly, your functions and methods must, of course, use type hinting! Type hinting refers to the type declarations, as seen, for example, in the declaration of the function above. There, we explicitly tell $a and $b that they should be of type float, and we indicate to the function that the return value should also be of type float:

function add(float $a, float $b): float

I strongly recommend equipping all PHP files of your plugin with declare(strict_type=1)!

Conclusion

In this article, you have learned about three ways to make your code cleaner and more maintainable. Two methods deal with the outer form of the code (.editorconfig and documentation), and one with the quality and security of the actual code (Strict Types).

Autoloading, coding standards and file structure in WordPress plugin development

Marcus Kober — Wed, 10 May 2023 09:47:13 +0000

In the last article, I explained the use of namespaces, which we need today to establish autoloading, which simultaneously defines our file and folder structure.

Declare classes in their own PHP files

To keep our code clear, we distribute the code sensibly across several PHP files. Each class should be declared in its own file. This file must then be loaded into the main code (e.g. via require_once()) before the class can be instantiated.

Let’s assume the following folder structure of an example plugin:

my-plugin
├── class-01.php
├── class-02.php
└── my-plugin.php
Content class-01.php:

<?php
class class01
{
    public function __construct()
    {
        echo 'class01 instantiated.';
    }
}

If we now want to instantiate the class01 in the plugin file my-plugin.php, we must first include the file and then we can instantiate the class:

<?php
/**
 * Plugin Name: MyPlugin
 */

require_once __DIR__ . '/class-01.php';

$klasse01 = new class01(

If we also need class02 in this script, we also have to include the corresponding file first and then we can instantiate the class:

<?php
/**
 * Plugin Name: MyPlugin
 */

require_once __DIR__ . '/class-01.php';
require_once __DIR__ . '/class-02.php';

$klasse01 = new class01();
$klasse02 = new class02();

This can quickly become confusing even with a small number of classes and lead to long lists of require_once().

Now a requirement for our plugin changes and we have to introduce a service that must be used by class02, for example.

We add our service as a new class in the service-01.php file:

my-plugin
├── class-01.php
├── class-02.php
├── my-plugin.php
└── service-01.php

<?php
class service01
{
    public function __construct()
    {
        echo 'service01 instantiated.';
    }
}

And change class02:

<?php
class class01
{
    protected service01 $service01;

    public function __construct(service01 $service01)
    {
        $this->service01 = $service01;

        echo 'class02 and service01 instantiated.';
    }
}

Now we have to include the file service-01.png in the main file of the plugin:

<?php
/**
* Plugin Name: MyPlugin
*/

require_once __DIR__ . '/class-01.php';
require_once __DIR__ . '/class-02.php';
require_once __DIR__ . '/service-01.php';

$service01 = new service01();

$klasse01 = new class01();
$klasse02 = new class02($service01);

And at this point, at the latest, it becomes confusing. First, there is a long list of require_once(), and with each new class we need, this list becomes even longer. Moreover, our folder structure no longer looks very clear. In the next step, an inc folder could be introduced, containing all the files we want to include using require_once():

my-plugin
├── inc
│   ├── class-01.php
│   ├── class-02.php
│   └── servie-01.php
└── my-plugin.php

In principle, there is nothing wrong with such a setup at this stage. However, as the plugin becomes more extensive and we have different classes like models, services, and classes with hooks, we also need a folder structure that organizes all the new files in a sensible and clear manner.

In addition, we want to move away from the very long list of require_once() calls.

Preparing for Autoloading and code standards

Autoloading refers to the automatic loading of required files, and to reliably use this, we need to equip our existing code with namespaces and follow certain coding standards. Coding standards affect both the code itself and the folder structure we will use. These standards help bring some order to the chaos that PHP generally allows. There are standards for indenting code (the eternal war: tabs or spaces?), naming variables, functions, classes, and methods, etc.

Why are standards important?

Coding standards lead to more clarity, and they generally provide a schema for how something should look so that developers don’t have to worry about it, and so that everyone can quickly and easily find their way into unfamiliar code, especially in a team.

Coding standards

Because it would be too easy otherwise, there are different standards. 😅 Coding standards are defined by different sources. There are standards set by WordPress itself, standards set by the PHP Framework Interoperability Group (PHP-FIG), and individual companies and agencies can also define their own standards, of course.

At this point, we are primarily interested in two definitions:

The standards that WordPress itself defines, with the standards for PHP being important in this article.
The PHP Standard Recommendation, or PSR for short, from the aforementioned PHP-FIG.

So which standards should we follow?

The answer you won’t like: it depends.

It depends on your personal taste, and there is no right or wrong here. You can also define your own standards (which I do not recommend). The important thing is to actually stick to one thing.

Which standards will we follow in this series?

I don’t want to dictate which standards you should follow, but I stick to the PSR, as they are also followed by other PHP frameworks like Symfony and Laravel. If you rely on PSR, you are not trapped in the WordPress universe and can seamlessly work on Symfony or Laravel projects as well. Opinions differ here, though; there are numerous advocates of the WordPress standard when programming for WordPress. If you ever want to become a core developer, you should definitely be aware that different coding standards exist.

Please take the time, if you are not familiar with PSR, to review the following PSRs:

PSR-1: Basic Coding Standard
PSR-2: Coding Style Guide
PSR-12: Extended Coding Style

IMPORTANT:

PHP files that contain either pure PHP code or end with a PHP code block must not contain a closing PHP tag (?>) (see PSR-2, 2.2 Files)! This can especially lead to a “Headers already sent” error in plugin development if whitespace or a blank line follows the ?>.

Standard for folder structure

Since we have to follow the namespaces in folder naming for autoloading, I don’t want to define fixed standards for the folder structure. This is ultimately more a matter of taste, especially in WordPress plugin development. Frameworks, however, are much stricter.

For later (and also for PSR-4 autoloading, see below), it is important that all PHP files, except for the main plugin file, are located within a src folder. This becomes especially important when we get to unit tests, as the actual source code is in src and all associated tests are in tests. But also for autoloading, as we will see shortly, this is important.

Our previous example code is now standardized

To establish autoloading well, we now fully align our code with the standards and introduce namespaces. We make the following changes:

Class names are written in StudlyCaps, so Class01 instead of class01
The file names are identical to the class names, so Class01.php instead of class-01.php
All files in src have namespaces, with the base namespace MK\MyPlugin following the Manufacturer\Plugin pattern, and our classes 1 and 2 are in the Main sub-namespace, while the service is in Service.

Folder structure

We now establish the folder structure that follows the naming of the namespaces:

my-plugin
├── src
│   ├── Main
│   │   ├── Class01.php
│   │   └── Class02.php
│   └── Service
│       └── Service01.php
└── my-plugin.php

The files

src/Main/Class01.php

<?php

namespace MK\MyPlugin\Main;

class Class01
{
    public function __construct()
    {
        echo 'Class01 instantiated.';
    }
}

src/Main/Class02.php

<?php

namespace MK\MyPlugin\Main;

use MK\MyPlugin\Service\Service01;

class Class02
{
    protected Service01 $service01;

    public function __construct(Service01 $service01)
    {
        $this->$service01 = $service01;

        echo 'Class02 instantiated.';
    }
}

src/Service/Service01.php

<?php

namespace MK\MyPlugin\Main;

class Service01
{
    public function __construct()
    {
        echo 'Service01 instantiated.';
    }
}

my-plugin.php

<?php
/**
* Plugin Name: MyPlugin
*/

require_once __DIR__ . '/src/Main/Class01.php';
require_once __DIR__ . '/src/Main/Class02.php';
require_once __DIR__ . '/src/Service/Service01.php';

use MK\MyPlugin\Main\Class01;
use MK\MyPlugin\Main\Class02;
use MK\MyPlugin\Main\Service01;

$service01 = new Service01();

$class01 = new Class01();
$class02 = new Class02($service01);

Using autoloading in WordPress plugins

Basically, there are two ways to use autoloading:

Self-configured autoloading via spl_autoload_register()
PSR-4 autoloading via Composer

I generally use autoloading via Composer and highly recommend it. However, to cover the most important things here, I also deal with spl_autoload_register().

Autoloading with spl_autoload_register()

With the PHP function spl_autoload_register(), we can implement our own autoloading. To do this, let’s look at the function call:

spl_autoload_register(?callable $callback = null, bool $throw = true, bool $prepend = false): bool

So, the function expects at least one callback function, and this function is given the name of the class to be loaded:

callback(string $class): void

We can now comment out the require_once() calls in our main file my-plugin.php and insert spl_autoload_register() for testing, using an anonymous function as the callback:

<?php
/**
* Plugin Name: MyPlugin
*/

// require_once __DIR__ . '/src/Main/Class01.php';
// require_once __DIR__ . '/src/Main/Class02.php';
// require_once __DIR__ . '/src/Service/Service01.php';

use MK\MyPlugin\Main\Class01;
use MK\MyPlugin\Main\Class02;
use MK\MyPlugin\Main\Service01;

spl_autoload_register(function(string $className) {
    var_dump($className);
});

$service01 = new Service01();

$class01 = new Class01();
$class02 = new Class02($service01);

By disabling the require_once() calls and integrating spl_autoload_register(), PHP tries to get the appropriate PHP file via the autoloader when calling new Service01(). To do this, PHP passes the fully qualified class name to the callback function that we passed to spl_autoload_register().

All our callback does at the moment is to output the class name using var_dump(). So our above code generates the following message:

string(29) "MK\MyPlugin\Service\Service01"
Fatal error: Uncaught Error: Class "MK\MyPlugin\Service\Service01" not found in 
[(...)/wp-content/plugins]/autoload-plugin-02/autoload-plugin-01.php:18 
Stack trace: #0 (...)/wp-settings.php(453): include_once() #1 (...)/wp-config.php(93): 
require_once '...' #2 (...)/wp-load.php(50): require_once '...' #3 (...)/wp-admin/admin.php(34): 
require_once '...' #4 (...)/wp-admin/plugins.php(10): require_once '...' #5 {main} 
thrown in (...)/wp-content/plugins/autoload-plugin-02/autoload-plugin-01.php on line 18

In this code, I have replaced my local paths with (…) and added manual line breaks to avoid making the message too long.

First, the output of var_dump() appears:

string(29) "MK\MyPlugin\Service\Service01"

This is the fully qualified name of the class that is instantiated first.

Then follows the Fatal Error, as the class could not be found. We now need to ensure in our callback that the appropriate file is loaded.

Since we have made it very easy for ourselves with the namespaces and the corresponding folder structure, we can get the filename with a few simple adjustments to the fully qualified class name:

<?php
/**
* Plugin Name: MyPlugin
*/

// require_once __DIR__ . '/src/Main/Class01.php';
// require_once __DIR__ . '/src/Main/Class02.php';
// require_once __DIR__ . '/src/Service/Service01.php';

use MK\MyPlugin\Main\Class01;
use MK\MyPlugin\Main\Class02;
use MK\MyPlugin\Main\Service01;

spl_autoload_register(function(string $className) {
    // MKMyPlugin vom Klassennamen durch den Pfad zu src ersetzen:
    $className = str_replace('MK\\MyPlugin\\', __DIR__ . '/src/', $className);

    // Die restlichen Backslashes durch Verzeichnis-Trenner (Slashes) ersetzen und .php anhängen
    $classFile =  str_replace('\\', '/', $className) . '.php';

    // Klassen-Datei laden
    require_once $classFile;
});

$service01 = new Service01();

$class01 = new Class01();
$class02 = new Class02($service01);

In the example of the Service01 class, the class name is MK\MyPlugin\Service\Service01. The part MK\MyPlugin can be seen as an alias to the src directory of our plugin.

So, to get the path for the class file from this, in the first step we only need to replace the part MK\MyPlugin with __DIR__ . '/src/. Afterward, we exchange all backslashes (\) for the directory separator (slash, /) and add the extension .php.

So, MK\MyPlugin\Service\Service01 becomes (…)/wp-content/plugins/my-plugin/src/Service/Service01.php, which exactly matches our file. The part (…) corresponds to your local path to the WordPress installation.

With the above code, our plugin should now automatically reload all class files. So now we just need to remove our redundant, commented out code:

<?php
/**
* Plugin Name: MyPlugin
*/

use MK\MyPlugin\Main\Class01;
use MK\MyPlugin\Main\Class02;
use MK\MyPlugin\Main\Service01;

spl_autoload_register(function(string $className) {
    // Replace MK\MyPlugin in the class name with the path to src:
    $className = str_replace('MK\\MyPlugin\\', __DIR__ . '/src/', $className);

    // Replace the remaining backslashes with directory separators (slashes) and append .php
    $classFile =  str_replace('\\', '/', $className) . '.php';

    // Load class file
    require_once $classFile;
});

$service01 = new Service01();

$class01 = new Class01();
$class02 = new Class02($service01);

However, if we now implement this code and reload the page in our WordPress installation, we will be confronted with a new error:

Warning: require_once(WP_Site_Health.php): Failed to open stream: No such file or directory 
in (...)/wp-content/plugins/autoload-plugin-02/autoload-plugin-01.php on line 27

Fatal error: Uncaught Error: Failed opening required 'WP_Site_Health.php' (include_path='.:/usr/share/php:/www/wp-content/pear') 
in (...)/wp-content/plugins/autoload-plugin-02/autoload-plugin-01.php:27 
Stack trace: #0 [internal function]: {closure}('WP_Site_Health') 
#1 (...)/wp-settings.php(604): class_exists('WP_Site_Health') #2 (...)/wp-config.php(93): 
require_once('...') #3 (...)/wp-load.php(50): require_once('...') 
#4 (...)/wp-admin/admin.php(34): require_once('...') #5 (...)/wp-admin/plugins.php(10): 
require_once('...') #6 {main} thrown in (...)/wp-content/plugins/autoload-plugin-02/autoload-plugin-01.php on line 27

What’s happening here?

PHP tries to load the WordPress core class WP_Site_Health, from which our callback code makes the file WP_Site_Health.php, and of course, this cannot be found.

The autoloader callback that we register with spl_autoload_register() is declared in the global namespace. So, we need to ensure that we only process class names that are actually present in our namespace, as PHP uses the callback for every loaded class that is loaded after registration. This includes WordPress core classes.

To ensure that only class names in our namespace are handled in our autoloader, we add the following check:

<?php
/**
* Plugin Name: MyPlugin
*/

use MK\MyPlugin\Main\Class01;
use MK\MyPlugin\Main\Class02;
use MK\MyPlugin\Main\Service01;

spl_autoload_register(function(string $className) {
    if (false === strpos($className, 'MK\\MyPlugin')) {
        return;
    }

    // Replace MK\MyPlugin in the class name with the path to src:
    $className = str_replace('MK\\MyPlugin\\', __DIR__ . '/src/', $className);

    // Replace the remaining backslashes with directory separators 
    $classFile =  str_replace('\\', '/', $className) . '.php';

    // Load class file
    require_once $classFile;
});

$service01 = new Service01();

$class01 = new Class01();
$class02 = new Class02($service01);

With if (false === strpos($className, 'MK\MyPlugin')), we check if the beginning of our namespace is present in the class name. If not (strpos returns false), we terminate the callback with return.

Now we have a working autoloader that only handles the class names of our plugin.

Autoloading with Composer

The manual transformation of the class name in the callback of spl_autoload_register() and the exception handling of class names outside the namespace of the plugin are both cumbersome and prone to errors.

In terms of code reusability, this version of autoloading doesn’t score well, as we always have to manually adjust the namespace in at least two places.

It would be much nicer if we could use an established solution here. That’s where Composer comes in. Composer is a cross-platform dependency management tool for PHP that helps developers easily manage and automatically download required libraries and packages for their projects. At the same time, Composer also offers a PSR-4-based autoloading that we want to use for our plugin from now on.

Setting up Composer

To use Composer in the plugin, we first need to set up Composer. Composer must already be installed on your device; you can follow this tutorial to install it.

Once Composer is installed, please open a terminal (I recommend Warp if you’re on a Mac, or hyper.js otherwise) and switch to your plugin directory.

Then enter the following command: composer init. The Composer config generator will guide you through the setup. In most cases, you can use the default settings.

Since we don’t want to define any dependencies yet, you can answer the questions “Would you like to define your dependencies (require) interactively” and “Would you like to define your dev dependencies (require-dev) interactively” with no.

Then comes the question we need:

Add PSR-4 autoload mapping? Maps namespace "Marcuskober\MyPlugin" to the entered relative path. [src/, n to skip]:

Here, Composer automatically generates a namespace from the initially specified package name, which by default consists of the name you chose when setting up Composer and the directory name. We confirm the selection here with enter to choose the name and the suggested src directory.

The setup must then be confirmed with a yes.

Composer now creates a vendor directory for your plugin and the config file composer.json. The vendor directory already contains the files that Composer needs for autoloading, and packages will be placed in this directory later if you install them via Composer.

My config file now looks like this:

{
    "name": "marcuskober/my-plugin",
    "autoload": {
        "psr-4": {
            "Marcuskober\\MyPlugin\\": "src/"
        }
    },
    "authors": [
        {
            "name": "Marcus Kober",
            "email": "marcus.kober@gmail.com"
        }
    ]
}

In my case, I need to correct the namespace under "psr-4” so that it matches our chosen namespace. Depending on your choice of name, directory, and namespaces, you may also need to do this.

So, we’ll change this (from Marcuskober to MK) accordingly:

"psr-4": {
    "MK\\MyPlugin\\": "src/"
}

After changing the namespace in composer.json, we need to inform Composer to adjust its autoload files accordingly. To do this, we enter the following command in the terminal: composer dump-autoload. If Composer returns Generated autoload files in the terminal, we have correctly set up Composer.

Using composer autoload in our plugin

To use Composer autoloading in our plugin, all we need to do is remove the require_once() calls and load the file vendor/autoload.php:

<?php
/**
* Plugin Name: MyPlugin
*/

use MK\MyPlugin\Main\Class01;
use MK\MyPlugin\Main\Class02;
use MK\MyPlugin\Main\Service01;

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

$service01 = new Service01();

$class01 = new Class01();
$class02 = new Class02($service01);

And simply by adding the line require __DIR__ . '/vendor/autoload.php';, the autoloading with Composer works directly out of the box!

Conclusion and Outlook

As you can see, autoloading with Composer is not rocket science and, unlike spl_autoload_register(), is quickly and easily implemented.

Once your plugins have reached a certain size, I recommend using autoloading with Composer. Even though you can freely adjust the settings, autoloading still forces you to use clean class naming, a logical folder structure, and the use of a single src directory for your PHP files. And believe me, the constraint is purely positive at this point.

In the upcoming articles in this series, we will delve deeper into the development and structuring of complex plugins, and the code will become more tangible as we will see usable code after these rather theoretical first articles!

In the next article, we will focus on hooks and their registration from your plugin.

Namespaces in WordPress plugin development

Marcus Kober — Wed, 03 May 2023 10:34:03 +0000

In this article I'll point out, what's the reason for using namespaces in our WordPress plugins and what namespaces are. We will learn, that namespaces are important for the upcoming topics in this series.

The problem with naming constants, functions, and classes in WordPress plugins

Avoiding name collisions is of paramount importance in plugin development. If you use constants, functions, and classes directly in your plugin file, these are registered in the global namespace. Therefore, there is a risk that you will overwrite constants, functions, or classes from other plugins (or from WordPress itself), or vice versa. As a result, your plugin (or other plugins) may not function correctly, or a PHP error may be thrown.

So, let’s assume that there are two plugins installed on our system, each declaring a function called plugin_init():

Plugin file plugin-01/plugin-01.php:

<?php
/*
 * Plugin Name: Plugin #1
 */

function plugin_init() {
    // some code
}

Plugin file plugin-02/plugin-02.php:

<?php
/*
 * Plugin Name: Plugin #2
 */

function plugin_init() {
    // some code
}

This will lead to the following error: PHP Fatal error: Cannot redeclare plugin_init() (previously declared in /../plugin-01/plugin-01.php). The reason behind this is that PHP does not allow the declaration of two functions with the same name.

Using a prefix to solve this problem

We can now come up with a prefix for our plugin, which we will then use consistently throughout our plugin. A prefix is just a string of characters that we put in front of our function and class names, usually followed by an underscore.

Please keep in mind that the prefix must be as unique as possible. If we only use our plugin name, it is possible that another plugin also has that name, which then leads to naming conflicts again. A short combination of your name and the name of your plugin should generally be safe.

Example:

<?php
/*
 * Plugin Name: Prefixed plugin
 */

function mk_pp_plugin_init() {
    // some code
}

function mk_pp_get_data() {
    // some code
}

// ...

In this example, we have chosen mk_pp as a prefix (a short form of Marcus Kober and an abbreviation for the plugin) and now use this for all our constants and functions. As you can see, this leads to long names and surely doesn’t contribute to clarity and readability. However, such a prefix is relatively safe. But can’t we do it even more elegantly?

What are namespaces?

Namespaces offer the ability to encapsulate elements of your code so as not to cause name collisions. Essentially, namespaces are a mechanism for organizing functions, classes, and constants. A namespace defines a unique area in which the names of functions and classes are encapsulated. This makes it possible to use identical names within different namespaces.

You can also imagine namespaces like a folder system. The “subfolders” are separated with backslashes (/).

For the root namespace, I recommend using your name or that of your company, or an abbreviation thereof. In my case, that would be MK. Then follows the name of your plugin (or an abbreviation thereof): MK\MyPlugin.

We use namespaces

The namespace is defined at the beginning of each PHP file in your plugin. Of course, you should again make sure not to use too generic namespaces like simply Plugin, as this could also lead to a name collision of the namespace.

Example:

<?php
/*
 * Plugin Name: Namespaced plugin
 */

namespace MK\NamespacePlugin;

function plugin_init() {
    // some code
}

function get_data() {
    // some code
}

// ...

The fully qualified name of the function plugin_init() is now: MK\NamespacePlugin\plugin_init(). This resolves the potential name conflict with a possibly existing function plugin_init() in another plugin.

Namespaces in WordPress plugins

Now let’s try to register a function inside a namespace as a callback for a hook:

<?php
/*
 * Plugin Name: Namespaced plugin
 */

namespace MK\NamespacePlugin;

function plugin_init() {
    // some code
}

add_action('init', 'plugin_init');

This will lead to a Fatal error:

Fatal error: Uncaught TypeError: call_user_func_array(): Argument #1 ($callback) must be a valid callback, function "plugin_init" not found or invalid function name

Why does this error message appear? After all, the function plugin_init() does exist in our plugin. To understand, let’s look at the file where the error occurs. In the PHP error description, we see below:

thrown in /.../wp-includes/class-wp-hook.php on line 308

So, the error occurs in the WordPress core file class-wp-hook.php, where the core function apply_filters() is defined, which calls the callback that we defined in add_action(). However, the file class-wp-hook.php is outside of the namespace MK\NamespacePlugin that we defined, which is why we need to give the function add_action() the fully qualified name of the function:

<?php
/*
 * Plugin Name: Namespaced plugin
 */

namespace MK\NamespacePlugin;

function plugin_init() {
    // some code
}

add_action('init', 'MK\NamespacePlugin\plugin_init');

So that we don’t have to manually type in the full name everywhere, we can also provide the call with the magic constant __NAMESPACE__, which contains the name of the current namespace as a string:

add_action('init', __NAMESPACE__ . 'plugin_init');

Conclusion

Using namespaces is a clean and efficient way to encapsulate our constants, functions, and classes from the global namespace and thus prevent name collisions.

In the next article of this series, we will also see that we need namespaces for autoloading and the folder structure of plugins.

You might not be using object-oriented programming

Marcus Kober — Fri, 28 Apr 2023 12:56:36 +0000

What lies behind this somewhat provocative headline? Over time, I have noticed something about certain WordPress plugins. What exactly, I will describe here.

First, I must admit, that I did not only notice that with plugins from other developers, but first and foremost with older plugins by myself. When I was developing my first plugins, I proclaimed with the utmost conviction at some point: "I now use object-oriented programming in my plugins!". Unfortunately, this was not the truth. My code looked something like this:

<?php
/*
 * Plugin Name: Not object oriented
 * Description: I'm not object oriented
 * Author: Marcus Kober
 */

class MK_MyPlugin
{
    public function __construct()
    {
        add_action('init', [$this, 'init']);
        add_action('wp_enqueue_scripts', [$this, 'assets']);
    }

    public function init()
    {
        $results = $this->getResults();
        // Some more code
    }

    public function assets()
    {
        // wp_enqueue...
    }

    private function getResults()
    {
        // Some code
    }

    // More methods
    // ...
}

new MK_MyPlugin();

So what did I do? I have packed all functionality of the plugin inside one large class and then instantiated it directly.

The complete code inside a huge single class does not make it object-oriented programming

If all the code of your plugin resides within a single class, and this class is instantiated at runtime, this is some sort of programming inside a class, but not yet object-oriented programming.

All that is achieved with the code above is merely a better encapsulation of the code so that there is no need for prefixing your functions and variables to avoid name conflicts (more on that in the upcoming article about namespaces). Unfortunately, it's nothing more like that and certainly not object-oriented programming.

So, what type of programming do we have here?

Next to object-oriented programming is procedural programming. In procedural programming the code is organized in steps, to get a clear structure. Code fragments are often organized in functions and every step is represented by a code line. One step is, for example, a variable declaration, a function call, an if-query, and so on.

The code of our little plugin introduced above would look something like that in procedural programming:

<?php
/*
 * Plugin Name: Not object oriented
 * Description: I'm not object oriented
 * Author: Marcus Kober
 */

function mk_myplugin_init() {
    $results = mk_myplugin_getResults();
    // Some more code
}

function mk_myplugin_assets() {
    // wp_enqueue...
}

function mk_myplugin_getResults() {
    // Some code
}

add_action('init', 'mk_myplugin_init');
add_action('wp_enqueue_scripts', 'mk_myplugin_assets');

The only difference to the first code example is that the various functions of the plugin were implemented as methods of a single class. Essentially, the problem is solved in the same procedural way in both versions of the code, only the arrangement of the code is different.

In the world of WordPress, you'll find many such examples of procedural programming. Many plugins and even large parts of the WordPress core are based or were based on procedural programming, and that is absolutely fine. Even though many parts of WordPress are now built as classes, these are obscured in the WordPress API by functions such as get_posts().

In the first article of this series, I already wrote: it is not absolutely necessary to use object-oriented programming and modern PHP for every plugin. However, especially for more extensive plugins, object-oriented programming helps enormously in structuring the code (alongside other advantages that we will get to know).

What does object-oriented programming solve?

Let's assume you are developing a plugin. At first, it's not very complicated. Procedural programming would not be a problem here and should be the way to go.

Over time, however, several things happen:

new functions need to be implemented
bugs need to be fixed
perhaps there are problems with other plugins and a workaround needs to be implemented
new WordPress versions are leading to problems that need to be addressed
and so on

This is where procedural programming quickly reaches its limits. Such issues indicate that something should be done about the general structure of the code:

Where should the new code be integrated?
Does the new code lead to conflicts with existing code?
Should the code be split into multiple files?
How should the new files be named?
How much code and which code should the files contain?
In what order should these files be loaded?

Now let's assume, we solved all those issues with procedural programming. We now have a large codebase, distributed over many files with more or less speaking file names. The code gets more and more complex and tasks such as bug fixing or feature integration become increasingly difficult.

But now a new problem arrives: a client is calling and wants you to develop a new plugin. You recognize that the new plugin needs some parts of your last plugin. The reusability of code that is so deeply entangled in your codebase is certainly not very high. You can indeed copy certain parts of the code, but you probably have to untangle many tight wirings first to really integrate the code into the new plugin.

That costs you time - and therefore either you or the client money!

That's where object-oriented programming enters the stage. In object-oriented programming, as small classes as possible work together to solve a problem in its entirety, while each participating class solves only a narrowly defined sub-problem. This not only increases the readability of the code and leads to a more orderly structure, but also facilitates the reuse of the code. In this way, certain classes can be used in different plugins without having to complicatedly extract them from the existing code.

Done right, object-oriented programming increases the readability, maintainability, reusability, and testability of your code, leading to cleaner code and - hopefully - lesser bugs. 😊

What exactly does a WordPress plugin look like, that is based on object-oriented programming? We will work that out together in this series of articles.

Conclusion

Of course, object-oriented programming brings its own problems, but it is precisely these problems that I want to address in this series and hopefully solve to some extent. By using object-oriented programming, as a developer, you have a wealth of often proven solutions for recurring problems at your disposal, the so-called design patterns. Autoloading relieves you of the agony of choice of when to load which file, and dependency injection takes away the question of which class to instantiate when. All of this we will discuss in this article series.

Modern object-oriented PHP in WordPress plugin development

Marcus Kober — Thu, 27 Apr 2023 13:16:59 +0000

In this article series, I will present methods for building WordPress plugins in a modern and object-oriented way. The focus will be on code quality, reusability, maintainability, and extensibility of plugins and plugin code.

In this first article, I would like to briefly introduce myself and explain why I'm writing this series. I also want to highlight when these approaches and methods are unsuitable and provide additional considerations when considering modern PHP and WordPress plugins.

My Name is Marcus and at the time of publication, I'm 47 years old, living in Cologne with my wife and two kids. I have been professionally developing websites and web apps using PHP since 1999, and since 2005 using WordPress too. During this time, I have worked on large-scale web application projects using Yii2, Symfony, and Laravel. Furthermore, I have developed over 150 custom WordPress themes and more than 50 different plugins during this time. These themes and plugins were mainly commissioned by clients, including some very extensive plugins (with over 100 PHP files) that are installed on many client sites. Since then, I have enjoyed thinking and learning about plugin architecture and software architecture in general, always striving to improve my code.

There are many good tutorials and articles on plugin development available on the internet, but most of them end just where it becomes interesting for developing more complex and larger plugins. Unfortunately, there are very few resources available on code organization, file structure, and advanced PHP programming in WordPress plugins.

That's why I developed the desire to gather all the knowledge I have acquired so far. In one place and as comprehensively as possible.

Modern PHP and WordPress - do they even fit together?

WordPress itself is not really built with object-oriented programming and does not use modern PHP due to backward compatibility. However, this does not mean that new plugins must follow this philosophy. If you are developing plugins for the WordPress Plugin Repository and want to reach the widest possible audience of users, it may be advisable to avoid certain PHP features that were introduced later. It is also essential to explicitly specify the PHP version in the plugin header so that plugin activation is prevented on WordPress installations with incompatible PHP versions. For example: Requires PHP: 8.1.

So yes, if you know what you're doing, you can use modern PHP in your plugins. Especially if you have control over who receives your plugins (for example, in commissioned work) or even manage the hosting for your clients, there is absolutely nothing against it.

Brillant idea, from now on I will use these advanced techniques and object orientation for all my plugins!

No, please don't. Not every plugin needs those things. Especially smaller plugins with a few lines of code and just a few functions are better developed without these advanced methods. It's not necessary to generate more overhead as needed for a project. Plugins that register only two or three hooks, haven't to use autoloading, PHP attributes, and dependency injection (more on this in the following articles).

Why the focus on PHP when WordPress is moving more and more towards JavaScript / React?

Although I am a big fan of Gutenberg and block themes, and developing custom blocks is one of my favorite topics, PHP remains relevant for extensive plugins. Therefore, this article series is also of long-term importance.

I may also write some articles on block development after this series. However, for now, my focus is on how modern PHP techniques can be effectively used in WordPress plugins.

Preview

In this article series, the focus is on efficiently using hooks and implementing them with modern PHP. Through many practical code examples, we will explore topics such as dependency injection, its importance, and implementation in WordPress plugins, as well as methods for unit testing and its implementation in the WordPress context.

I will strive to regularly publish new articles and - as far as my job and family allow - to already have many articles completed before the first article goes online. 😅

Who is this article series for?

You should already have some experience with WordPress development and want to take the next step. You should also have heard of object-oriented programming before.

Source