How to start WordPress plugin development with Docker, Part 1: Docker and Admin Panel

Photo by Launchpresso on Unsplash

“Beautiful designs, powerful features, and the freedom to build anything you want. WordPress is both free and priceless at the same time.” ~ Wordpress.org

If you work on the web, you have heard about WordPress. It’s a must! Using WordPress, you can literally build anything.

From a new user point of view, WordPress is a nice CMS: you install a theme, set it up, install the plugins you need, you can even tweak some SEO aspects using a plugin for that.

From a developer point of view, it’s different. WordPress is like a framework. Think about it for a minute, with WordPress you have:

• routing: you can write your custom URLs as you want.
• database interfacing: you have tons of functions with useful features like prepared statements and parameters sanitization.
• templating: you can add your own template, extends a plugin one or even fragment the view and define every sub-view separately.
• media management: it can handle images, audio and video without you have to write code.
• authentication/permissions handling: role management can be tweakable as you wish.
• administration panel: you have a nice dashboard you can extend. You can add menus, pages and settings without rebuilding anything.

It isn’t a framework, but it’s really similar to that. With this perspective, start projecting our plugin!

A throwaway development environment for WordPress 🔧

If you already develop “WordPress stuff”, you should already have a development environment that you’re comfortable with and if you don’t wanna change, you can skip this part and get to the generator, but if you want to have another perspective, here it is. If you use a different strategy thinking it’s simple or more effective, let me know in the comments, it’s always appreciated to get other developers comments!

Docker community maintains a WordPress official image with:

• Apache as a web server
• PHP-FPM as process manager
• WP-CLI as a command-line helper (don’t know WP-CLI? Discover it here)
• MySQL as DBMS
• PHPMyAdmin as Databases Explorer Utility

This is an interesting fact: these images are ready-to-go, you shouldn’t necessarily know how docker works to use it on your local machine, you can just follow the steps, launch the images, develop your WordPress stuff and finally clear everything.

Setting up the environment with docker is really easy:

• The docker official image is available here on Github, you should just clone this git clone https://github.com/nezhar/wordpress-docker-compose.git.
• Get in the cloned folder, and let docker do the rest with docker-compose up -d.

This will trigger docker to get the images from DockerHub and bundle your environment. If you look at the folder content, you should see a .env file:

IP=127.0.0.1
DB_ROOT_PASSWORD=password
DB_NAME=wordpress

This file should help you tweaking those 3 parameters, before building, to change the default images behaviour. Once docker has finished, you should just open localhost and your WordPress is ready for setup!

WordPress installation using Docker

Your WordPress files are in the wp-app folder!

WordPress Plugin Boilerplate generator ✏️

WordPress plugins can be structured as you wish, you can just throw files in there, without a specific structure and if you followed the 2/3 rules wrote in the Codex, your plugin will work. If you already have your structure, nice, go with it, if you want to try a new structure or you’re doing it for the first time, a boilerplate can be a nice starting point.

I tried different boilerplates and my favourite of all is WPPB (WordPress Plugin Boilerplate).

wppb.me: boilerplate generator

To be really innovative, let’s build a Hello World.

wppb.me

After clicking “Build Plugin”, you will get your plugin boilerplate zip in your download folder! After extracting it, you will see a lot of files. They’re organized into 3 convenient folders:

• admin: where administration related-stuff are in.
• public: where public related-stuff are in.
• includes: where the magic happens.

We’ll go with the approach “use first, learn later”, this means that we’ll learn by doing and then we’ll get deeper by examining the exact working flow for this boilerplate.

Install the plugin in your local environment

As we said before, your local WordPress environment is located in the wp-app folder, to develop your plugin faster, copy the plugin folder into the wp-app/wp-content/plugins, and get to http://localhost/wp-admin/plugins.

Installed plugins

The plugin’s ready to be activated, the nice part of it is that you can activate, develop, refresh and get what you just did in real-time. Activate it and start the development process!

