Custom Post Types Guide for Implementing Custom Capabilities in WordPress

WordPress is an open-source (CMS) that powers millions of websites. Out of the box, it allows you to create and manage posts and pages. However, as your website grows, you might need to manage different types of content beyond these basic options. It is where custom post types (CPTs) come in.

A custom post type is essentially a way to group content. For instance, if you’re running a book review site, you might create a Books post type, and for a movie review website, a Movie post type. The flexibility of custom post types helps you manage content more efficiently.

But, creating custom post types is only part of the equation. WordPress role and capability system allows you to define what users can do with these post types. For example, you might want to allow certain users to edit books but not publish them. To accomplish this, you’ll need to implement custom capabilities.

In this guide, we’ll explain how to integrate custom capabilities into custom post types. We’ll go through the technical steps, provide code examples, and explain each step in simple language so you can easily understand.

By the end of this guide, you’ll have a solid understanding of custom post types, custom capabilities, and how to manage user permissions on your WordPress website.

1. Registering a Custom Post Type (CPT) with Custom Capabilities

The first step in adding custom capabilities is creating a custom post type. It is done using the register_post_type() function in WordPress. By default, this function creates a standard post type with basic capabilities. But to add custom capabilities, we need to make some adjustments.

Code Example 1: Registering a Custom Post Type for Books

Here’s how to create a custom post type called Books, with custom capabilities for editing, publishing, and deleting books:

function create_book_post_type() {

    register_post_type('book', array(

        'labels' => array(

            'name' => 'Books',

            'singular_name' => 'Book',

            'add_new' => 'Add New Book',

            'edit_item' => 'Edit Book',

            'new_item' => 'New Book',

            'view_item' => 'View Book',

            'search_items' => 'Search Books',

            'not_found' => 'No books found',

            'not_found_in_trash' => 'No books found in Trash',

            'all_items' => 'All Books',

        ),

        'public' => true,

        'has_archive' => true,

        'show_in_rest' => true, // Enable Gutenberg support

        'capability_type' => 'book', // Custom capabilities

        'map_meta_cap' => true, // Map meta capabilities

    ));

}

add_action('init', 'create_book_post_type');

Explanation:

• capability_type: This tells WordPress to create custom capabilities for the Book post type. By setting this to ‘book’, WordPress will automatically generate capabilities like edit_book, publish_books, and delete_book.
• map_meta_cap: Setting this to true ensures that WordPress maps the custom capabilities to the default capabilities, such as edit_posts. This process allows WordPress to map high-level actions to low-level capabilities, such as edit_posts, delete_posts, etc.

Custom capabilities are helpful because they allow you to control who can perform certain activities on the custom content you create.

2. Understanding WordPress Role and Capability System

WordPress has a built-in system for managing editing, publishing, and deleting user roles and their capabilities. The default roles are Administrator, Editor, Author, Contributor, and Subscriber. Each role comes with a set of predefined capabilities, such as the ability to edit, publish, and delete posts.

However, WordPress allows you to customize these roles and capabilities to suit your needs. For instance, if you have a custom post type for books, you may want certain users (like editors) to be able to edit books, but only administrators to publish books.

This is where custom capabilities come into play. By integrating custom capabilities into your roles, you can control who can perform which actions on your custom post types.

3. Assigning Custom Capabilities to WordPress Roles

Now that we’ve registered a custom post type with custom capabilities, we need to assign those capabilities to user roles. The add_cap() function can help us do this.

For example, let’s say you want to allow Editors to edit and publish books, but only Administrators can delete books.

Code Example 2: Assigning Custom Capabilities to User Roles

function assign_book_caps_to_editor() {

    // Get the Editor role

    $editor_role = get_role('editor');

    // Assign capabilities to the Editor role

    $editor_role->add_cap('edit_book');

    $editor_role->add_cap('publish_books');

    // Get the Administrator role

    $admin_role = get_role('administrator');

    // Assign delete capability to Admin role

    $admin_role->add_cap('delete_book');

}

add_action('admin_init', 'assign_book_caps_to_editor');

Explanation:

• get_role(): This function retrieves a role object (e.g., editor, administrator) that you want to assign capabilities to.
• add_cap(): This function adds a specific capability (e.g., edit_book, publish_books) to the role. Here, we add the capability to edit and publish books to the Editor role and the capability to delete books to the Administrator role.

4. Checking User Capabilities on the Frontend

Now that you’ve assigned custom capabilities to roles, you might want to check if a user has a specific capability before displaying content on the front end.

For example, if a user can edit books, you can show them an Edit Book button.

Code Example 3: Displaying Content Based on User Capabilities

if (current_user_can('edit_book')) {

    echo '<button>Edit Book</button>';

} else {

    echo '<p>You don't have permission to edit this book.</p>';

}

Explanation:

• current_user_can(): This function checks if the current user has the specified capability. In this case, we check if the user can edit books and display a button accordingly.

5. Removing Capabilities from User Roles

Sometimes, you may need to remove certain capabilities from a user role. For instance, you may want to revoke the ability to delete books from an Administrator role.

Code Example 4: Removing a Capability from a Role

function remove_delete_book_capability() {

    $admin_role = get_role('administrator');

    $admin_role->remove_cap('delete_book');

}

add_action('admin_init', 'remove_delete_book_capability');

Explanation:

• remove_cap(): This function removes a specific capability from a role. In this case, we’re removing the delete_book capability from the Administrator role.

6. Advanced Tips for Managing Custom Capabilities

• Using Custom Capabilities in Plugins: If you’re building a plugin that interacts with custom post types, you can easily integrate custom capabilities by defining them when registering your post types.
• Role-based Content Restriction: You can restrict access to certain content based on user roles and capabilities. This allows you to create member-only sections of your site or restrict editing permissions for certain users.

7. Troubleshooting Common Issues

As you implement custom capabilities, you might encounter some common issues:

• Permissions Not Updating: If you don’t see the custom capabilities reflected in the user interface, try signing out and logging back in or clearing your browser cache.
• Capabilities Not Working: When registering your custom post type, ensure that map_meta_cap is set to true. It will ensure that WordPress properly maps the capabilities.

Questions & Answers

if (current_user_can('edit_book')) {

    echo 'You have permission to edit this book.';

}

$role = get_role('editor');

$role->remove_cap('publish_books');

Conclusion

With custom capabilities and WordPress built-in role system, you have a powerful way to control access to your custom post types. By following this guide, you’ve learned how to register a custom post type, define custom capabilities, assign those capabilities to user roles, and check capabilities on the front end.

This functionality is essential for sites that need precise control over who can do what with their content. Whether you manage a simple blog or a complex multi-user site, custom capabilities will help you fine-tune the permissions for each user role.

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.