CRM/Utils/Hook/WordPress.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
  12 /**
  13  *
  14  * @package CRM
  15  * @copyright CiviCRM LLC https://civicrm.org/licensing
  16  */
  17 class CRM_Utils_Hook_WordPress extends CRM_Utils_Hook {
  18
  19   /**
  20    * @var bool
  21    */
  22   private $isBuilt = FALSE;
  23
  24   /**
  25    * @var string[]
  26    */
  27   private $allModules = NULL;
  28
  29   /**
  30    * @var string[]
  31    */
  32   private $civiModules = NULL;
  33
  34   /**
  35    * @var string[]
  36    */
  37   private $wordpressModules = NULL;
  38
  39   /**
  40    * @var string[]
  41    */
  42   private $hooksThatReturn = [
  43     'civicrm_upgrade',
  44     'civicrm_caseSummary',
  45     'civicrm_dashboard',
  46   ];
  47
  48   /**
  49    * Invoke hooks.
  50    *
  51    * @param int $numParams
  52    *   Number of parameters to pass to the hook.
  53    * @param mixed $arg1
  54    *   Parameter to be passed to the hook.
  55    * @param mixed $arg2
  56    *   Parameter to be passed to the hook.
  57    * @param mixed $arg3
  58    *   Parameter to be passed to the hook.
  59    * @param mixed $arg4
  60    *   Parameter to be passed to the hook.
  61    * @param mixed $arg5
  62    *   Parameter to be passed to the hook.
  63    * @param mixed $arg6
  64    *   Parameter to be passed to the hook.
  65    * @param string $fnSuffix
  66    *   Function suffix, this is effectively the hook name.
  67    *
  68    * @return mixed
  69    */
  70   public function invokeViaUF(
  71     $numParams,
  72     &$arg1, &$arg2, &$arg3, &$arg4, &$arg5, &$arg6,
  73     $fnSuffix
  74   ) {
  75
  76     // do_action_ref_array is the default way of calling WordPress hooks
  77     // because for the most part no return value is wanted. However, this is
  78     // only generally true, so using do_action_ref_array() is only called for those
  79     // hooks which do not require a return value. We exclude the following, which
  80     // are incompatible with the WordPress Plugin API:
  81     //
  82     // civicrm_upgrade
  83     // http://wiki.civicrm.org/confluence/display/CRMDOC43/hook_civicrm_upgrade
  84     //
  85     // civicrm_caseSummary
  86     // http://wiki.civicrm.org/confluence/display/CRMDOC43/hook_civicrm_caseSummary
  87     //
  88     // civicrm_dashboard
  89     // http://wiki.civicrm.org/confluence/display/CRMDOC43/hook_civicrm_dashboard
  90
  91     // distinguish between types of hook
  92     if (!in_array($fnSuffix, $this->hooksThatReturn)) {
  93
  94       // only pass the arguments that have values
  95       $args = array_slice(
  96         array(&$arg1, &$arg2, &$arg3, &$arg4, &$arg5, &$arg6),
  97         0,
  98         $numParams
  99       );
 100
 101       // Use WordPress Plugins API to modify $args
 102       //
 103       // Because $args are passed as references to the WordPress callbacks,
 104       // runHooks subsequently receives appropriately modified parameters.
 105
 106       // protect from REST calls
 107       if (function_exists('do_action_ref_array')) {
 108         do_action_ref_array($fnSuffix, $args);
 109       }
 110
 111     }
 112
 113     // The following is based on the logic of the Joomla hook file by allowing
 114     // WordPress callbacks to do their stuff before runHooks gets called.
 115
 116     // It also follows the logic of the Drupal hook file by building the "module"
 117     // (read "plugin") list and then calling runHooks directly. This should avoid
 118     // the need for the post-processing that the Joomla hook file does.
 119
 120     // Note that hooks which require a return value are incompatible with the
 121     // signature of apply_filters_ref_array and must therefore be called in
 122     // global scope, like in Drupal. It's not ideal, but plugins can always route
 123     // these calls to methods in their classes.
 124
 125     // At some point, those hooks could be pre-processed and called via the WordPress
 126     // Plugin API, but it would change their signature and require the CiviCRM docs
 127     // to be rewritten for those calls in WordPress. So it's been done this way for
 128     // now. Ideally these hooks will be deprecated in favour of hooks that do not
 129     // require return values.
 130
 131     // build list of registered plugin codes
 132     $this->buildModuleList();
 133
 134     // Call runHooks the same way Drupal does
 135     $moduleResult = $this->runHooks(
 136       $this->allModules,
 137       $fnSuffix,
 138       $numParams,
 139       $arg1, $arg2, $arg3, $arg4, $arg5, $arg6
 140     );
 141
 142     // finally, return
 143     return empty($moduleResult) ? TRUE : $moduleResult;
 144
 145   }
 146
 147   /**
 148    * Build the list of plugins ("modules" in CiviCRM terminology) to be processed for hooks.
 149    *
 150    * We need to do this to preserve the CiviCRM hook signatures for hooks that require
 151    * a return value, since the WordPress Plugin API seems to be incompatible with them.
 152    *
 153    * Copied and adapted from: CRM/Utils/Hook/Drupal6.php
 154    */
 155   public function buildModuleList() {
 156     if ($this->isBuilt === FALSE) {
 157
 158       if ($this->wordpressModules === NULL) {
 159
 160         // include custom PHP file - copied from parent->commonBuildModuleList()
 161         $config = CRM_Core_Config::singleton();
 162         if (!empty($config->customPHPPathDir) &&
 163           file_exists("{$config->customPHPPathDir}/civicrmHooks.php")
 164         ) {
 165           @include_once "{$config->customPHPPathDir}/civicrmHooks.php";
 166         }
 167
 168         // initialise with the pre-existing 'wordpress' prefix
 169         $this->wordpressModules = ['wordpress'];
 170
 171         // Use WordPress Plugin API to build list
 172         // a plugin simply needs to declare its "unique_plugin_code" thus:
 173         // add_filter('civicrm_wp_plugin_codes', 'function_that_returns_my_unique_plugin_code');
 174
 175         // protect from REST calls
 176         if (function_exists('apply_filters')) {
 177           $this->wordpressModules = apply_filters('civicrm_wp_plugin_codes', $this->wordpressModules);
 178         }
 179
 180       }
 181
 182       if ($this->civiModules === NULL) {
 183         $this->civiModules = [];
 184         $this->requireCiviModules($this->civiModules);
 185       }
 186
 187       $this->allModules = array_merge((array) $this->wordpressModules, (array) $this->civiModules);
 188       if ($this->wordpressModules !== NULL && $this->civiModules !== NULL) {
 189         // both CRM and CMS have bootstrapped, so this is the final list
 190         $this->isBuilt = TRUE;
 191       }
 192
 193     }
 194   }
 195
 196 }