Hello world from the Admin panel

To start developing the admin panel you should start from the Admin class in the admin/class-kalizi-hello-world-admin.php. In the partials folder there will be your views for each page. To start registering a page, start making a method in the admin class where the logic for your page will be and include the view there, super easy.

public function adminHello() {
    include 'partials/kalizi-hello-world-admin-display.php';
}

If you open the included page, there will be a lot of comments, you can put your HTML code thereafter the PHP tag opening, like

<h1>Hello world</h1>

But with this, nothing is done, you should tell WordPress about your page via the admin_menu hook. To register a hook, you should take a look at the includes/class-kalizi-hello-world.php, there you will find a method called define_admin_hooks where the administration class gets instantiated and two actions to enqueue scripts. To register menu pages we should add another method to handle the hook in the admin class.

public function register_menu() { }

Then in the define_admin_hooks just bind it to the hook:

$this->loader->add_action( 'admin_menu', $plugin_admin, 'register_menu' );

In the register_menu you can register the administration page using the add_menu_page:

public function register_menu() {
  add_menu_page(
   'Hello Page Title',
   'Hello Menu',
   'manage_options',
   'hello_from_kalizi',
   [ &$this, 'adminHello' ]
  );
 }

Its parameters, in order, are:

• page title.
• menu title.
• capability: this allows you to control who’ll have access to what, manage_options are the permissions for a user that can access Administration Screens (check them here).
• menu slug.
• callable function: this will follow the PHP call_user_func way, to invoke a method you should use the syntax [$className, $methodName].
• icon URL: it’s optional, you can add an icon to your files and get its URL via the plugin_dir_url(__FILE__).’/path/to/image’.
• position: WordPress menus follow indexed orders, to check your menus order you should use print_r($GLOBALS['menu') as in Administration Page documentation.

The registered menu

Once you’ll click it, this will make the call to the adminHello that will include the view.

Hello world

🔥 It’s baptism of fire time, kid 🔥

Database 💾

If you’re building a plugin, unless you’re doing something static, you should need some tables. To set up your tables, take a look at includes/class-kalizi-hello-world-activator.php. In there, there’s a method called activate where you should put the DB init logic.

To perform CREATE statements, you should first tell WordPress, this way:

global $wpdb;
require_once(ABSPATH . 'wp-admin/includes/upgrade.php');

The first row will recall the $wpdb, the WordPress Database Access Abstraction Class.

The second row will require the upgrade.php to use the dbDelta, a function to modify the database with SQL. So, to perform a CREATE statement, you should:

$query = "
 CREATE TABLE IF NOT EXISTS {$wpdb->prefix}hello_from_the_database (
  id BIGINT(20) NOT NULL AUTO_INCREMENT,
  hello_from VARCHAR(20) NOT NULL,
  hello_message LONGTEXT NOT NULL
  PRIMARY KEY(id)
 ) {$wpdb->get_charset_collate()};
";
dbDelta($query);
if (! empty($wpdb->last_error)) {
 // What you gonna do if this fails?
}

If you’re already in WordPress, you should know that all WordPress tables have a prefix, so you have to add it too with $wpdb->prefix and stay with the WP collate.

To perform a query, you have to invoke the $wpdb again, you can get more information in the WordPress Documentation about WPDB.

From administration, it’s all today!

Photo by Stephen Phillips - Hostreviews.co.uk on Unsplash

Once you know the basics for working on the admin part, you can do everything you can imagine, WordPress Documentation has a lot of actions you can use delegating your methods.

If you have any question about this part, want to know more about wp-admin or have a question about plugin development, please leave a comment down below. 💬

Stay tuned for the next articles of this series, we’ll deep into the boilerplate, talk about how to do something on the public part, how to use ajax or your favourite JS framework or libraries, and much more stuff! Let me know if you want me to focus on some aspects of the WP Plugins development and have a nice day! ☕️