4elements, web design and consultancy

In the previous article, we discussed working with post metadata in WordPress using the provided APIs. We also covered a variety of tools, the ideas of security, and what would be required in order to set up the environment in which to work with the code that would be provided throughout the tutorial.

If you haven't read that article, then I highly recommend reviewing it not only because it covers how to work with post metadata, but also because it hits on some important topics that are relevant to the remainder of the articles in this series (and it alludes to some that are to come later this year).

Assuming you're all caught up and ready to learn about another one of the metadata APIs, then let's get started with the WordPress User Meta API.

The WordPress User Meta API

Meta-data is handled with key/value pairs. The key is the name of the meta-data element. The value is the information that will appear in the meta-data list on each individual post that the information is associated with.

As we continue to work with the various metadata APIs, you're going to find that this definition holds true no matter which API is being explored.

The nice thing is that once you've gotten a handle on tackling one metadata API, you have a general idea for how each of the related APIs will work. Sure, there may be nuances here and there, but the general functionality will be the same.

Working With the User Metadata API

When looking at the WordPress Post Meta API, we reviewed and used the following functions:

add_post_meta

update_post_meta

get_post_meta

delete_post_meta

Yes, there are idiosyncrasies among them, especially as it relates to how add_post_meta and update_post_meta work and the various ways get_post_meta and delete_post_meta work, and the APIs we're about to examine will work much in the same fashion.

For the remainder of this article, I'm assuming that you have a local web server, access to a database front-end, an IDE, and that you're comfortable working with the file tutsplus-metadata.php.

Note that the user metadata will be stored in the wp_usermeta database table, so we'll be referencing that in any screenshots of the database. Unlike the initial post metadata table, there's actually some data already in the user metadata table.

This is because of some of the data that's stored on the user profile screen:

Nonetheless, the API is going to allow us to write our own information to the table. So with all of that said, let's go ahead and take a look at how to work with the functions provided by WordPress.

Note that through all of the examples given, we are going to be passing 1 for the first parameter to the API functions since the first user is always the site administrator. This is generally guaranteed to be present in any given installation.

Adding User Meta

You can find a reference to the add_user_meta function in the Codex. The definition of the function is about as succinct as possible:

Add metadata to a user's record.

How beneficial is this? That is, if you were to be working on a plugin or a web application that's built on WordPress and you're looking to extend what a person is able to associate with their profile, then this is one way to do it.

It could be something as simple as providing a user's profile on a given social network, or it could be something more advanced where you may be associating the user with data contained in another table, an array of information, or something else.

Regardless, this is how you go about doing that. Here's the thing, though: Remember how writing metadata for a post using the add_post_meta function resulted in multiple rows being able to be written using the same key?

The same thing is possible using add_user_meta. However, the API function accepts an optional fourth parameter on whether or not a the value being inserted should be unique or not.

Non-Unique Values

So first, let's take a look at the code for adding some user metadata, and let's do so by not specifying that it should be unique.

Note that we're using the same strategy as employed earlier in this series:

We hook into the_content.

We check to see if we're on the Hello World post.

If so, we add the user metadata.

We return $content to WordPress.

With this code in place and with the Hello World post loaded in your browser, refresh the page a few times.

Once done, the resulting database table will look like this:

As I said, it's very similar to how the post metadata API performs.

Unique Values

Using your database front-end, delete the rows that were created or feel free to choose a new key (perhaps something like instagram_username). I'm going to be deleting the rows.

Secondly, I'm also going to be creating a second function rather than changing the one above so that I can offer the complete source code at the end of the tutorial, so read the following code closely:

First, provide a unique value for the meta value (or the third argument) in the function call. Refresh the page a few times, and then take a look at the database. It should look something like this:

Notice what's interesting? There are still multiple values, but they are all the same.

Now try changing the meta value argument a couple of times, and then take a look at the database and you should see something like this:

Notice the difference? Exactly—there isn't one. That's because we said there could only be a unique key. So it doesn't necessarily mean that only one record is created. It means that multiple records will be created when the function is called, but it will always use the first value that it stored that's associated with said key.

If you'd like, go ahead and delete the rows that we just created as this provides a great segue into the next function.

Updating User Meta

Update user meta field based on user ID. Use the $prev_value parameter to differentiate between meta fields with the same key and user ID. If the meta field for the user does not exist, it will be added.

When working with this function, it helps to think about this in two scenarios:

when previous metadata has been added using the add_user_meta function and there are multiple records with the same information

