Registering widgets within the Mythic system

A screenshot of the widgets manager class in a code editor.

A developer who is currently building a theme with the Mythic starter asked a great question about how to register widgets within Mythic’s object-oriented setup. This made for a perfect example to explore some of the inner-workings of both Mythic and the underlying Hybrid Core framework.

While there’s nothing forbidding theme authors from doing things the same way they always have, I hope that by the end of this post, you’ll have an appreciation for what I consider a better method of building things for long-term, maintainable code.

Several features from the Mythic + Hybrid Core combination are tough to grasp when talking about them in the abstract. Widget registration and handling provide a great way to look at how these features can actually work.

Let’s just dive head first into how I’d handle widgets in this system.

Setting up the files and folders

In your Mythic-based theme, you need to open the /app folder and create a new /Widgets folder inside of it. Then, create three new files named Example.php, Manager.php, and WidgetsServiceProvider.php. Your folder structure should look like the following (note that these are case-sensitive).

/app
    /Widgets
        /Example.php
        /Manager.php
        /WidgetsServiceProvider.php

We use these exact names because Mythic uses Composer to autoload classes. This is based on the PSR-4 Autoloading Standard that is used practically everywhere else in the PHP world outside of the WordPress community. Because we follow this standard, it means we don’t have to worry about when and where to load our class files. They simply get loaded when they are needed.

Creating a custom widget

Creating widgets is not any different in the Mythic system. Like any other WordPress widget, you need to extend the WP_Widget class. Open your Example.php file and add the following PHP code.

namespace Mythic\Widgets;

use WP_Widget;

class Example extends WP_Widget {

    // Drop your custom widget code here.

}

Of course, I’ll leave it up to you to build out your own widget following the WordPress Widgets API.

Mythic expects you to be working with namespaces out of the box, so the big difference for theme authors unaccustomed to namespaces will be the namespace and use lines.

You should notice that the namespace follows our folder structure. Mythic\Widgets points to app/Widgets.

The use line is to import the core WordPress WP_Widget class that you will be extending. When working with namespaces, you must import classes from outside the current namespace to use them.

Creating a manager class

One thing I like to do is create what I call a “manager” class for certain features. Widgets would be a single feature within my theme that would only ever need to be registered once on each page load. This is where I like to use this type of class.

The Hybrid Core framework, which Mythic is built from, uses an interface called Bootable. This basically says that an implementing class (like our manager class here) has a method named boot(), which is used to “boot” things. I typically use this for registering actions and filters with WordPress.

Open your Manager.php file and add the following code to register your widgets.

namespace Mythic\Widgets;

use Hybrid\Contracts\Bootable;

class Manager implements Bootable {

    public function boot() {

        add_action( 'widgets_init', [ $this, 'registerWidgets' ] );
    }

    public function registerWidgets() {

        register_widget( Example::class );
    }
}

While we’re only using a single widget in this example, you may have multiple widgets to register. Each call to core WP’s register_widget() function would go within the registerWidgets() method. This way, you have a single class for managing which widgets get registered.

Furthermore, this is a pattern that you can reuse for other features. And, programming is all about following predictable patterns.

As a side note to this, you’ll often see developers recommend using a class __construct() method for adding actions/filters. I don’t really consider that appropriate (even though I’ve done it many times in the past). The constructor is meant for setting up the initial state of the object. Actions/Filters don’t really fall in line with that. Some sort of boot() (like we’re using) or other type of initialization method makes far more sense.

Adding a service provider

Hybrid Core provides a method for registering what are called “service providers.” Essentially, a service provider is just a way to bootstrap code with the application. When I have a well-defined feature such as a group of widgets with a manager class, I like to create a service provider to bootstrap this particular feature.

To create a service provider, you merely need to extend the existing ServiceProvider class from Hybrid Core, which has both a register() method (for registering things with the app) and a boot() method (for booting things).

Open the WidgetsServiceProvider.php file and add the following code.

namespace Mythic\Widgets;

use Hybrid\Tools\ServiceProvider;

class WidgetsServiceProvider extends ServiceProvider {

    public function register() {
        $this->app->singleton( Manager::class );
    }

    public function boot() {
        $this->app->resolve( Manager::class )->boot();
    }
}

Note in the register() method, we created a single instance of our Manager class using the singleton() method. We’ll only ever need one instance on a page load, so that’s the best method to use. Then, in the boot() method, we call the boot() method from the Manager class (if you remember, that’s the code that registers our widgets).

Feel free to dive into the Container Wiki if you want to learn more about the various methods available, which are beyond the scope of this tutorial.

Registering the service provider

All that’s left at this point is registering the service provider with the application. To do this, open your /app/bootstrap-app.php file and scroll to the section for adding service providers. Then, add the following code.

$mythic->provider( \Mythic\Widgets\WidgetsServiceProvider::class );

Why all of the steps?

I know what some of your are thinking–this is much more complex than necessary for registering a widget or two.

In the short term, that’s absolutely true. However, in terms of writing long-term, maintainable code that can be easily reused and edited in the future, I consider this a far better method because we’ve created a system that’s organized and separates concerns into their own classes.

  • Example.php – Houses the code for the widget only and nothing more.
  • Manager.php – Houses the code for managing the registration of widgets.
  • WidgetsServiceProvider.php – Houses the code for bootstrapping the widgets feature.

Each thing has its own place and performs its single task.

Another thing to consider for the long term is that you may wish to create a widget library of sorts. By organizing things now, you could easily repackage your widgets into their own repository and load them via Composer into any theme project as needed.

Diving deep into Mythic

One of the reasons for this tutorial is that I wanted to share some of the concepts of building things the Hybrid/Mythic way. Widgets are merely a means to an end in this case.

The important bits are thinking in terms of code separation. Thinking in terms of classes having a single responsibility. Once you start thinking about how these pieces fit together, it can be an enjoyable way to code.

I won’t pretend to have all the answers. I’m always learning and exploring new ideas. Much has been written with many disagreements on how some of these concepts should work in the WordPress community by some folks much smarter than me. However, what we’ve built with Mythic and Hybrid Core 5.0 has helped me write better code already.

1 Comment


  1. ·Reply

    Great post. Do you send newsletters as well ?

Leave a Reply

Your email address will not be published. Required fields are marked *