If you’re someone who’s building solutions with WordPress regardless of if they are themes, plugins, or applications, then odds are you’ve had to deal with saving some type of information to the database.

Granted, anytime you create a post, a page, or anything that stores data, you’re entering information into the database.

But that’s not what I’m talking about.

Instead, I’m talking about times when you’re having to work with the Options API, the Theme Customizer API, or one of the meta APIs (like the Post Meta API). In this case, you’re working with the core application to save and retrieve information from the database.

When doing this – especially in development and possibly in staging – it’s likely that you’re having to write the code, run a test (automated or not), and then take a look at the way the record is stored in the database to make sure it saved as expected.

In my experience, there are a handful of things that can be done to make this process a little bit easier and make your code a little bit cleaner and one of these has to do with writing meaningful WordPress Meta Keys

A General Rule on WordPress Meta Keys

In the following list, I share a few things that I try to do in my projects that help to make the data more cohesive with the application layer code which should, in turn, maintain a level of cohesion with the presentation layer.

That is, the information that’s stored in the database should, more often than not, be clearly related to the class or the function or the application that is responsible for writing the data to the database.

Clear keys are key.

Clear keys are key.

This is the general rule that I try to follow when working on projects that hit all major areas of an application (that is, the database, the code, and the presentation): Prefix data similar to how we prefix class names or functions in the code.

I’ll share an example in a moment, but the advantages in doing this are:

  1. It’s easy to pull back the data using a LIKE query with the wildcard operator.
  2. For database clients that allow you to group information alphabetically, the records will be entered closely together.
  3. This follows the conventions set forth in the code (especially if you’re working in a procedural style).
  4. This helps to drive the data model into the application layer and then into the templates.

Of course there are exceptions, but generally speaking, I’ve found this to save a lot of time when revisiting projects in the future for the sake of upgrades, debugging, or general maintenance.

Litmus by Example

One quick litmus test that you can perform to see if you’re following this particular method is to look at any one of your recent projects – say a plugin – and look at information it’s responsible for saving to the database.

I lost my key

For example, let’s say that you have a WordPress plugin that allows the user to save some notes about the content from the post editor dashboard. This information is only visible in the dashboard and it appears in a meta box below the post editor.

Next, let’s say that the name of this particular plugin is Acme Post Notes because that’s about as clear as it gets. If you’re working in a procedural style, then all of your functions should be prefixed with acme_ as per WordPress standards. If you’re working in an object-oriented fashion, it’s likely that your classes are prefixed with Acme_ or something similar.

Finally, let’s say that the post information that’s being saved to the database is done so using the Post Meta API and that it’s adding data like this (where $notes is the sanitized value from the textarea in which the notes are written.

add_post_meta( $post_id, 'acme_post_notes', $notes ) ;

Assuming that you’re structuring your code in a consistent manner, there’s very little ambiguity in the above code.

  • It prefixes the meta key with the name of the plugin (or with part of the name of the plugin)
  • It makes it easy to execute an SQL query such that you can pull back all of the post notes by running a query for WHERE meta_value LIKE ‘acme_%’ or, in this case, ‘WHERE meta_value = ‘acme_post_notes’`
  • It follows the conventions that are defined in your code regardless of if it’s procedural code or object-oriented code
  • It has close cohesion with the overall utility as the data is clearly related to the core code that’s driving it, and the elements that display the notes on the screen are clearly labeled as such.

Though this is just an example – and a simple one at that – it should demonstrate the point that I’m trying to make: When possible, try to make sure that the data, the code, and the presentation is as cohesive as possible.

Ultimately, it’s much easier to write, read, and maintain over time.

Category:
Notes
Tags:

Join the conversation! 6 Comments

  1. Another great tip Tom, thank you!

  2. I’d suggest you use underscores for your meta key naming rather than hyphens.

    e.g. acme_post_notes instead of acme-post-notes

    Extending as an example if you want to hide the meta key from custom fields list on the post edit screen you prefix the key with an underscore e.g. _acme_post_notes so that is a more consistent key name than _acme-post-notes.

  3. So, hasn’t the time come to start namespacing meta keys? Shouldn’t we be more clear about what a meta field actually holds based on it’s name? We’re doing it with actions and filters, class names and much more, greatly improving consistency and readability — so why shouldn’t we do it with post meta?

    Isn’t “myplugin/average_rating” be a better name for a meta key holding the average rating for a post than “myplugin_average_rating”? In a more complex example: isn’t “woocommerce/price/sale_dates_from” a better meta key than “woocommerce_price_sale_dates_from” (NB WooCommerce actually doesn’t prefix all meta keys, but let’s disregard that here)?

    There’s no big reason not to — the meta API currently supports it. Using a delimiter separating the prefix, the context, possible sub-contexts and the actual attribute greatly improves readability and further prevents conflicts.

    • So, hasn’t the time come to start namespacing meta keys? Shouldn’t we be more clear about what a meta field actually holds based on it’s name? We’re doing it with actions and filters, class names and much more, greatly improving consistency and readability — so why shouldn’t we do it with post meta?

      I think the idea behind this makes a lot of sense, but I want to be clear that that’s not to say that I don’t think prefixes are still a working solution permitting it’s something that’s really specific, but the larger the app and/or the larger the site, the more I think this makes sense.

      bq. Isn’t “myplugin/average_rating” be a better name for a meta key holding the average rating for a post than “myplugin_average_rating”?

      In a sense, maybe. I mean, at this point, the slash though denoting a namespace of sorts is also just a single change in character.

      The only thing that I’ve be careful with in doing this – though the API supports it – is not being overly aggressive with parsing information before it’s written to the database (such as with using stripslashes or a similar function) because then we’re left with mypluginaverage_rate and that’s no fun :).

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.