From c50a383bde16c35e22c1faf23478d14e44242666 Mon Sep 17 00:00:00 2001
From: sun <sun@unleashedmind.com>
Date: Sun, 24 Feb 2013 23:46:15 +0100
Subject: [PATCH] - #1836516 by sun: Added API documentation, hook_help(), and
 cleaned up code and comments.

---
 masquerade.api.php | 47 +++++++++++++++++++++++++++++
 masquerade.module  | 87 ++++++++++++++++++++++++++++++++++++++----------------
 2 files changed, 109 insertions(+), 25 deletions(-)
 create mode 100644 masquerade.api.php

diff --git a/masquerade.api.php b/masquerade.api.php
new file mode 100644
index 0000000..53850ef
--- /dev/null
+++ b/masquerade.api.php
@@ -0,0 +1,47 @@
+<?php
+
+/**
+ * @file
+ * Hooks provided by the Masquerade module.
+ */
+
+/**
+ * @addtogroup hooks
+ * @{
+ */
+
+/**
+ * Control access to masquerade as a certain target user.
+ *
+ * Modules may implement this hook to control whether a user is allowed to
+ * masquerade as a certain target user account.
+ *
+ * @param stdClass $user
+ *   The currently logged-in user.
+ * @param Drupal\user\Plugin\Core\Entity\User $target_account
+ *   The target user account to check for masquerade access.
+ *
+ * @return bool
+ *   Either a Boolean or NULL:
+ *   - FALSE to explicitly deny access. If a module denies access, no other
+ *     module is able to grant access and access is denied.
+ *   - TRUE to grant access. Access is only granted if at least one module
+ *     grants access and no module denies access.
+ *   - NULL or nothing to not affect the operation. If no module explicitly
+ *     grants access, access is denied.
+ */
+function hook_masquerade_access($user, \Drupal\user\Plugin\Core\Entity\User $target_account) {
+  // Explicitly deny access for uid 1.
+  if ($target_account->id() == 1) {
+    return FALSE;
+  }
+  // Example: If the target username is 'demo', always grant access for everone.
+  if ($target_account->label() == 'demo') {
+    return TRUE;
+  }
+  // In other cases do not alter access.
+}
+
+/**
+ * @} End of "addtogroup hooks".
+ */
diff --git a/masquerade.module b/masquerade.module
index aae1eb1..b1493cf 100644
--- a/masquerade.module
+++ b/masquerade.module
@@ -16,8 +16,34 @@ use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
 function masquerade_help($path, $arg) {
   switch ($path) {
     case 'admin/help#masquerade':
-      // @todo FIXME.
-      return t('<p>The masquerade module adds a link on a user\'s profile page that allows permitted users to masquerade as that user. Upon masquerading, a link to "switch back" to the original user will appear in the menu. While masquerading, the option to masquerade as another user will not appear. All masquerading transactions are logged, and $user->masquerading will be set; this could be displayed via theme.</p><p>In the masquerade settings a list of roles are presented; any checked role is considered an "administrator" and requires the second level "masquerade as admin" permission to masquerade as. User #1 is automatically considered an administrator, regardless of roles.</p>');
+      $output = '';
+      $output .= '<h3>' . t('About') . '</h3>';
+      $output .= '<p>' . t('The Masquerade module allows users to temporarily switch to another user
+account. It records the original user account, so users can easily switch back.') . '</p>';
+      $output .= '<h3>' . t('Uses') . '</h3>';
+      $output .= '<dl>';
+      $output .= '<dt>' . t('Granting masquerade access') . '</dt>';
+      $output .= '<dd>' . t('All users with the !permission are able to switch to any other registered user account. <strong>Caution:</strong> This includes user accounts that may have more administrative privileges than the masquerading user.', array(
+        '!permission' => l(t('Masquerade as another user'), 'admin/people/permissions', array('fragment' => 'module-masquerade')),
+      )) . '</dd>';
+      $output .= '<dt>' . t('Masquerading as another user') . '</dt>';
+      $output .= '<dd>' . t('There are multiple ways to masquerade as another user:');
+      $output .= '<ul>';
+      $output .= '<li>' . t('On the <a href="@admin-people-url">administrative user listing</a>, choose the <em>Masquerade</em> operation of a certain user account.', array(
+        '@admin-people-url' => url('admin/people'),
+      )) . '</li>';
+      $output .= '<li>' . t('Enable the %toolbar module or the contributed !admin_menu module to use Masquerade directly from either toolbar.', array(
+        '%toolbar' => t('Toolbar'),
+        '!admin_menu' => l(t('Administration menu'), 'http://drupal.org/project/admin_menu'),
+      )) . '</li>';
+      $output .= '</ul>';
+      $output .= '</dd>';
+      $output .= '<dt>' . t('Switching back') . '</dt>';
+      $output .= '<dd>' . t('To stop masquerading as another user, click the %unmasquerade link in the user account links menu.', array(
+        '%unmasquerade' => t('Unmasquerade'),
+      )) . '</dd>';
+      $output .= '</dl>';
+      return $output;
   }
 }
 
@@ -74,7 +100,7 @@ function masquerade_menu() {
 /**
  * Implements hook_translated_menu_link_alter().
  *
- * Dynamically add the CSRF protection token to the Masquerade menu items.
+ * Adds a CSRF protection token to masquerade menu links.
  */
 function masquerade_translated_menu_link_alter(&$item, $map) {
   if (isset($item['page_callback'])) {
@@ -88,7 +114,15 @@ function masquerade_translated_menu_link_alter(&$item, $map) {
 }
 
 /**
- * Menu router access callback for Masquerade tab.
+ * Returns whether the current user is allowed to masquerade as a certain target user.
+ *
+ * @param \Drupal\user\Plugin\Core\Entity\User $target_account
+ *   The user account object to masquerade as.
+ *
+ * @return bool
+ *   TRUE if allowed, FALSE otherwise.
+ *
+ * @see hook_masquerade_access()
  */
 function masquerade_user_access(User $target_account) {
   global $user;
@@ -124,10 +158,12 @@ function masquerade_user_access(User $target_account) {
 /**
  * Implements hook_masquerade_access().
  */
-function masquerade_masquerade_access($user, $target_user) {
+function masquerade_masquerade_access($user, User $target_account) {
   // Only return TRUE, since alternative access implementations could not work
   // otherwise.
-  if (user_access('masquerade')) {
+  // By default, access to masquerade as uid 1 is not granted (but also not
+  // denied, so other implementations may grant access).
+  if ($target_account->id() != 1 && user_access('masquerade')) {
     return TRUE;
   }
 }
@@ -165,7 +201,7 @@ function masquerade_user_view(User $account, $display, $view_mode, $langcode) {
 }
 
 /**
- * Masquerade block form.
+ * Form constructor for the Masquerade block form.
  */
 function masquerade_block_form() {
   $form['autocomplete'] = array(
@@ -190,7 +226,7 @@ function masquerade_block_form() {
 }
 
 /**
- * Masquerade block form validation.
+ * Form validation handler for masquerade_block_form().
  */
 function masquerade_block_form_validate($form, &$form_state) {
   $name = $form_state['values']['masquerade_as'];
@@ -209,14 +245,17 @@ function masquerade_block_form_validate($form, &$form_state) {
 }
 
 /**
- * Masquerade block form submission.
+ * Form submission handler for masquerade_block_form().
  */
 function masquerade_block_form_submit($form, &$form_state) {
   masquerade_switch_user($form_state['masquerade_target_account']);
 }
 
 /**
- * Page callback to switch users.
+ * Page callback; Masquerades as a given user.
+ *
+ * @param \Drupal\user\Plugin\Core\Entity\User $target_account
+ *   The user account object to masquerade as.
  */
 function masquerade_switch_user_page(User $target_account) {
   $token = drupal_container()->get('request')->query->get('token');
@@ -261,7 +300,7 @@ function masquerade_switch_user_validate(User $target_account) {
   if ($target_account->uid == $user->uid) {
     return t('You cannot masquerade as yourself. Please choose a different user to masquerade as.');
   }
-  if (variable_get('maintenance_mode', 0) && !user_access('access site in maintenance mode', $target_account)) {
+  if (config('system.maintenance')->get('enabled') && !user_access('access site in maintenance mode', $target_account)) {
     return t('!user is not permitted to %permission. <a href="@maintenance-url">Disable maintenance mode</a> to masquerade as !user.', array(
       '!user' => theme('username', array('account' => $target_account)),
       '%permission' => t('Use the site in maintenance mode'),
@@ -283,9 +322,6 @@ function masquerade_switch_user_validate(User $target_account) {
  *
  * @param \Drupal\user\Plugin\Core\Entity\User $target_account
  *   The user account object to masquerade as.
- *
- * @return bool
- *   TRUE if the user was sucessfully switched, or FALSE if there was an error.
  */
 function masquerade_switch_user(User $target_account) {
   global $user;
@@ -310,22 +346,21 @@ function masquerade_switch_user(User $target_account) {
 
   // Call all login hooks when switching to masquerading user.
   module_invoke_all('user_login', $user);
-
-  return TRUE;
 }
 
 /**
  * Allows a user who is currently masquerading to become a new user.
  */
 function masquerade_switch_back_page() {
+  global $user;
+
   $token = drupal_container()->get('request')->query->get('token');
-  if (isset($token) && drupal_valid_token($token, 'unmasquerade')) {
-    global $user;
+  if (isset($token) && drupal_valid_token($token, 'unmasquerade') && masquerade_user_is_masquerading()) {
     $old_user = $user;
     masquerade_switch_back();
-    drupal_set_message(t('You are no longer masquerading as !old_user and are now logged in as !user.', array(
-      '!user' => theme('username', array('account' => $user)),
-      '!old_user' => theme('username', array('account' => $old_user)),
+
+    drupal_set_message(t('You are no longer masquerading as !user.', array(
+      '!user' => theme('username', array('account' => $old_user)),
     )));
     drupal_goto(drupal_container()->get('request')->server->get('HTTP_REFERER'));
   }
@@ -340,12 +375,14 @@ function masquerade_switch_back_page() {
 function masquerade_switch_back() {
   global $user;
 
-  if (!masquerade_user_is_masquerading()) {
-    return FALSE;
-  }
   $uid = $_SESSION['masquerading'];
 
   $old_user = $user;
+  if (!$new_user = user_load($uid)) {
+    // Ensure the flag is cleared.
+    unset($_SESSION['masquerading']);
+    return FALSE;
+  }
 
   // Call logout hooks when switching from masquerading user.
   module_invoke_all('user_logout', $user);
@@ -354,7 +391,7 @@ function masquerade_switch_back() {
   // Remove the masquerading flag from the user's session.
   unset($_SESSION['masquerading']);
 
-  $user = user_load($uid);
+  $user = $new_user;
 
   // Call all login hooks when switching back to original user.
   module_invoke_all('user_login', $user);
-- 
1.7.11.msysgit.1