#20: map_meta_cap

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:

  1. array $caps An array of primitive capabilities matched to the provided meta $cap
  2. string $cap The name of the meta capability to map to
  3. int $user_id The current user’s id or a specified one
  4. array $args An array of extra arguments for the meta capability. Sometimes empty


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!

2 thoughts on “#20: map_meta_cap

  1. 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.

  2. 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.


Leave a Reply

Your email address will not be published. Required fields are marked *