Create Custom Post Meta in WordPress

WordPress adds some basic data like title, content, excerpt etc with post type you save. When you need to store additional information with any post type you need to add post meta boxes to achieve this.

What is WordPress Post Meta?

When we want to store some additional information which is not stored in posts table of WordPress database, we use post meta boxes to save additional information in post_meta table. WordPress Post meta is an additional piece of information that is saved in a separate database table. This additional information is not saved in posts table but in posts_meta table containing the id to post to link each post meta to a specific post. If you want to learn how to show this custom post meta in post tables column visit Show Post Meta in WordPress Admin Table Columns.

Functions Used to Add WordPress Post Meta

Adding custom post meta for a post type involves using a few functions WordPress offers. These functions allow developers to add functionality for registering/adding post meta, retrieving post meta and updating post meta when post is created or updated. Function to add meta box in WordPress:

add_meta_box($id, $title, $callback, $screen = null, $context = 'advanced', $priority = 'default', $callback_args = null);

$id: (string) (Required) - ID for meta box id attribute.
$title: (string) (Required) - Title of meta box.
$callback: (callable) (Required) - The function that will actually contain the HTML to render our meta box.
$screen: (string|array) (Optional) - The screen or screens on which meta box will be shown.
$context: (string) (Optional) - Context of screen where the meta box will be displayed. Possible values are "side", "normal" and "advanced". Default value is "advanced".
$priority: (string) (Optional) - Priority of appearance of meta box. Possible values ("default","low", "high"). Default value is "default".
$callback_args: (array) (Optional) - Array of parameters passed as a second parameter to your callback function.

Following WordPress function is used to get post meta value from database table. The function definition is as below:

get_post_meta($id, $key, $single);

$id: (int) (Required) - Unique ID of post.
$key: (string) (Optional) - Key of post meta in post table.
$single: (bool) (Optional) - Whether to return the value as single value.

WordPress offers two separate functions to save post meta and update post meta. However the function used to update post meta can also be used to save a new post meta as it adds the post meta to table if it does not already exist. Function definition of update post meta is as below:

update_post_meta($post_id, $meta_key, $meta_value, $prev_check = '');

$post_id: (int) (Required) - Unique ID of post.
$meta_key: (string) (Required) - Unique meta key for post meta.
$meta_value: (string) (Required) - Value for post meta.
$prev_check: (mixed) (Optional) - If provided only post meta with provided value will be updated.

How to Add WordPress Post Meta

In previous post Create Custom Post Types in WordPress we created a "Property" post type. In this post we are going to add post meta to save additional information like property price and property area with our post. We will use add_meta_boxes action hook of WordPress to add post meta box fields. We will use save_post_{$post->post_type} hook to save our post meta. We will create separate post-meta.php file which we will include in functions.php file. This file post-meta.php will consist of the code to implement post meta box.

Follow these steps to add post meta box in WordPress:

Add an action hook add_meta_boxes with a add_property_metafunction.
Add the function add_meta_box in add_property_meta function with the parameters "id", "title", "callback" and "screen" array.
Render the post meta fields in the callback function.
Use get_post_meta function to fetch saved post meta values.
Add an action hook "save_post_property" with a save_property_meta function. The save_post_property function is called when a post type "property" is saved.
Save the post meta using update_post_meta function in save_property_meta function.
Make sure to use sanitize_meta to sanitize post meta value that is posted.

post-meta.php

<?php
// Add a meta box to our custom post type
add_action('add_meta_boxes', 'add_property_meta');

function add_property_meta(): void
{
    add_meta_box('property_meta_box', 'Property Data', 'render_property_meta', ['property']);
}

// Function to draw our post meta
function render_property_meta($post): void
{
    // Retrieve post metadata if its already saved
    $property_price = get_post_meta($post->ID, 'property_price', true);
    $property_area = get_post_meta($post->ID, 'property_area', true);
    ?>
    <table class="form-table property-form-table">
        <tbody>
        <tr>
            <th scope="row"><label for="property_price"><?php _e('Price', 'text-domain'); ?></label></th>
            <td><input type="text" name="property_price" id="property_price" class="regular-text"
                       value="<?= $property_price; ?>"/></td>
        </tr>
        <tr>
            <th scope="row"><label for="property_area"><?php _e('Area', 'text-domain'); ?></label></th>
            <td><input type="text" name="property_area" id="property_area" class="regular-text"
                       value="<?= $property_area; ?>"/></td>
        </tr>
        </tbody>
    </table>
    <?php
}

add_action('save_post_property', 'save_property_meta');
function save_property_meta($post_id): void
{
    // Prepare array of our post meta to loop through
    $post_meta = ['property_price', 'property_area'];
    foreach ($post_meta as $meta) {
        if (isset($_POST[$meta])) {
            // Save post metadata if it's submitted with post
            update_post_meta($post_id, $meta, sanitize_meta($_POST[$meta]));
        }
    }
}

Now to add post meta boxes to custom post type all we need to do is include this post-meta.php in our functions.php file.

include('post-meta.php');

This is how the post meta box will look like: