crm.fsf.org/20131203/files/sites/all/modules-old/redirect/redirect.api.php

   1 <?php
   2
   3 /**
   4  * @file
   5  * Hooks provided by the Redirect module.
   6  */
   7
   8 /**
   9  * @defgroup redirect_api_hooks Redirect API Hooks
  10  * @{
  11  * During redirect operations (create, update, view, delete, etc.), there are
  12  * several sets of hooks that get invoked to allow modules to modify the
  13  * redirect operation:
  14  * - All-module hooks: Generic hooks for "redirect" operations. These are
  15  *   always invoked on all modules.
  16  * - Entity hooks: Generic hooks for "entity" operations. These are always
  17  *   invoked on all modules.
  18  *
  19  * Here is a list of the redirect and entity hooks that are invoked, and other
  20  * steps that take place during redirect operations:
  21  * - Creating a new redirect (calling redirect_save() on a new redirect):
  22  *   - hook_redirect_presave() (all)
  23  *   - Redirect written to the database
  24  *   - hook_redirect_insert() (all)
  25  *   - hook_entity_insert() (all)
  26  * - Updating an existing redirect (calling redirect_save() on an existing redirect):
  27  *   - hook_redirect_presave() (all)
  28  *   - Redirect written to the database
  29  *   - hook_redirect_update() (all)
  30  *   - hook_entity_update() (all)
  31  * - Loading a redirect (calling redirect_load(), redirect_load_multiple(), or
  32  *   entity_load() with $entity_type of 'redirect'):
  33  *   - Redirect information is read from database.
  34  *   - hook_entity_load() (all)
  35  *   - hook_redirect_load() (all)
  36  * - Deleting a redirect (calling redirect_delete() or redirect_delete_multiple()):
  37  *   - Redirect is loaded (see Loading section above)
  38  *   - Redirect information is deleted from database
  39  *   - hook_redirect_delete() (all)
  40  *   - hook_entity_delete() (all)
  41  * - Preparing a redirect for editing (note that if it's
  42  *   an existing redirect, it will already be loaded; see the Loading section
  43  *   above):
  44  *   - hook_redirect_prepare() (all)
  45  * - Validating a redirect during editing form submit (calling
  46  *   redirect_form_validate()):
  47  *   - hook_redirect_validate() (all)
  48  * @}
  49  */
  50
  51 /**
  52  * @addtogroup hooks
  53  * @{
  54  */
  55
  56 /**
  57  * Act on redirects being loaded from the database.
  58  *
  59  * This hook is invoked during redirect loading, which is handled by
  60  * entity_load(), via classes RedirectController and
  61  * DrupalDefaultEntityController. After the redirect information is read from
  62  * the database or the entity cache, hook_entity_load() is invoked on all
  63  * implementing modules, and then hook_redirect_load() is invoked on all
  64  * implementing modules.
  65  *
  66  * This hook should only be used to add information that is not in the redirect
  67  * table, not to replace information that is in that table (which could
  68  * interfere with the entity cache). For performance reasons, information for
  69  * all available redirects should be loaded in a single query where possible.
  70  *
  71  * The $types parameter allows for your module to have an early return (for
  72  * efficiency) if your module only supports certain redirect types.
  73  *
  74  * @param $redirects
  75  *   An array of the redirects being loaded, keyed by rid.
  76  * @param $types
  77  *   An array containing the types of the redirects.
  78  *
  79  * @ingroup redirect_api_hooks
  80  */
  81 function hook_redirect_load(array &$redirects, $types) {
  82
  83 }
  84
  85 /**
  86  * Alter the list of redirects matching a certain source.
  87  *
  88  * @param $redirects
  89  *   An array of redirect objects.
  90  * @param $source
  91  *   The source request path.
  92  * @param $context
  93  *   An array with the following key/value pairs:
  94  *   - language: The language code of the source request.
  95  *   - query: An array of the source request query string.
  96  *
  97  * @see redirect_load_by_source()
  98  * @ingroup redirect_api_hooks
  99  */
 100 function hook_redirect_load_by_source_alter(array &$redirects, $source, array $context) {
 101   foreach ($redirects as $rid => $redirect) {
 102     if ($redirect->source !== $source) {
 103       // If the redirects to do not exactly match $source (e.g. case
 104       // insensitive matches), then remove them from the results.
 105       unset($redirects[$rid]);
 106     }
 107   }
 108 }
 109
 110 /**
 111  * Control access to a redirect.
 112  *
 113  * Modules may implement this hook if they want to have a say in whether or not
 114  * a given user has access to perform a given operation on a redirect.
 115  *
 116  * The administrative account (user ID #1) always passes any access check,
 117  * so this hook is not called in that case. Users with the "administer redirects"
 118  * permission may always update and delete redirects through the administrative
 119  * interface.
 120  *
 121  * Note that not all modules will want to influence access on all
 122  * redirect types. If your module does not want to actively grant or
 123  * block access, return REDIRECT_ACCESS_IGNORE or simply return nothing.
 124  * Blindly returning FALSE will break other redirect access modules.
 125  *
 126  * @param $redirect
 127  *   The redirect object on which the operation is to be performed, or, if it
 128  *   does not yet exist, the type of redirect to be created.
 129  * @param $op
 130  *   The operation to be performed. Possible values:
 131  *   - "create"
 132  *   - "delete"
 133  *   - "update"
 134  * @param $account
 135  *   A user object representing the user for whom the operation is to be
 136  *   performed.
 137  *
 138  * @return
 139  *   REDIRECT_ACCESS_ALLOW if the operation is to be allowed;
 140  *   REDIRECT_ACCESS_DENY if the operation is to be denied;
 141  *   REDIRECT_ACCESSS_IGNORE to not affect this operation at all.
 142  *
 143  * @see redirect_access()
 144  * @ingroup redirect_api_hooks
 145  */
 146 function hook_redirect_access($op, $redirect, $account) {
 147   $type = is_string($redirect) ? $redirect : $redirect->type;
 148
 149   if (in_array($type, array('normal', 'special'))) {
 150     if ($op == 'create' && user_access('create ' . $type . ' redirects', $account)) {
 151       return REDIRECT_ACCESS_ALLOW;
 152     }
 153
 154     if ($op == 'update') {
 155       if (user_access('edit any ' . $type . ' content', $account) || (user_access('edit own ' . $type . ' content', $account) && ($account->uid == $redirect->uid))) {
 156         return REDIRECT_ACCESS_ALLOW;
 157       }
 158     }
 159
 160     if ($op == 'delete') {
 161       if (user_access('delete any ' . $type . ' content', $account) || (user_access('delete own ' . $type . ' content', $account) && ($account->uid == $redirect->uid))) {
 162         return REDIRECT_ACCESS_ALLOW;
 163       }
 164     }
 165   }
 166
 167   // Returning nothing from this function would have the same effect.
 168   return REDIRECT_ACCESS_IGNORE;
 169 }
 170
 171 /**
 172  * Act on a redirect object about to be shown on the add/edit form.
 173  *
 174  * This hook is invoked from redirect_object_prepare().
 175  *
 176  * @param $redirect
 177  *   The redirect that is about to be shown on the add/edit form.
 178  *
 179  * @ingroup redirect_api_hooks
 180  */
 181 function hook_redirect_prepare($redirect) {
 182
 183 }
 184
 185 /**
 186  * Perform redirect validation before a redirect is created or updated.
 187  *
 188  * This hook is invoked from redirect_validate(), after a user has has finished
 189  * editing the redirect and is submitting it. It is invoked at the end of all
 190  * the standard validation steps.
 191  *
 192  * To indicate a validation error, use form_set_error().
 193  *
 194  * Note: Changes made to the $redirect object within your hook implementation
 195  * will have no effect. The preferred method to change a redirect's content is
 196  * to use hook_redirect_presave() instead. If it is really necessary to change
 197  * the redirect at the validate stage, you can use form_set_value().
 198  *
 199  * @param $redirect
 200  *   The redirect being validated.
 201  * @param $form
 202  *   The form being used to edit the redirect.
 203  * @param $form_state
 204  *   The form state array.
 205  *
 206  * @see redirect_validate()
 207  * @ingroup redirect_api_hooks
 208  */
 209 function hook_redirect_validate($redirect, $form, $form_state) {
 210
 211 }
 212
 213 /**
 214  * Act on a redirect being inserted or updated.
 215  *
 216  * This hook is invoked from redirect_save() before the redirect is saved to
 217  * the database.
 218  *
 219  * @param $redirect
 220  *   The redirect that is being inserted or updated.
 221  *
 222  * @see redirect_save()
 223  * @ingroup redirect_api_hooks
 224  */
 225 function hook_redirect_presave($redirect) {
 226
 227 }
 228
 229 /**
 230  * Respond to creation of a new redirect.
 231  *
 232  * This hook is invoked from redirect_save() after the redirect is inserted
 233  * into the redirect table in the database.
 234  *
 235  * @param $redirect
 236  *   The redirect that is being created.
 237  *
 238  * @see redirect_save()
 239  * @ingroup redirect_api_hooks
 240  */
 241 function hook_redirect_insert($redirect) {
 242
 243 }
 244
 245 /**
 246  * Respond to updates to a redirect.
 247  *
 248  * This hook is invoked from redirect_save() after the redirect is updated in
 249  * the redirect table in the database.
 250  *
 251  * @param $redirect
 252  *   The redirect that is being updated.
 253  *
 254  * @see redirect_save()
 255  * @ingroup redirect_api_hooks
 256  */
 257 function hook_redirect_update($redirect) {
 258
 259 }
 260
 261 /**
 262  * Respond to redirect deletion.
 263  *
 264  * This hook is invoked from redirect_delete_multiple() after the redirect has
 265  * been removed from the redirect table in the database.
 266  *
 267  * @param $redirect
 268  *   The redirect that is being deleted.
 269  *
 270  * @see redirect_delete_multiple()
 271  * @ingroup redirect_api_hooks
 272  */
 273 function hook_redirect_delete($redirect) {
 274
 275 }
 276
 277 /**
 278  * Act on a redirect being redirected.
 279  *
 280  * This hook is invoked from redirect_redirect() before the redirect callback
 281  * is invoked.
 282  *
 283  * @param $redirect
 284  *   The redirect that is being used for the redirect.
 285  *
 286  * @see redirect_redirect()
 287  * @see drupal_page_is_cacheable()
 288  * @ingroup redirect_api_hooks
 289  */
 290 function hook_redirect_alter($redirect) {
 291 }
 292
 293 /**
 294  * @} End of "addtogroup hooks".
 295  */