class-gravityview-roles-capabilities.php

Go to the documentation of this file.

<?php
/**
 * Roles and Capabilities
 *
 * @package GravityView
 * @license GPL2+
 * @since 1.14
 * @author Katz Web Services, Inc.
 * @link http://gravityview.co
 * @copyright Copyright 2015, Katz Web Services, Inc.
 */

// Exit if accessed directly
defined( 'ABSPATH' ) || exit;

/**
 * GravityView Roles Class
 *
 * This class handles the role creation and assignment of capabilities for those roles.
 *
 * @since 1.15
 */
class GravityView_Roles_Capabilities {

 /**
 * @var GravityView_Roles_Capabilities|null
 */
 static $instance = null;

 /**
 * @since 1.15
 * @return GravityView_Roles_Capabilities
 */
 public static function get_instance() {

 if( ! self::$instance ) {
 self::$instance = new self;
 }

 return self::$instance;
 }

 /**
 * Get things going
 *
 * @since 1.15
 */
 public function __construct() {
 $this->add_hooks();
 }

 /**
 * @since 1.15
 */
 private function add_hooks() {
 add_filter( 'members_get_capabilities', array( 'GravityView_Roles_Capabilities', 'merge_with_all_caps' ) );
 add_action( 'members_register_cap_groups', array( $this, 'members_register_cap_group' ), 20 );
 add_filter( 'user_has_cap', array( $this, 'filter_user_has_cap' ), 10, 4 );
 add_action( 'admin_init', array( $this, 'add_caps') );
 }


 /**
 * Add support for `gravityview_full_access` capability, and
 *
 * @see map_meta_cap()
 *
 * @since 1.15
 *
 * @param array $allcaps An array of all the user's capabilities.
 * @param array $caps Actual capabilities for meta capability.
 * @param array $args Optional parameters passed to has_cap(), typically object ID.
 * @param WP_User|null $user The user object, in WordPress 3.7.0 or higher
 *
 * @return mixed
 */
 public function filter_user_has_cap( $usercaps = array(), $caps = array(), $args = array(), $user = NULL ) {

 // Empty caps_to_check array
 if( ! $usercaps || ! $caps ) {
 return $usercaps;
 }

 /**
 * Enable all GravityView caps_to_check if `gravityview_full_access` is enabled
 */
 if( ! empty( $usercaps['gravityview_full_access'] ) ) {

 $all_gravityview_caps = self::all_caps();

 foreach( $all_gravityview_caps as $gv_cap ) {
 $usercaps[ $gv_cap ] = true;
 }

 unset( $all_gravityview_caps );
 }

 $usercaps = $this->add_gravity_forms_usercaps_to_gravityview_caps( $usercaps );

 return $usercaps;
 }

 /**
 * If a user has been assigned custom capabilities for Gravity Forms, but they haven't been assigned similar abilities
 * in GravityView yet, we give temporary access to the permissions, until they're set.
 *
 * This is for custom roles that GravityView_Roles_Capabilities::add_caps() doesn't modify. If you have a
 * custom role with the ability to edit any Gravity Forms entries (`gravityforms_edit_entries`), you would
 * expect GravityView to match that capability, until the role has been updated with GravityView caps.
 *
 * @since 1.15
 *
 * @param array $usercaps User's allcaps array
 *
 * @return array
 */
 private function add_gravity_forms_usercaps_to_gravityview_caps( $usercaps ) {

 $gf_to_gv_caps = array(
 'gravityforms_edit_entries' => 'gravityview_edit_others_entries',
 'gravityforms_delete_entries' => 'gravityview_delete_others_entries',
 'gravityforms_view_entry_notes' => 'gravityview_view_entry_notes',
 'gravityforms_edit_entry_notes' => 'gravityview_delete_entry_notes',
 );

 foreach ( $gf_to_gv_caps as $gf_cap => $gv_cap ) {
 if ( isset( $usercaps[ $gf_cap ] ) && ! isset( $usercaps[ $gv_cap ] ) ) {
 $usercaps[ $gv_cap ] = $usercaps[ $gf_cap ];
 }
 }

 return $usercaps;
 }

 /**
 * Add GravityView group to Members 1.x plugin management screen
 * @see members_register_cap_group()
 * @since 1.15
 * @return void
 */
 function members_register_cap_group() {
 if ( function_exists( 'members_register_cap_group' ) ) {

 $args = array(
 'label' => __( 'GravityView', 'gk-gravityview' ),
 'icon' => 'gv-icon-astronaut-head',
 'caps' => self::all_caps(),
 'merge_added' => true,
 'diff_added' => false,
 );

 members_register_cap_group( 'gravityview', $args );
 }
 }

 /**
 * Merge capabilities array with GravityView capabilities
 *
 * @since 1.15 Used to add GravityView caps to the Members plugin
 * @param array $caps Existing capabilities
 * @return array Modified capabilities array
 */
 public static function merge_with_all_caps( $caps ) {

 $return_caps = array_merge( $caps, self::all_caps() );

 return array_unique( $return_caps );
 }