when no metadata has been added and we're adding a new record and want it to be unique

In the first case, it helps to provide the $prev_value because you're telling WordPress which value to target and to update.

When We've Added Metadata

For example, assume that our database looks as it did earlier in the tutorial:

And we want to update the records that have the previous value of https://twitter.com/tommcfarlin/. To do that, then we'd update the code that looks like this.

And this results in the following record being entered into the database:

If you refresh the page several times and then check your database table, you'll notice that only a single instance of the value is written versus multiple values that come when using add_user_meta.

Then if we wanted to ever change that value, we'd update the meta value associated with the specified meta key and it would update that single record.

Retrieving User Meta

When it comes to retrieving user metadata, we have the get_user_metafunction. At this point, it should be clear that the expected parameters will be the user ID and the meta key.

But what about the meta value?

Remember when we're retrieving information, we only need the user ID and the meta key since that's the identifying information for a specific value.

But what happens if the developer has multiple records for a single key? More specifically, what if they've used the add_user_meta function as we've done above and have multiple records?

This is where the optional fourth parameter comes into play: a boolean value that we specify if we want to retrieve a single value or an array of values. The default value (the one that's passed if it's not specified) is false so we'll always get back an array unless we specify otherwise.

Retrieving All Records

Let's assume that we're working off the same set of data from earlier in the tutorial. That is, we have multiple entries for a user's Twitter account. Recall that the database looked like this:

In order to get all of this information out of the database and displayed on the screen, we'd use the following code:

And the result of this code will print this out at the top of the Hello World post from which we've been working:

https://twitter.com/tommcfarlin/

Note that if you're using update_user_meta and you don't specify true as the final parameter, you will get a single-index array handed back to you.

array(1) { [0]=> string(32) "https://twitter.com/tommcfarlin/" }

Thus, if you're looking for a string representation of information, always pass true.

Deleting User Meta

The last thing that we need to cover is how to actually delete the data that we've written to the database. If you've followed along with this series thus far, then you're likely developing some sort of intuition as to how this particular function is going to work.

Remove metadata matching criteria from a user. You can match based on the key, or key and value. Removing based on key and value, will keep from removing duplicate metadata with the same key. It also allows removing all metadata matching key, if needed.

Note that this function is designed to work in the case where there are multiple records that exist and you want to delete them all, or when you have a single record that exists and you want to remove it.

Deleting Multiple Records

First, we'll take a look at how to use this function when there are multiple records with the same information. Let's assume, for the purposes of this example, the database looks something like this:

Here, we have multiple records. In order to delete records having the same key, we use a single call to the delete_user_meta function and pass the user ID and the meta key.

And then if you refresh your database, you should see the following (or something similar):

It's nice when an API performs exactly as you expect.

The Complete Source Code

Here's a copy of all of the source code that we covered in this article. Please note that the add_action calls have been commented out as you'll need to uncomment them based on what you want to do when experimenting with the code.

Additionally, feel free to add this to the file that we created in the previous tutorial. That's what I did when working on the examples; however, you may want to be careful when working on the file so that the proper add_action calls are set based on what it is you'd like to do.

Conclusion

As mentioned earlier in the article, you can review each of the functions in the WordPress Codex, which should always be a click away for a WordPress developer.

In the final article in this series, we're going to take a look at how to deal with comment metadata. Given what we've learned so far, it should be something that's relatively easy to pick up.

Of course, that still leaves us with metadata related to taxonomies. Because of the nature of taxonomies, terms, and the APIs, we'll be reviewing those in follow-up series.

For now, continue to experiment with the code that's been provided in this article. Remember that it's meant for demonstration purposes only and should not be run in a production environment.

Throughout this series, we're trying to lay a foundation for future WordPress developers to build from when they go forward and work on solutions for their employer, their clients, or for their own projects.

With that said, I'm looking forward to continuing this series. Remember if you're just getting started, you can check out my series on how to get started with WordPress, which focuses on topics specifically for WordPress beginners.

In the meantime, if you're looking for other utilities to help you build out your growing set of tools for WordPress or for code to study and become more well-versed in WordPress, don't forget to see what we have available in Envato Market.

Finally, you can see all of my courses and tutorials on my profile page, and you can read more articles about WordPress and WordPress development on my blog. Feel free to follow me on Twitter as well at @tommcfarlin where I talk about various software development practices and how we can employ them in WordPress.

Please don't hesitate to leave any questions or comments in the feed below, and I'll aim to respond to each of them.