Creating Maintainable WordPress Meta Boxes: Refactoring
Throughout this series, we've focused on building maintainable WordPress meta boxes. By that, I mean that we've been working to create a WordPress plugin that's well-organized, follows WordPress coding standards, and that can be easily adapted and maintained as the project moves forward over time.
Though we've implemented some good practices, there is still room for refactoring. For this series, this is done by design. Whenever you're working on a project for a client or for a larger company, the odds of you having to maintain an existing codebase are rather high. As such, I wanted us to be able to return back to our codebase in order to refine some of the code that we've written.
Note this article will not be written in the format that the others have been written - that is, there won't be a "First we do this, then we do this" approach to development. Instead, we're going to highlight several areas in need of refactoring and then handle them independently of the other changes we're making.
Refactoring
To be clear, the act of refactoring (as defined by Wikipedia) is:
Refactoring improves nonfunctional attributes of the software. Advantages include improved code readability and reduced complexity to improve source code maintainability, and create a more expressive internal architecture or object model to improve extensibility.
In short, it makes the code more readable, less complex, easier to follow, and does so all without changing the behavior of the code from the end-users standpoint.
This can be achieved a number of different ways each of which are unique to the given project. In our case, we're going to look at refactoring our constructors, some of our save methods, some of our helper methods, and more.
Ultimately, the goal is to show some strategies that can be used throughout your future WordPress endeavors. I'll aim to cover as much as possible in this article; however, note that there may be opportunities for additional refactoring that isn't covered.
If that's the case, great! Feel free to make them on your own instance of the codebase. With that said, let's get started.
The Constructor
If you take a look at our constructor:
<?php
public function __construct( $name, $version ) {
$this->name = $name;
$this->version = $version;
$this->meta_box = new Authors_Commentary_Meta_Box();
add_action( 'admin_enqueue_scripts', array( $this, 'enqueue_admin_styles' ) );
add_action( 'admin_enqueue_scripts', array( $this, 'enqueue_admin_scripts' ) );
}
Notice that it's currently doing two things:
Initializing properties such as the name and the version
Registering hooks with WordPress
It's common practice to see hooks set in the context of a constructor in a WordPress plugin, but it's not really a great place to do it.
A constructor should be used to initialize all properties that are relevant to the given class such that when a user instantiates a class, s/he has everything needed to work with the class.
Since they may not want to register hooks at the time that they initialize the class, we need to abstract this into its own initialize_hooks method. Our code should now look like this:
<?php
public function __construct( $name, $version ) {
$this->name = $name;
$this->version = $version;
$this->meta_box = new Authors_Commentary_Meta_Box();
}
public function initialize_hooks() {
add_action( 'admin_enqueue_scripts', array( $this, 'enqueue_admin_styles' ) );
add_action( 'admin_enqueue_scripts', array( $this, 'enqueue_admin_scripts' ) );
}
After that, we need to make sure to update the core code of authors-commentary.php so that it properly instantiates and registers the hooks.
<?php
function run_author_commentary() {
$author_commentary = new Author_Commentary_Admin( 'author-commentary', '1.0.0' );
$author_commentary->initialize_hooks();
}
run_author_commentary();
Here, the main difference is that we've updated the version number that we're passing to the main class and we're also explicitly calling the initialize_hooks function within the context of run_author_commentary.
If you execute your code right now, everything should work exactly as it did prior to this refactoring.
I'd also like to add that you can make a case for having a separate class responsible for coordinating hooks and callbacks such that the responsibility resides in a separate class. Though I'm a fan of that approach, it's outside the scope of this particular article.
Next, let's go ahead and do the same thing to class-authors-commentary-meta-box.php. Rather than creating a new function, we can simply rename the constructor since the constructor doesn't really do anything. This means our code should go from looking like this:
<?php
public function __construct() {
add_action( 'add_meta_boxes', array( $this, 'add_meta_box' ) );
add_action( 'save_post', array( $this, 'save_post' ) );
}
To this:
<?php
public function initialize_hooks() {
add_action( 'add_meta_boxes', array( $this, 'add_meta_box' ) );
add_action( 'save_post', array( $this, 'save_post' ) );
}
And the final change that we need to make is to update the constructor in the main class so that it now reads inside of the initialize_hooks function that we created in the main plugin class.
<?php
public function initialize_hooks() {
$this->meta_box->initialize_hooks();
add_action( 'admin_enqueue_scripts', array( $this, 'enqueue_admin_styles' ) );
add_action( 'admin_enqueue_scripts', array( $this, 'enqueue_admin_scripts' ) );
}
Again, refresh the page and your plugin should still be functioning exactly as it were prior to this refactoring.
Helper Methods
In the Authors_Commentary_Meta_Box class, we have a number of conditionals in the save_post function that are very redundant. When this happens, this usually means that much of the functionality can be abstracted into a helper function and then called from within the function in which they were initially placed.
Let's take a look at the code as it stands right now:
<?php
public function save_post( $post_id ) {
/* If we're not working with a 'post' post type or the user doesn't have permission to save,
* then we exit the function.
*/
if ( ! $this->is_valid_post_type() || ! $this->user_can_save( $post_id, 'authors_commentary_nonce', 'authors_commentary_save' ) ) {
return;
}
// If the 'Drafts' textarea has been populated, then we sanitize the information.
if ( ! empty( $_POST['authors-commentary-drafts'] ) ) {
// We'll remove all white space, HTML tags, and encode the information to be saved
$drafts = trim( $_POST['authors-commentary-drafts'] );
$drafts = esc_textarea( strip_tags( $drafts ) );
update_post_meta( $post_id, 'authors-commentary-drafts', $drafts );
} else {
if ( '' !== get_post_meta( $post_id, 'authors-commentary-drafts', true ) ) {
delete_post_meta( $post_id, 'authors-commentary-drafts' );
}
}
// If the 'Resources' inputs exist, iterate through them and sanitize them
if ( ! empty( $_POST['authors-commentary-resources'] ) ) {
$resources = $_POST['authors-commentary-resources'];
$sanitized_resources = array();
foreach ( $resources as $resource ) {
$resource = esc_url( strip_tags( $resource ) );
if ( ! empty( $resource ) ) {
$sanitized_resources[] = $resource;
}
}
update_post_meta( $post_id, 'authors-commentary-resources', $sanitized_resources );
} else {
if ( '' !== get_post_meta( $post_id, 'authors-commentary-resources', true ) ) {
delete_post_meta( $post_id, 'authors-commentary-resources' );
}
}
// If there are any values saved in the 'Published' input, save them
if ( ! empty( $_POST['authors-commentary-comments'] ) ) {
update_post_meta( $post_id, 'authors-commentary-comments', $_POST['authors-commentary-comments'] );
} else {
if ( '' !== get_post_meta( $post_id, 'authors-commentary-comments', true ) ) {
delete_post_meta( $post_id, 'authors-commentary-comments' );
}
}
}
Aside from the method being far too long to begin with, there are a number of things that we can clean up:
The initial conditional that uses logical not and logical OR operators
The conditionals that check the presence of information in the $_POST array
The sanitization, update, and/or delete functions for the associated meta data
So let's take a look at each of these individually and work on refactoring this function.
1. The Initial Condition
The purpose of the first conditional check is to make sure that the current user has the ability to save data to the given post. Right now, we're literally checking to see if the current post type is a valid post type and if the user has permission to save given the current nonce values being passed by WordPress.
Right now, the code reads:
If this is not a valid post type or the user doesn't have permission to save, then exit this function.
It's not all together terrible, but could definitely be improved. Instead of having an OR, let's consolidate it into a single evaluation such that it reads:
If the user doesn't have permission to save, then exit this function.
Luckily, this is a relatively easy fix. Since the type of post that's being save helps to dictate whether or not the user has permission the save the post, we can move that logic into the user_can_save function.
So let's take the is_valid_post_type function and move it into the user_can_save function:
<?php
private function user_can_save( $post_id, $nonce_action, $nonce_id ) {
$is_autosave = wp_is_post_autosave( $post_id );
$is_revision = wp_is_post_revision( $post_id );
$is_valid_nonce = ( isset( $_POST[ $nonce_action ] ) && wp_verify_nonce( $_POST[ $nonce_action ], $nonce_id ) );
// Return true if the user is able to save; otherwise, false.
return ! ( $is_autosave || $is_revision ) && $this->is_valid_post_type() && $is_valid_nonce;
}
Now all of the logic that's responsible for determining if the user can save the post meta data is encapsulated within a function specifically designed to evaluate exactly that.
We started with this:
<?php
if ( ! $this->is_valid_post_type() || ! $this->user_can_save( $post_id, 'authors_commentary_nonce', 'authors_commentary_save' ) ) {
return;
}
And now we have this:
<?php
if ( ! $this->user_can_save( $post_id, 'authors_commentary_nonce', 'authors_commentary_save' ) ) {
return;
}
Reads much easier, doesn't it?
2. Checking The $_POST Array
Next up, before we begin sanitizing, validating, and saving (or deleting) the meta data, we're checking the $_POST collection to make sure that the data actually exists.
We can write a small helper function that will take care of this evaluation for us. Though we're essentially writing a little bit of code that makes our evaluation more verbose, the conditionals will read a bit clearer than if we'd just left them as-is.
First, introduce the following function (and note that it takes in a parameter):
<?php
/**
* Determines whether or not a value exists in the $_POST collection
* identified by the specified key.
*
* @since 1.0.0
*
* @param string $key The key of the value in the $_POST collection.
* @return bool True if the value exists; otherwise, false.
*/
private function value_exists( $key ) {
return ! empty( $_POST[ $key ] );
}
Next, refactor all of the calls that were initially calling the ! empty( $_POST[ ... ] ) so that they take advantage of this function.
For example, the function calls should look like this:
if ( $this->value_exists( 'authors-commentary-comments' ) ) {
// ...
} else {
// ...
}
2. Deleting Meta Data
Notice that throughout the conditionals that are placed in that function, every evaluating for deleting post meta data if the value does not exist looks the exact same.
For example, we see something like this every time:
<?php
if ( '' !== get_post_meta( $post_id, 'authors-commentary-comments', true ) ) {
delete_post_meta( $post_id, 'authors-commentary-comments' );
}
This is an obvious chance to refactor the code. As such, let's create a new function called delete_post_meta and have it encapsulate all of this information:
<?php
/**
* Deletes the specified meta data associated with the specified post ID
* based on the incoming key.
*
* @since 1.0.0
* @access private
* @param int $post_id The ID of the post containing the meta data
* @param string $meta_key The ID of the meta data value
*/
private function delete_post_meta( $post_id, $meta_key ) {
if ( '' !== get_post_meta( $post_id, $meta_key, true ) ) {
delete_post_meta( $post_id, '$meta_key' );
}
}
Now we can do back and replace all of the else conditional evaluations to make a call to this single function so that it reads something like the following:
<?php
// If the 'Drafts' textarea has been populated, then we sanitize the information.
if ( $this->value_exists( 'authirs-commentary-drafts' ) ) {
// We'll remove all white space, HTML tags, and encode the information to be saved
$drafts = trim( $_POST['authors-commentary-drafts'] );
$drafts = esc_textarea( strip_tags( $drafts ) );
update_post_meta( $post_id, 'authors-commentary-drafts', $drafts );
} else {
$this->delete_post_meta( $post_id, 'authors-commentary-drafts' );
}
At this point, we really only have one other aspect of this part of the code to refactor.
3. Sanitization and Saving
Right now, the way in which the post meta data is saved is done so through a process of evaluating the presence of the data in the $_POST collection, sanitizing it based on the type of information, and then saving it to the post meta data.
Ideally, we'd like to sanitize the data in its own function as well as save the post meta data in its own function. Thus, we need to introduce to new functions.
First, let's work on sanitization. Because we're dealing with textareas and arrays, there are a couple of ways in which we need to handle the sanitization call. Since we're either working with an array or we're not, we can create a function that accepts an optional parameter denoting whether or not we're working with an array.
If we are not working with an array, then we'll treat the incoming data as text; otherwise, we'll treat it as an array:
<?php
/**
* Sanitizes the data in the $_POST collection identified by the specified key
* based on whether or not the data is text or is an array.
*
* @since 1.0.0
* @access private
* @param string $key The key used to retrieve the data from the $_POST collection.
* @param bool $is_array Optional. True if the incoming data is an array.
* @return array|string The sanitized data.
*/
private function sanitize_data( $key, $is_array = false ) {
$sanitized_data = null;
if ( $is_array ) {
$resources = $_POST[ $key ];
$sanitized_data = array();
foreach ( $resources as $resource ) {
$resource = esc_url( strip_tags( $resource ) );
if ( ! empty( $resource ) ) {
$sanitized_data[] = $resource;
}
}
} else {
$sanitized_data = '';
$sanitized_data = trim( $_POST[ $key ] );
$sanitized_data = esc_textarea( strip_tags( $sanitized_data ) );
}
return $sanitized_data;
}
Next, we can update the sanitization calls to use this method. But before we do that, let's also write a small helper that will be responsible for updating the post meta data with the sanitized inputs:
<?php
private function update_post_meta( $post_id, $meta_key, $meta_value ) {
if ( is_array( $_POST[ $meta_key ] ) ) {
$meta_value = array_filter( $_POST[ $meta_key ] );
}
update_post_meta( $post_id, $meta_key, $meta_value );
}
Now we can update all of the conditionals that we were using earlier in the function to read like this:
<?php
public function save_post( $post_id ) {
if ( ! $this->user_can_save( $post_id, 'authors_commentary_nonce', 'authors_commentary_save' ) ) {
return;
}
if ( $this->value_exists( 'authors-commentary-drafts' ) ) {
$this->update_post_meta(
$post_id,
'authors-commentary-drafts',
$this->sanitize_data( 'authors-commentary-drafts' )
);
} else {
$this->delete_post_meta( $post_id, 'authors-commentary-drafts' );
}
if ( $this->value_exists( 'authors-commentary-resources' ) ) {
$this->update_post_meta(
$post_id,
'authors-commentary-resources',
$this->sanitize_data( 'authors-commentary-resources', true )
);
} else {
$this->delete_post_meta( $post_id, 'authors-commentary-resources' );
}
if ( $this->value_exists( 'authors-commentary-comments' ) ) {
$this->update_post_meta(
$post_id,
'authors-commentary-comments',
$_POST['authors-commentary-comments']
);
} else {
$this->delete_post_meta( $post_id, 'authors-commentary-comments' );
}
}
Note that we could actually refactor this particular even more so there aren't as many conditionals, but for the sake of the length of the article, the length of time, and also trying to introduce some other strategies, this will be left up as an exercise to be done on your own time.
Conclusion
By now, we've completed our plugin. We've written a plugin that introduces a meta box for providing options for the authors who are writing blog posts.
Additionally, we've employed the WordPress coding standards, some strong file-organization strategies, and have created a number of helper methods and abstractions that will help us to maintain this particular plugin as it undergoes future development.
Because it's not easy to highlight every single opportunity for refactoring, there are likely additional changes that could be made. On your own time, feel free to try implementing some of them on your own.
Overall, I hope you've enjoyed the series and learned a lot from it, and I hope that it will help you to write better, more maintainable code in future WordPress-based projects.
Comments
Post a Comment