 /**
 * Retrieves the global WP_Roles instance and instantiates it if necessary.
 *
 * @see wp_roles() This method uses the exact same code as wp_roles(), here for backward compatibility
 *
 * @global WP_Roles $wp_roles WP_Roles global instance.
 *
 * @return WP_Roles WP_Roles global instance if not already instantiated.
 */
 private function wp_roles() {
 global $wp_roles;

 if ( ! isset( $wp_roles ) ) {
 $wp_roles = new WP_Roles();
 }

 return $wp_roles;
 }

 /**
 * Add capabilities to their respective roles if they don't already exist
 * This could be simpler, but the goal is speed.
 *
 * @since 1.15
 * @return void
 */
 public function add_caps() {

 $wp_roles = $this->wp_roles();

 if ( is_object( $wp_roles ) ) {

 $_use_db_backup = $wp_roles->use_db;

 /**
 * When $use_db is true, add_cap() performs update_option() every time.
 * We disable updating the database here, then re-enable it below.
 */
 $wp_roles->use_db = false;

 $capabilities = self::all_caps( false, false );

 foreach ( $capabilities as $role_slug => $role_caps ) {
 foreach ( $role_caps as $cap ) {
 $wp_roles->add_cap( $role_slug, $cap );
 }
 }

 /**
 * Update the option, as it does in add_cap when $use_db is true
 *
 * @see WP_Roles::add_cap() Original code
 */
 update_option( $wp_roles->role_key, $wp_roles->roles );

 /**
 * Restore previous $use_db setting
 */
 $wp_roles->use_db = $_use_db_backup;
 }
 }

 /**
 * Get an array of GravityView capabilities
 *
 * @see get_post_type_capabilities()
 *
 * @since 1.15
 *
 * @param string $single_role If set, get the caps_to_check for a specific role. Pass 'all' to get all caps_to_check in a flat array. Default: `all`
 * @param boolean $flat_array True: return all caps in a one-dimensional array. False: a multi-dimensional array with `$single_role` as keys and the caps as the values
 *
 * @return array If $role is set, flat array of caps_to_check. Otherwise, a multi-dimensional array of roles and their caps_to_check with the following keys: 'administrator', 'editor', 'author', 'contributor', 'subscriber'
 */
 public static function all_caps( $single_role = false, $flat_array = true ) {

 // Change settings
 $administrator_caps = array(
 'gravityview_full_access', // Grant access to all caps_to_check
 'gravityview_view_settings',
 'gravityview_edit_settings',
 'gravityview_uninstall', // Ability to trigger the Uninstall @todo
 'gravityview_contact_support', // Whether able to send a message to support via the Support Port

 'edit_others_gravityviews',
 'edit_private_gravityviews',
 'edit_published_gravityviews',
 );

 // Edit, publish, delete own and others' stuff
 $editor_caps = array(
 'read_private_gravityviews',
 'delete_private_gravityviews',
 'delete_others_gravityviews',
 'publish_gravityviews',
 'delete_published_gravityviews',
 'copy_gravityviews', // For duplicate/clone View functionality

 // GF caps_to_check
 'gravityview_edit_others_entries',
 'gravityview_moderate_entries', // Approve or reject entries from the Admin; show/hide approval column in Entries screen
 'gravityview_delete_others_entries',
 'gravityview_add_entry_notes',
 'gravityview_view_entry_notes',
 'gravityview_delete_entry_notes',
 'gravityview_email_entry_notes',
 );

 // Edit, delete own stuff
 $author_caps = array(
 // GF caps_to_check
 'gravityview_edit_entries',
 'gravityview_edit_entry',
 'gravityview_edit_form_entries', // This is similar to `gravityview_edit_entries`, but checks against a Form ID $object_id
 'gravityview_delete_entries',
 'gravityview_delete_entry',
 );

 // Edit and delete drafts but not publish
 $contributor_caps = array(
 'edit_gravityviews',
 'delete_gravityviews',
 'gravityview_getting_started', // Getting Started page access
 'gravityview_support_port', // Display GravityView Support Port
 );

 // Read only
 $subscriber_caps = array(
 'gravityview_view_entries',
 'gravityview_view_others_entries',
 );

 $subscriber = $subscriber_caps;
 $contributor = array_merge( $contributor_caps, $subscriber_caps );
 $author = array_merge( $author_caps, $contributor_caps, $subscriber_caps );
 $editor = array_merge( $editor_caps, $author_caps, $contributor_caps, $subscriber_caps );
 $administrator = array_merge( $administrator_caps, $editor_caps, $author_caps, $contributor_caps, $subscriber_caps );
 $all = $administrator;

 // If role is set, return caps_to_check for just that role.
 if( $single_role ) {
 $caps = isset( ${$single_role} ) ? ${$single_role} : false;
 return $flat_array ? $caps : array( $single_role => $caps );
 }

 // Otherwise, return multi-dimensional array of all caps_to_check
 return $flat_array ? $all : compact( 'administrator', 'editor', 'author', 'contributor', 'subscriber' );
 }

