Implementing and Handling Custom Post Statuses in WordPress

In the world of WordPress, managing content effectively is important for any website owner or developer. While WordPress provides standard post statuses like “draft,” “pending,” and “publish,” there are times when you may need to create custom post statuses to better fit your content management workflow. This guide will walk you through the process of implementing and handling custom post statuses in WordPress, providing clear explanations, code examples, and best practices for both beginners and experts.

What are Custom Post Statuses?

Custom post statuses are additional states that you can assign to your posts beyond the default options provided by WordPress. For instance, you might want to create statuses like “in review,” “needs editing,” or “archived.” These custom statuses can help streamline your content, making it simple to manage and track the progress of your posts.

Why Use Custom Post Statuses?

1. Enhanced Workflow: Custom post statuses allow you to categorize content more effectively, enabling better organization and tracking.
2. Improved User Experience: By providing specific statuses, you can make it clearer to users what stage a post is in, reducing confusion.
3. Flexibility: Custom statuses can be tailored to fit your website needs.

Guide to Implementing Custom Post Statuses

Step 1: Registering Custom Post Statuses

To create a custom post status, you will use the register_post_status() function. This function define the properties of your new status, such as its label, visibility, and whether it should appear in the admin status list.

Example: Registering a Custom Post Status

Here’s how to register a custom post status called “In Review”:

function my_custom_post_status() {

    register_post_status('in_review', array(

        'label'                     => _x('In Review', 'post status'),

        'public'                    => true,

        'exclude_from_search'       => false,

        'show_in_admin_status_list'  => true,

        'show_in_admin_all_list'     => true,

        'show_in_rest'              => true,

        'label_count'               => _n_noop('In Review <span class="count">(%s)</span>', 'In Review <span class="count">(%s)</span>'),

    ));

}

add_action('init', 'my_custom_post_status');

Explanation of the Code

• Function Definition: We define a function called my_custom_post_status() to encapsulate our custom post-status registration.
• register_post_status(): This function takes two parameters: the status name (‘in_review’) and an array of arguments that define the status properties.
  • label: The label for the status, which will be displayed in the admin interface.
  • public: Whether the status is public or not. Setting this to true allows it to be visible in the admin area.
  • exclude_from_search: If set to true, posts with this status will not appear in search results.
  • show_in_admin_status_list: If set to true, the status will be shown in the admin status list.
  • show_in_rest: If set to true, the status will be available in the REST API.
  • label_count: This defines how the count of posts with this status will be displayed.

Step 2: Updating Post Status

Once you have registered your custom post status, you can update a post’s status using the wp_update_post() function. This function allows you to change the status of a post programmatically.

Example: Updating a Post Status

$post_id = 123; // Replace with your post ID

$updated_post = array(

    'ID'          => $post_id,

    'post_status' => 'in_review', // Set the custom status

);

wp_update_post($updated_post);

Explanation of the Code

• Post ID: Replace 123 with the actual ID of the post you want to update.
• Array Definition: We create an array called $updated_post that contains the post ID and the new status.
• wp_update_post(): This function updates the post in the database with the new status.

Step 3: Adding Custom Post Status to the Admin Edit Screen

To make your custom post status available in the WordPress admin interface, you need to add it to the dropdown list of post statuses in the post edit screen.

Example: Adding Custom Status to the Admin Edit Screen

function my_custom_post_status_dropdown($post) {

    if ($post->post_type == 'post') {

        $post_statuses = array(

            'in_review' => 'In Review',

        );


        foreach ($post_status es as $status => $label) {

            echo '<script type="text/javascript">

                jQuery(document).ready(function($) {

                    $("select#post_status").append("<option value=\"' . esc_attr($status) . '\">' . esc_html($label) . '</option>");

                });

            </script>';

        }

    }

}

add_action('admin_footer', 'my_custom_post_status_dropdown');

Explanation of the Code

• Function Definition: The function my_custom_post_status_dropdown() checks if the post type is ‘post’.
• Post Statuses Array: An array of custom statuses is defined, with the status slug as the key and the label as the value.
• JavaScript Injection: The script appends the custom status option to the existing post status dropdown in the admin area.

Handling Permissions and Security

User Roles and Capabilities

When implementing custom post statuses, it’s essential to manage who can change them. The add_cap() function can assign capabilities to specific user roles.

Example: Adding Capabilities

function my_custom_post_status_capabilities() {

    $role = get_role('editor');

    $role->add_cap('edit_in_review_posts');

}

add_action('admin_init', 'my_custom_post_status_capabilities');

Explanation of the Code

• Role Retrieval: The get_role() function retrieves the ‘editor’ role.
• Adding Capability: The add_cap() method adds a new capability to the role, allowing editors to edit posts with the ‘in_review’ status.

Advanced Techniques

Custom Status Transitions with Hooks

You can use hooks to trigger actions when a post transitions to a custom status. This process can be useful for sending notifications or logging changes.

Example: Using Hooks for Status Transitions

function my_custom_status_transition($new_status, $old_status, $post) {

    if ($new_status === 'in_review') {

        // Perform actions when a post is marked as 'in_review'

    }

}

add_action('transition_post_status', 'my_custom_status_transition', 10, 3);

Explanation of the Code

• Function Definition: The function my_custom_status_transition() checks if the new status is ‘in_review’.
• Action Hook: The add_action() function hooks into the transition_post_status action, allowing you to execute code when a post status changes.

FAQs

Conclusion

Implementing custom post statuses in WordPress can significantly enhance your content management workflow. By following the steps outlined in this guide, you can create, manage, and utilize custom post statuses effectively. Whether you are a beginner or an experienced developer, these techniques will help you tailor your WordPress experience to better suit your needs.

About the writer

Hassan Tahir wrote this article, drawing on his experience to clarify WordPress concepts and enhance developer understanding. Through his work, he aims to help both beginners and professionals refine their skills and tackle WordPress projects with greater confidence.