Civi/API/Events.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11 namespace Civi\API;
  12
  13 /**
  14  * The API kernel dispatches a series of events while processing each API request.
  15  * For a successful API request, the sequence is RESOLVE => AUTHORIZE => PREPARE => RESPOND.
  16  * If an exception arises in any stage, then the sequence is aborted and the EXCEPTION
  17  * event is dispatched.
  18  *
  19  * Event subscribers which are concerned about the order of execution should assign
  20  * a priority to their subscription (such as W_EARLY, W_MIDDLE, or W_LATE).
  21  */
  22 class Events {
  23
  24   /**
  25    * Determine whether the API request is allowed for the current user.
  26    * For successful execution, at least one listener must invoke
  27    * $event->authorize().
  28    *
  29    * @see AuthorizeEvent
  30    */
  31   const AUTHORIZE = 'civi.api.authorize';
  32
  33   /**
  34    * Determine which API provider executes the given request. For successful
  35    * execution, at least one listener must invoke
  36    * $event->setProvider($provider).
  37    *
  38    * @see ResolveEvent
  39    */
  40   const RESOLVE = 'civi.api.resolve';
  41
  42   /**
  43    * Apply pre-execution logic
  44    *
  45    * @see PrepareEvent
  46    */
  47   const PREPARE = 'civi.api.prepare';
  48
  49   /**
  50    * Apply post-execution logic
  51    *
  52    * @see RespondEvent
  53    */
  54   const RESPOND = 'civi.api.respond';
  55
  56   /**
  57    * Handle any exceptions.
  58    *
  59    * @see ExceptionEvent
  60    */
  61   const EXCEPTION = 'civi.api.exception';
  62
  63   /**
  64    * Priority - Higher numbers execute earlier
  65    */
  66   const W_EARLY = 100;
  67
  68   /**
  69    * Priority - Middle
  70    */
  71   const W_MIDDLE = 0;
  72
  73   /**
  74    * Priority - Lower numbers execute later
  75    */
  76   const W_LATE = -100;
  77
  78   /**
  79    * @return array<string>
  80    */
  81   public static function allEvents() {
  82     return [
  83       self::AUTHORIZE,
  84       self::EXCEPTION,
  85       self::PREPARE,
  86       self::RESOLVE,
  87       self::RESPOND,
  88     ];
  89   }
  90
  91   /**
  92    * @param \Civi\Core\Event\GenericHookEvent $e
  93    * @see \CRM_Utils_Hook::eventDefs
  94    */
  95   public static function hookEventDefs($e) {
  96     $e->inspector->addEventClass(self::AUTHORIZE, 'Civi\API\Event\AuthorizeEvent');
  97     $e->inspector->addEventClass(self::EXCEPTION, 'Civi\API\Event\ExceptionEvent');
  98     $e->inspector->addEventClass(self::PREPARE, 'Civi\API\Event\PrepareEvent');
  99     $e->inspector->addEventClass(self::RESOLVE, 'Civi\API\Event\ResolveEvent');
 100     $e->inspector->addEventClass(self::RESPOND, 'Civi\API\Event\RespondEvent');
 101   }
 102
 103 }