WordPress Post Meta Functions Explained

Today we look into how to use the WordPress post meta functions. We investigate the most common functions, their attributes, parameters, and usage examples. Our goal is to build a reference for these functions thus you can use it when you are implementing them.

We follow the same structure for all functions, which is going to be:

• A description
• The functions’ parameters (and types)
• Return values
• Remarks
• Examples

In addition, we are going to cover these functions:

• Add_post_meta
• Get_post_meta
• Delete_post_meta
• Update_post_meta

Let’s get started!

The add_post_meta()

This function follows the same pattern as other add_ functions in WordPress. It will add values, and it won’t update previous values. It can be useful when you want to make sure only new information comes in. This is its basic syntax:

add_post_meta(
  (int) $post_id,
  (string) $meta_key,
  (mixed) $meta_value,
  (bool) $unique = false
)

Return values

The function returns the meta ID on success, false if there’s an error. Errors usually happen when an invalid post ID is used, or when the post won’t allow this add operation (if this is a unique meta ID, and there’s another one already, for example).

The unique operator

The $unique Boolean operator works the same way it does in similar add_ functions. If you set this to true (it is false by default) only one value is allowed for a specific custom field. This does not mean that a post can have just one custom field, just that a specific custom field can’t have multiple values.

Thus, this is usually allowed:

$metaID1 = add_post_meta( 50, 'location', 'New York' ); // $metaID1 is 50
$metaID2 = add_post_meta( 50, 'location', 'Chicago' ); // $metaID2 is 51

This is all fair game. WordPress will simply assign two values for the location, and when you try to get this value you have two items. This, on the other hand, won’t work:

$metaID1 = add_post_meta( 50, 'location', 'New York', true ); // $metaID1 is 50
$metaID2 = add_post_meta( 50, 'location', 'Chicago', true ); // $metaID2 false

That’s because now you told WordPress not to allow multiple values for that custom field. Then when you try to push new values to an existing item it won’t work. This is a good safe lock in case you want to prevent overwriting.

The get_post_meta()

Now you saved your custom fields, what if you want to manipulate them? Well, that’s a get_ operation.

But this operation is quite powerful. You can use it to load specific values or the entire set of meta fields for a post. That’s because this function has some interesting parameters, let’s see its syntax now:

get_post_meta(
  (int) $post_id,
  (string) $key = '',
  (bool) $single = false
)

Return values

This function has just 3 parameters, yet it has multiple possibilities.

• If the $single parameter set to true, it returns the first meta field value found. If no value exists, it returns an empty string
• Should the $single parameter set to false, then it returns an array of the existing values even if it’s a single value (or an empty array for no values)
• If the $meta_key is set, this function returns only the values (single or array, depending on the $single variable) with that specific key
• If the $meta_key is empty, then it returns an array of all of the existing meta fields for the specified post

Single or array values

The add_post_meta function allows multiple values for a single meta key. Therefore, it makes sense to have a method to retrieve them. That’s what the $single parameter does. In our first example, the location could be New York and Chicago.

Well, if you do a similar get_post_meta call you get exactly that:

$meta = get_post_meta( 50, 'location' ); //$meta is array("New York", "Chicago")

But the trick now is that if you want just one value (for direct display, for example) you need to use the $single parameter. This is how it looks like:

$meta = get_post_meta( 50, 'location', true ); //$meta is (string) "New York"

Therefore, don’t forget to use the $single parameter if you want just one value.

In addition to the single meta field retrieval, you can use this function to get all fields. When using this function this way you get them all, even if you set the $single parameter. Here’s an example:

$meta = get_post_meta( 50 ); //$meta is an array with all custom fields and each of their values
$meta2 = get_post_meta( 50, null, true ); //$meta2 is the same as $meta

In terms of error handling, this function is quite simple. Null values will return an empty array if you didn’t set the single parameter:
$result = Array()
Or an empty string, if you have the single attribute as true:
$result = “”;

The delete_post_meta()

We created our custom field, we read it. Now it’s time to delete it.

This function has just 3 parameters, and they have different outcomes as well. Here is the basic syntax:

delete_post_meta(
  (int) $post_id,
  (string) $meta_key,
  (mixed) $meta_value = ''
)

Return Values

This one is quite simple. If the operation was successful you get a true and if something is wrong the return is false.

Usage

Delete operations are a bit trickier, then we need to be careful on how we implement them. The last thing we want is to delete data we shouldn’t.

Thus, there are two levels for our delete operations:

1. Individual meta values
2. The entire set of meta values for a key

These usages are set by the $meta_value variable. If we set anything there just a single value will be deleted. If we don’t use it, all values for a key will be deleted.

Here is an example:

delete_post_meta( 50, 'location', 'New York' ); // Only new york will be deleted
delete_post_meta( 50, 'location' ); // All locations will be deleted

The update_post_meta()

Sometimes instead of deleting our metadata, we want to overwrite it. That’s what this function does. In addition, this function can be used to add new custom post data, in case it doesn’t exists.

Now on to the basic syntax:

update_post_meta(
  (int) $post_id,
  (string) $meta_key,
  (mixed) $meta_value,
  (mixed) $prev_value = ''
)

Return Values

In case there’s a failure, this function returns false. If it is a successful update, then it returns true. If a new meta field is created, then the return is the field ID.

Back to our example, if we wanted to replace New York with Florida, then we can use something like this:

$meta = update_post_meta( 50, 'location', 'Florida', "New York" ); //$meta is true

In a sense, update operations as critical as delete operations. That’s because we need to be careful not to remove data we want to keep. For example, if we run this code:

update_post_meta( 50, 'location', 'Florida' ); //$meta is true
$meta = get_post_meta( 50, 'location' ); //$meta is array("Florida", "Florida")

Here, we run the update code. Since we have two meta values both get replaced with the value we set it to be.

Conclusion

Today we looked into how the WordPress post meta functions work. We saw some examples and some particularities of each of them. In addition, we looked at the critical points for each function.

We hope you enjoyed, and see you again next time!