The state of handling custom metadata in WordPress

metadata-wordpressWordPress has a table for handling metadata of posts. Quite simply, it's a good place to store “stuff” that relates to a post, but doesn't belong in one of the standard parts of the posts table.

Metadata can be nearly anything. And it can be displayed however a theme wants to display it. You can grab it all and list it out together (as was a common use case for WordPress' early blog structures). Or you can control what metadata goes where, very specifically.

Using custom metadata gets us out of the_content()

Today, metadata is used by plugins and themes that are distributed, and very often by developers creating custom things on WordPress.

Here's a sample list of metadata attached to one of my posts:


But it can get much more complicated than that. Take an eCommerce site, for instance. If a product is a custom post type, then the price, shipping details, dimensions, and many more things could all be metadata stored for that product.

Custom meta boxes and custom meta field interfaces allow us to structure these things nicely in the WordPress admin.


Then, on the front end of the website, you have control over how to grab and utilize that data. For example, the metabox shown above enables the use of that data on a page like this:


Metadata UI interfaces are fractured

Much of what I'm saying is old news to you. I get that. You know, use, and love making creative use of post metadata in WordPress. However, what I'm sure you also know, is that the landscape of tools for creating interfaces for entering custom metadata is incredibly fractured.

There are dozens (if not hundreds) of publicly available plugins, drop-in classes, and generators for creating custom metaboxes and interfaces for inputting metadata. Here's a screenshot of an incredible breakdown of various available tools.


This screenshot is from Scott Kingsley Clark's comparison table. If it's overwhelming to you, that's my point.

WordPress' core metadata / custom fields interface is lacking. So tools have come about to make making custom meta boxes, defining fields, and interfacing with custom metadata easier.

Problems arise from non-standard meta handling

Some of the most popular tools to enhance the WordPress meta-data handling experience are Advanced Custom Fields, Pods, Custom Field Suite, and more. There are also many classes that are meant to be dropped into a custom theme or plugin.

What's happened is that these tools have taken different approaches, and over time some of them even change the way they store the data. This means that backward compatibly issues can arise, and if not handled properly, can cause problems for developers and site owners using these tools.

Trust me, I'm not trying to pin these issues on WordPress core. Developers should be careful about the tools they use, and builders of these tools should consider the backward compatibility issues their users may run into.

A real life example happening right now

I've spent some time in the last day or so trying to learn exactly what problems people are having with the upcoming changes to Advanced Custom Fields (ACF). ACF has fast grown into one of the most popular tools for creating custom metaboxes and fields.

Advanced Custom Fields also has paid add-ons so the developer can monetize the work he's put into the plugin.

The problem is, as Chris Lema did a great job of explaining, is that he has not considered backward compatibility properly.

Basically, developers use ACF to build custom interfaces for their clients. Now, ACF is changing the add-on model to be a single Pro plugin, that's not an add-on at all, but a whole new plugin.

While he's at it, it's very confusing what will work and not work between ACF versions 4 and 5, leaving developers confused, and worst of all, many site owners may upgrade to version 5 of the free plugin and see features disappear or their sites break.

This is not good. And folks are unhappy. The developer of ACF should ensure that he's created workarounds for those that upgrade from version 4 to 5, that he doesn't break their sites.

Worst of all, this isn't the first time this has happened for ACF. When going from version 3 to 4, there were backward compatibility issues, and it was a tough upgrade on a lot of developers and site owners. It resulted in a fork of ACF, and Custom Field Suite was born.

There's a saying: “Fool me once, shame on you; fool me twice, shame on me.”

After the last time, I would've put the brakes on my level of trust that ACF would properly consider back compat moving forward. However, whether they should've kept using it or not, a lot of people are worried now about the future integrity of websites they built that depend on ACF.

Backward compatibility is important

Backward compatibility is important in WordPress. As a WordPress developer I talked to this morning noted, we've been training our clients for years that it's safe to update their WordPress sites. And with irresponsible development practices, it puts that trust in jeopardy.

So I encourage two things:

  1. I hope that Elliot from ACF will re-consider the strategy he's using, so that ACF users can have a more seamless upgrade. And I hope he'll document exactly what actions users and developers should take (the existing posts and documentation is very confusing).
  2. Developers need to strongly consider the tools they're using, and determine whether it's worth creating a dependency on a tool like ACF to make life a little easier during development.

It's time for WordPress core to enhance the metadata API

Many times with software, it's tough to know exactly how people will use things. In the case of WordPress' custom fields, I doubt the core team really considered exactly how people would be using custom fields and the post meta table 5 or 8 years from then.

But today, the post meta table is a huge part of WordPress. It's pivotal to storing data from interfaces that allow WordPress to be used as much more than “just a blogging platform.”

And I believe it's high time core supports a common format for creating metadata UI interfaces.

Thankfully this process is already underway.

One of the WordPress core components that's being actively worked on is that for WordPress Options and Meta APIs. The aforementioned Scott Kingsley Clark (also the lead developer of Pods) is heading up the team, and they are utilizing regular meeting times to organize the project.

Most of the people involved in this core component have either created their own metadata framework or utilize metadata extensively in their own work. The massive spreadsheet comparison of existing tools was the first part of the process, to see how people are approaching it now, and analyze what the best route for a core solution would be.

In its current state, the new metadata API would make it easier than it currently is to create new fields and field groups to utilize a variety of core-supported field types. Furthermore, the new API would be extensible so that developers could utilize a core-supported framework to take custom fields even further.

You can check out more on their Github page for more specific information, but something like this is really promising, and could be a game-changer for creating WordPress content if and when it goes into core.

Make it easier for developers, and better for everyone

Creating custom content types was possible before WordPress 3.0. But WordPress 3.0 made it so much easier, and clearer to folks with less development experience.

The metadata API already does a great job at making it easy to grab and use metadata. But creating beautiful custom metaboxes in the admin to enhance the publishing experience in WordPress is still relatively difficult. It's totally possible, but I think it could be easier.

I strongly believe that an enhanced API to make it as easy as making WordPress custom post types would make WordPress a better, more reliable platform, and I think that most developers would be ecstatic to utilize a core API, versus attempting to choose amongst the fragmented metadata API landscape that exists today.