CRM/Utils/Hook/WordPress.php

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