 /**
 * Check whether the current user has a capability
 *
 * @since 1.15
 *
 * @see WP_User::user_has_cap()
 * @see https://codex.wordpress.org/Plugin_API/Filter_Reference/user_has_cap You can filter permissions based on entry/View/form ID using `user_has_cap` filter
 *
 * @see GFCommon::current_user_can_any
 * @uses GFCommon::current_user_can_any
 *
 * @param string|array $caps_to_check Single capability or array of capabilities
 * @param int|null $object_id (optional) Parameter can be used to check for capabilities against a specific object, such as a post or us
 * @param int|null $user_id (optional) Check the capabilities for a user who is not necessarily the currently logged-in user
 *
 * @return bool True: user has at least one passed capability; False: user does not have any defined capabilities
 */
 public static function has_cap( $caps_to_check = '', $object_id = null, $user_id = null ) {

 /**
 * @filter `gravityview/capabilities/allow_logged_out` Shall we allow a cap check for non-logged in users? USE WITH CAUTION!
 *
 * WARNING: This allows anyone to edit and delete entries, add notes, delete notes, etc!
 *
 * If you use this filter, at least check against certain capabilities and $object_ids.
 *
 * There are use-cases, albeit strange ones, where we'd like to check and override capabilities for
 * for a non-logged in user.
 *
 * Examples, you ask? https://github.com/gravityview/GravityView/issues/826
 *
 * @param boolean $allow_logged_out Allow the capability check or bail without even checking. Default: false. Do not allow. Do not pass Go. Do not collect $200.
 * @param string|array $caps_to_check Single capability or array of capabilities to check against
 * @param int|null $object_id (optional) Parameter can be used to check for capabilities against a specific object, such as a post or us.
 * @param int|null $user_id (optional) Check the capabilities for a user who is not necessarily the currently logged-in user.
 */
 $allow_logged_out = apply_filters( 'gravityview/capabilities/allow_logged_out', false, $caps_to_check, $object_id, $user_id );

 if ( true === $allow_logged_out ) {

 $all_caps = self::all_caps('editor');

 if( array_intersect( $all_caps, (array) $caps_to_check ) ) {
 return true;
 }
 }

 /**
 * We bail with a negative response without even checking if:
 *
 * 1. The current user is not logged in and non-logged in users are considered unprivileged (@see `gravityview/capabilities/allow_logged_out` filter).
 * 2. If the caps to check are empty.
 */
 if ( ( ! is_user_logged_in() && ! $allow_logged_out ) || empty( $caps_to_check ) ) {
 return false;
 }

 $has_cap = false;

 // Add full access caps for GV & GF
 $caps_to_check = self::maybe_add_full_access_caps( $caps_to_check );

 foreach ( $caps_to_check as $cap ) {
 if( ! is_null( $object_id ) ) {
 $has_cap = $user_id ? user_can( $user_id, $cap, $object_id ) : current_user_can( $cap, $object_id );
 } else {
 $has_cap = $user_id ? user_can( $user_id, $cap ) : current_user_can( $cap );
 }
 // At the first successful response, stop checking
 if( $has_cap ) {
 break;
 }
 }

 return $has_cap;
 }

 /**
 * Add Gravity Forms and GravityView's "full access" caps when any other caps are checked against.
 *
 * @since 1.15

 * @param array $caps_to_check
 *
 * @return array
 */
 public static function maybe_add_full_access_caps( $caps_to_check = array() ) {

 $caps_to_check = (array)$caps_to_check;

 $all_gravityview_caps = self::all_caps();

 // Are there any $caps_to_check that are from GravityView?
 if( $has_gravityview_caps = array_intersect( $caps_to_check, $all_gravityview_caps ) ) {
 $caps_to_check[] = 'gravityview_full_access';
 }

 $all_gravity_forms_caps = class_exists( 'GFCommon' ) ? GFCommon::all_caps() : array();

 // Are there any $caps_to_check that are from Gravity Forms?
 if( $all_gravity_forms_caps = array_intersect( $caps_to_check, $all_gravity_forms_caps ) ) {
 $caps_to_check[] = 'gform_full_access';
 }

 return array_unique( $caps_to_check );
 }

 /**
 * Remove all GravityView caps_to_check from all roles
 *
 * @since 1.15
 * @return void
 */
 public function remove_caps() {

 $wp_roles = $this->wp_roles();

 if ( is_object( $wp_roles ) ) {

 /** Remove all GravityView caps_to_check from all roles */
 $capabilities = self::all_caps();

 // Loop through each role and remove GV caps_to_check
 foreach( $wp_roles->get_names() as $role_slug => $role_name ) {
 foreach ( $capabilities as $cap ) {
 $wp_roles->remove_cap( $role_slug, $cap );
 }
 }
 }
 }
}

add_action( 'init', array( 'GravityView_Roles_Capabilities', 'get_instance' ), 1 );