WordPress.org

Make WordPress Core

Opened 5 years ago

Closed 5 years ago

#32694 closed defect (bug) (fixed)

current_user_can function is able to take post_id as argument, but it is not documented in WordPress documentation.

Reported by: jliman Owned by: DrewAPicture
Milestone: 4.4 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch
Focuses: docs Cc:

Description

The function current_user_can is documented with one parameter, but if we look at the code, it actually support post_id as the argument.

Attachments (3)

capabilities.diff (625 bytes) - added by jliman 5 years ago.
Added optional parameter information.
32694.diff (1.5 KB) - added by DrewAPicture 5 years ago.
+ map_meta_cap
32694.2.diff (4.0 KB) - added by DrewAPicture 5 years ago.

Download all attachments as: .zip

Change History (10)

#1 @dd32
5 years ago

In other areas we've documented it as such (WP_User::has_cap() is what current_user_can() wraps)

The second optional parameter can also be used to check for capabilities against a specific object, such as a post or user.

https://developer.wordpress.org/reference/classes/wp_user/has_cap/

#2 @DrewAPicture
5 years ago

  • Focuses docs added
  • Keywords needs-patch added
  • Version 4.2.1 deleted

Yeah, we're pretty bad about documenting functions that leverage func_get_args() for variable numbers of arguments.

I distinctly remember being frustrated by the lack of documentation on add_query_arg(), for instance, so I added some parameter docs there. We should probably do an audit and actually try to document any of these "variable-argument" functions in core.

#3 @DrewAPicture
5 years ago

  • Milestone changed from Awaiting Review to 4.4

I would like to get this done in 4.4, along with better docs for add_query_arg() and others.

@jliman, are you interested in trying your hand at submitting a patch?

@jliman
5 years ago

Added optional parameter information.

#4 @wonderboymusic
5 years ago

  • Owner set to DrewAPicture
  • Status changed from new to reviewing

#5 @wonderboymusic
5 years ago

  • Keywords has-patch added; needs-patch removed

@DrewAPicture
5 years ago

+ map_meta_cap

#6 @DrewAPicture
5 years ago

  • Status changed from reviewing to accepted

@DrewAPicture
5 years ago

#7 @DrewAPicture
5 years ago

  • Resolution set to fixed
  • Status changed from accepted to closed

In 34224:

Docs: Add documentation for $object_id, the optional second parameter in current_user_can() and WP_User::has_cap(), and the optional third parameter in map_meta_cap().

This change introduces the vernacular of "meta" vs "primitive" capabilities to core docs, and providing examples for each inline and attempts to make it clear that $object_id is really only useful if the passed $capability is of the meta cap variety.

Props jliman for the initial patch.
Fixes #32694.

Note: See TracTickets for help on using tickets.