The map_meta_cap filter allows you to modify which primitive capabilities are mapped to which meta capabilities. That is to say, allow a specific user or users to have or not have a capability in a specific context.
It is evaluated in map_meta_cap() in the wp-includes/capabilities.php file.
map_meta_cap accepts 4 arguments:
- array
$capsAn array of primitive capabilities matched to the provided meta$cap - string
$capThe name of the meta capability to map to - int
$user_idThe current user’s id or a specified one - array
$argsAn array of extra arguments for the meta capability. Sometimes empty
Example:
Let’s say you only want to allow super admins to upload files in your Multisite installation (for some reason). The following returns do_not_allow for any non-super admin on the upload_files cap.
View the code example on Gist.
Have a suggested improvement? You can fork the Gist and comment back with the link. If all is agreeable, I’ll merge in your changes. Crowd-sourced documentation FTW!
It’s important to note that a user must have ALL of the primitive capabilities returned in the $caps array to pass the capability check.
Nice job summarizing this filter. It’s a weird one. I added ‘contextual’ to the doc block for $args.
To me, the biggest thing about map_meta_cap is that it’s contextual. It runs for (nearly?) every permissions check. $args *might* give you added details into the context for which it’s running. However, figuring out what gets passed through $args is via var_dump() or xdebug inspection.
https://gist.github.com/tddewey/6090765