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