Changeset 59198 for trunk/src/wp-includes/capabilities.php

Timestamp:

10/08/2024 10:30:57 PM (16 months ago)

Author:

johnbillion

Message:

Role/Capability: Introduce the current_user_can_for_site() and user_can_for_site() functions.

The current_user_can_for_site() function is a replacement for current_user_can_for_blog() which is now deprecated. user_can_for_site() is a renaming of the user_can_for_blog() function which was introduced in [59123]. The intention of this change is to prevent the introduction of a new function which uses the old "blog" naming structure.

Props swissspidy, spacedmonkey, flixos90, johnjamesjacoby

Fixes #45197

File:

• trunk/src/wp-includes/capabilities.php (modified) (3 diffs)

trunk/src/wp-includes/capabilities.php

@@ -914 +914 @@
  * map to primitive capabilities that a user or role has, such as `edit_posts` and `edit_others_posts`.
  *
+ * This function replaces the current_user_can_for_blog() function.
+ *
  * Example usage:
  *
- *     current_user_can_for_blog( $blog_id, 'edit_posts' );
- *     current_user_can_for_blog( $blog_id, 'edit_post', $post->ID );
- *     current_user_can_for_blog( $blog_id, 'edit_post_meta', $post->ID, $meta_key );
- *
- * @since 3.0.0
- * @since 5.3.0 Formalized the existing and already documented `...$args` parameter
- *              by adding it to the function signature.
- * @since 5.8.0 Wraps current_user_can() after switching to blog.
- *
- * @param int    $blog_id    Site ID.
+ *     current_user_can_for_site( $site_id, 'edit_posts' );
+ *     current_user_can_for_site( $site_id, 'edit_post', $post->ID );
+ *     current_user_can_for_site( $site_id, 'edit_post_meta', $post->ID, $meta_key );
+ *
+ * @since 6.7.0
+ *
+ * @param int    $site_id    Site ID.
  * @param string $capability Capability name.
  * @param mixed  ...$args    Optional further parameters, typically starting with an object ID.
  * @return bool Whether the user has the given capability.
  */
-function current_user_can_for_blog( $blog_id, $capability, ...$args ) {
-    $switched = is_multisite() ? switch_to_blog( $blog_id ) : false;
+function current_user_can_for_site( $site_id, $capability, ...$args ) {
+    $switched = is_multisite() ? switch_to_blog( $site_id ) : false;
 
     $can = current_user_can( $capability, ...$args );
@@ -1024 +1023 @@
  * Example usage:
  *
- *     user_can_for_blog( $user->ID, $blog_id, 'edit_posts' );
- *     user_can_for_blog( $user->ID, $blog_id, 'edit_post', $post->ID );
- *     user_can_for_blog( $user->ID, $blog_id, 'edit_post_meta', $post->ID, $meta_key );
+ *     user_can_for_site( $user->ID, $site_id, 'edit_posts' );
+ *     user_can_for_site( $user->ID, $site_id, 'edit_post', $post->ID );
+ *     user_can_for_site( $user->ID, $site_id, 'edit_post_meta', $post->ID, $meta_key );
  *
  * @since 6.7.0
  *
  * @param int|WP_User $user       User ID or object.
- * @param int         $blog_id    Site ID.
+ * @param int         $site_id    Site ID.
  * @param string      $capability Capability name.
  * @param mixed       ...$args    Optional further parameters, typically starting with an object ID.
  * @return bool Whether the user has the given capability.
  */
-function user_can_for_blog( $user, $blog_id, $capability, ...$args ) {
+function user_can_for_site( $user, $site_id, $capability, ...$args ) {
     if ( ! is_object( $user ) ) {
         $user = get_userdata( $user );
@@ -1048 +1047 @@
 
     // Check if the blog ID is valid.
-    if ( ! is_numeric( $blog_id ) || $blog_id <= 0 ) {
+    if ( ! is_numeric( $site_id ) || $site_id <= 0 ) {
         return false;
     }
 
-    $switched = is_multisite() ? switch_to_blog( $blog_id ) : false;
+    $switched = is_multisite() ? switch_to_blog( $site_id ) : false;
 
     $can = user_can( $user->ID, $capability, ...$args );