trying-to-understand-wordpress-capabilities

Trying To Understand WordPress’s Capabilities

I recently finished a WordPress project that needed a “podcast” custom post type. The post type required restricted use to one user role, however, I noticed that the custom post type was available to all user roles. I then changed the capability_type argument to “podcast”, and the custom post type disappeared completely. 

It dawned on me that for as long as I’ve been developing with WordPress, I didn’t quite fully understand the relationship between custom post type capabilities and user role capabilities. And while Justin Tadlock’s post on Meta Capabilities is required reading, it didn’t quite cover everything to demystify the relationship between custom post type meta capabilities and user roles.

The Typical Scenario

You want to create a custom post type, that only a particular user role can use.

In this example, I am going to create a “Secrets” custom post type and I want only Administrators to have access to it.

…and it shows up in the backend as we expect, when we’re logged in as an administrator…

secret_admin_1

..however, if we log in as anything between a Contributer and editor, our secrets are not safe…

secret_not_safe

…so we read the documentation, and assume that if we change the capability_type argument to:

However we assumed incorrectly, for our secret is no longer visible to anyone, including administrators:

secret_admin_2

The popular solution to this issue, (and it’s not an issue as we will learn later) that you will encounter on stackoverflow or wordpress exchange is to simply change capability_type back to post and apply hacks to remove it from the dashboard menu for other user roles. THAT IS INCORRECT.

Creating and Mapping the Capabilities

Per the  register_post_type codex, we need to set and map the meta capabilities and primitive capabilities of our capability type:

Note that the “map_meta_cap” argument must be set to true. Re-saving the permalinks will trigger the flush_rewrite_rules function. However you will notice that our secrets are still hidden from us.

Since Justin Tadlock has a great write up on mapping meta capabilities to user capabilities, I won’t repeat the tutorial.

If you’re following along, after adding the mapped secret capabilities, you’ll realize that we STILL can’t see our secrets. Justin’s tutorial recommended the “Members Plugin” to finish off the process, and while that’s an awesome plugin that I highly recommend, there’s still too much magic going on behind the scenes for us to thoroughly understand what’s happening.

Applying the Mapped Capabilities to User Roles

Drum role…

NOW if you refresh, you’ll see your secrets, for your eyes only, for if you switch to any user between Contributor and Editor, your secrets are hidden.

The Members plugin handles the addition and removal of capabilities elegantly, and I would recommend using the plugin over adding them via a hook, however, it is important that you understand how to manually add meta capabilities to user roles if you feel that a plugin is overkill for your project.

So What Are Some Of  The Capabilities?

Let’s say you only wanted to share your secrets with other administrators, but you wanted to post them on the home page…

Administrators will see…

secrets_told

Our Secrets

While everyone else sees…

secrets_unseen

Nothing

I hope this tutorial clarified some of the more challenging aspects of custom post types and user roles. Please leave a comment below for any suggestions or corrections.