Today we're going to go over user permissions within the scope of your plugin. Specifically, I'll discuss what you should be using to determine who can see the various admin menus of your plugin.

A Solution To A Messy Problem

I stumbled across the complexity of user permissions when working on a multi-site installation of WordPress. We were hosting around 15-20 websites and had approximately 30 plugins installed. Blogs each had users of various levels and responsibilities. My employers would get requests or find plugins with functionality they wanted to offer and it would be up to me to install and configure them. That's when I ran into issues. Often, I found myself modifying plugins to simply accommodate the user roles we were using. The mess was mostly due in part to the different ways WordPress allows you to define who can view and use your plugin.

Once upon a time, WordPress incorporated "User Levels." There were 10 levels, each granting more privileges to the user than the last. So quite often, the developer would target a specific user level like so:

<?php
        if (current_user_can('level_10')){
        /*do something*/
        }

	//Or Define a Page
	add_menu_page('Page Title', 'Menu Title', 10,'unique-slug','menu_function');

?>

For those of you not familiar with WordPress functions, the add_menu_page function is defined as:

add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $position );

This particular set of code is targeting user level 10, which would be the highest permission set. While useful in some circumstances, user levels didn't give as much flexibility as I liked. Fortunately, when WordPress 2.0 was released, we were given "Roles and Capabilities." Capabilities replaced user levels and in WordPress 3.0, user levels have become depreciated.

With the new way of defining user permissions, we have gained additional ways of targeting users. The first is by the roles itself. Using the same functions as above, I'll illustrate targeting a user by role.

<?php
        if (current_user_can('Administrator')){
        /*do something*/
        }

	//Or Define a Page
	add_menu_page('Page Title', 'Menu Title', 'Administrator','unique-slug','menu_function');

?>

In essence, this isn't too different from using User Levels, and in my situation, that wasn't a good thing. With our multi-site setup, the Administrator roles were only used by people in house. The highest role any of the clients were allowed were editors. But they still needed to be able to do certain things within their site. And unfortunately, many plugins I ran across still used either user levels or the roles themselves to grant or deny use of their plugin. However, WordPress has provided a much more robust solution to this problem in the way of their capabilities.

Capabilities allow you to target a user based on what they are able to do rather than the role they hold. Consider the example below.

<?php
        if (current_user_can('upload_files')){
        /*do something*/
        }

	//Or Define a Page
	add_menu_page('Page Title', 'Menu Title', 'upload_files','unique-slug','menu_function');

?>

The functions now test whether or not a user can upload_files. If the capabilities have not been altered, this allows the menu to be visible and code to run for Super Administrators, Administrators, Editors and Authors. This is a much better solution, as individual capabilities can be added to or removed from roles in the theme functions.

Now while this is the best solution for many circumstances, I like to take it one step further. When I'm developing a plugin for non-administrative functions, such as a gallery or testimonial plugin, I prefer to grant user access based on a custom capability created for the plugin. I've given an example of how to do this below.

<?php
	//add_cap($role,$cap,$grant);
      add_cap("editor", "my_plugin_cap", true);

	add_menu_page('Page Title', 'Menu Title', 'my_plugin_cap','unique-slug','menu_function');

?>

As you can see, we're adding a capability called "my_plugin_cap" to the editor role. Then we add a menu page that is visible to all users with this capability. What's nice is that in the plugin, you can add the capability to the proper users, and if the administrator wants to give other roles access, he can do so by adding the capability himself through the theme functions. In my case, that means that I no longer need to edit the plugins themselves and I can feel free to update them without worrying about losing the changes I made.

I hope this tip was useful to you. Let me know if you have any questions or concerns in the comments below. Happy plugin programming!