Civi/API/Events.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2019                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26  */
  27 namespace Civi\API;
  28
  29 /**
  30  * The API kernel dispatches a series of events while processing each API request.
  31  * For a successful API request, the sequence is RESOLVE => AUTHORIZE => PREPARE => RESPOND.
  32  * If an exception arises in any stage, then the sequence is aborted and the EXCEPTION
  33  * event is dispatched.
  34  *
  35  * Event subscribers which are concerned about the order of execution should assign
  36  * a weight to their subscription (such as W_EARLY, W_MIDDLE, or W_LATE).
  37  * W_LATE).
  38  */
  39 class Events {
  40
  41   /**
  42    * Determine whether the API request is allowed for the current user.
  43    * For successful execution, at least one listener must invoke
  44    * $event->authorize().
  45    *
  46    * @see AuthorizeEvent
  47    */
  48   const AUTHORIZE = 'civi.api.authorize';
  49
  50   /**
  51    * Determine which API provider executes the given request. For successful
  52    * execution, at least one listener must invoke
  53    * $event->setProvider($provider).
  54    *
  55    * @see ResolveEvent
  56    */
  57   const RESOLVE = 'civi.api.resolve';
  58
  59   /**
  60    * Apply pre-execution logic
  61    *
  62    * @see PrepareEvent
  63    */
  64   const PREPARE = 'civi.api.prepare';
  65
  66   /**
  67    * Apply post-execution logic
  68    *
  69    * @see RespondEvent
  70    */
  71   const RESPOND = 'civi.api.respond';
  72
  73   /**
  74    * Handle any exceptions.
  75    *
  76    * @see ExceptionEvent
  77    */
  78   const EXCEPTION = 'civi.api.exception';
  79
  80   /**
  81    * Weight - Early
  82    */
  83   const W_EARLY = 100;
  84
  85   /**
  86    * Weight - Middle
  87    */
  88   const W_MIDDLE = 0;
  89
  90   /**
  91    * Weight - Late
  92    */
  93   const W_LATE = -100;
  94
  95   /**
  96    * @return array<string>
  97    */
  98   public static function allEvents() {
  99     return [
 100       self::AUTHORIZE,
 101       self::EXCEPTION,
 102       self::PREPARE,
 103       self::RESOLVE,
 104       self::RESPOND,
 105     ];
 106   }
 107
 108   /**
 109    * @param \Civi\Core\Event\GenericHookEvent $e
 110    * @see \CRM_Utils_Hook::eventDefs
 111    */
 112   public static function hookEventDefs($e) {
 113     $e->inspector->addEventClass(self::AUTHORIZE, 'Civi\API\Event\AuthorizeEvent');
 114     $e->inspector->addEventClass(self::EXCEPTION, 'Civi\API\Event\ExceptionEvent');
 115     $e->inspector->addEventClass(self::PREPARE, 'Civi\API\Event\PrepareEvent');
 116     $e->inspector->addEventClass(self::RESOLVE, 'Civi\API\Event\ResolveEvent');
 117     $e->inspector->addEventClass(self::RESPOND, 'Civi\API\Event\RespondEvent');
 118   }
 119
 120 }