CRM/Core/Action.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  * The core concept of the system is an action performed on an object. Typically this will be a "data model" object
  30  * as specified in the API specs. We attempt to keep the number and type of actions consistent
  31  * and similar across all objects (thus providing both reuse and standards)
  32  *
  33  * @package CRM
  34  * @copyright CiviCRM LLC (c) 2004-2019
  35  * $Id$
  36  *
  37  */
  38 class CRM_Core_Action {
  39
  40   /**
  41    * Different possible actions are defined here. Keep in sync with the
  42    * constant from CRM_Core_Form for various modes.
  43    *
  44    * @var int
  45    */
  46   const
  47     NONE = 0,
  48     ADD = 1,
  49     UPDATE = 2,
  50     VIEW = 4,
  51     DELETE = 8,
  52     BROWSE = 16,
  53     ENABLE = 32,
  54     DISABLE = 64,
  55     EXPORT = 128,
  56     BASIC = 256,
  57     ADVANCED = 512,
  58     PREVIEW = 1024,
  59     FOLLOWUP = 2048,
  60     MAP = 4096,
  61     PROFILE = 8192,
  62     COPY = 16384,
  63     RENEW = 32768,
  64     DETACH = 65536,
  65     REVERT = 131072,
  66     CLOSE = 262144,
  67     REOPEN = 524288,
  68     MAX_ACTION = 1048575;
  69
  70   //make sure MAX_ACTION = 2^n - 1 ( n = total number of actions )
  71
  72   /**
  73    * Map the action names to the relevant constant. We perform
  74    * bit manipulation operations so we can perform multiple
  75    * actions on the same object if needed
  76    *
  77    * @var array
  78    *
  79    */
  80   public static $_names = [
  81     'add' => self::ADD,
  82     'update' => self::UPDATE,
  83     'view' => self::VIEW,
  84     'delete' => self::DELETE,
  85     'browse' => self::BROWSE,
  86     'enable' => self::ENABLE,
  87     'disable' => self::DISABLE,
  88     'export' => self::EXPORT,
  89     'preview' => self::PREVIEW,
  90     'map' => self::MAP,
  91     'copy' => self::COPY,
  92     'profile' => self::PROFILE,
  93     'renew' => self::RENEW,
  94     'detach' => self::DETACH,
  95     'revert' => self::REVERT,
  96     'close' => self::CLOSE,
  97     'reopen' => self::REOPEN,
  98   ];
  99
 100   /**
 101    * The flipped version of the names array, initialized when used
 102    *
 103    * @var array
 104    */
 105   public static $_description;
 106
 107   /**
 108    * Called by the request object to translate a string into a mask.
 109    *
 110    * @param string $str
 111    *   The action to be resolved.
 112    *
 113    * @return int
 114    *   the action mask corresponding to the input string
 115    */
 116   public static function resolve($str) {
 117     $action = 0;
 118     if ($str) {
 119       $items = explode('|', $str);
 120       $action = self::map($items);
 121     }
 122     return $action;
 123   }
 124
 125   /**
 126    * Given a string or an array of strings, determine the bitmask
 127    * for this set of actions
 128    *
 129    * @param mixed $item
 130    *   Either a single string or an array of strings.
 131    *
 132    * @return int
 133    *   the action mask corresponding to the input args
 134    */
 135   public static function map($item) {
 136     $mask = 0;
 137
 138     if (is_array($item)) {
 139       foreach ($item as $it) {
 140         $mask |= self::mapItem($it);
 141       }
 142       return $mask;
 143     }
 144     else {
 145       return self::mapItem($item);
 146     }
 147   }
 148
 149   /**
 150    * Given a string determine the bitmask for this specific string.
 151    *
 152    * @param string $item
 153    *   The input action to process.
 154    *
 155    * @return int
 156    *   the action mask corresponding to the input string
 157    */
 158   public static function mapItem($item) {
 159     $mask = CRM_Utils_Array::value(trim($item), self::$_names);
 160     return $mask ? $mask : 0;
 161   }
 162
 163   /**
 164    *
 165    * Given an action mask, find the corresponding description
 166    *
 167    * @param int $mask
 168    *   The action mask.
 169    *
 170    * @return string
 171    *   the corresponding action description
 172    */
 173   public static function description($mask) {
 174     if (!isset(self::$_description)) {
 175       self::$_description = array_flip(self::$_names);
 176     }
 177
 178     return CRM_Utils_Array::value($mask, self::$_description, 'NO DESCRIPTION SET');
 179   }
 180
 181   /**
 182    * Given a set of links and a mask, return the html action string for
 183    * the links associated with the mask
 184    *
 185    * @param array $links
 186    *   The set of link items.
 187    * @param int $mask
 188    *   The mask to be used. a null mask means all items.
 189    * @param array $values
 190    *   The array of values for parameter substitution in the link items.
 191    * @param string $extraULName
 192    *   Enclosed extra links in this UL.
 193    * @param bool $enclosedAllInSingleUL
 194    *   Force to enclosed all links in single UL.
 195    *
 196    * @param null $op
 197    * @param null $objectName
 198    * @param int $objectId
 199    *
 200    * @return string
 201    *   the html string
 202    */
 203   public static function formLink(
 204     $links,
 205     $mask,
 206     $values,
 207     $extraULName = 'more',
 208     $enclosedAllInSingleUL = FALSE,
 209     $op = NULL,
 210     $objectName = NULL,
 211     $objectId = NULL
 212   ) {
 213     if (empty($links)) {
 214       return NULL;
 215     }
 216
 217     // make links indexed sequentially instead of by bitmask
 218     // otherwise it's next to impossible to reliably add new ones
 219     $seqLinks = [];
 220     foreach ($links as $bit => $link) {
 221       $link['bit'] = $bit;
 222       $seqLinks[] = $link;
 223     }
 224
 225     if ($op && $objectName && $objectId) {
 226       CRM_Utils_Hook::links($op, $objectName, $objectId, $seqLinks, $mask, $values);
 227     }
 228
 229     $url = [];
 230
 231     foreach ($seqLinks as $i => $link) {
 232       if (!$mask || !array_key_exists('bit', $link) || ($mask & $link['bit'])) {
 233         $extra = isset($link['extra']) ? self::replace($link['extra'], $values) : NULL;
 234
 235         $frontend = (isset($link['fe'])) ? TRUE : FALSE;
 236
 237         if (isset($link['qs']) && !CRM_Utils_System::isNull($link['qs'])) {
 238           $urlPath = CRM_Utils_System::url(self::replace($link['url'], $values),
 239             self::replace($link['qs'], $values), FALSE, NULL, TRUE, $frontend
 240           );
 241         }
 242         else {
 243           $urlPath = CRM_Utils_Array::value('url', $link, '#');
 244         }
 245
 246         $classes = 'action-item crm-hover-button';
 247         if (isset($link['ref'])) {
 248           $classes .= ' ' . strtolower($link['ref']);
 249         }
 250
 251         //get the user specified classes in.
 252         if (isset($link['class'])) {
 253           $className = is_array($link['class']) ? implode(' ', $link['class']) : $link['class'];
 254           $classes .= ' ' . strtolower($className);
 255         }
 256
 257         if ($urlPath !== '#' && $frontend) {
 258           $extra .= ' target="_blank"';
 259         }
 260         // Hack to make delete dialogs smaller
 261         if (strpos($urlPath, '/delete') || strpos($urlPath, 'action=delete')) {
 262           $classes .= " small-popup";
 263         }
 264         $url[] = sprintf('<a href="%s" class="%s" %s' . $extra . '>%s</a>',
 265           $urlPath,
 266           $classes,
 267           !empty($link['title']) ? "title='{$link['title']}' " : '',
 268           $link['name']
 269         );
 270       }
 271     }
 272
 273     $mainLinks = $url;
 274     if ($enclosedAllInSingleUL) {
 275       $allLinks = '';
 276       CRM_Utils_String::append($allLinks, '</li><li>', $mainLinks);
 277       $allLinks = "{$extraULName}<ul class='panel'><li>{$allLinks}</li></ul>";
 278       $result = "<span class='btn-slide crm-hover-button'>{$allLinks}</span>";
 279     }
 280     else {
 281       $extra = '';
 282       $extraLinks = array_splice($url, 2);
 283       if (count($extraLinks) > 1) {
 284         $mainLinks = array_slice($url, 0, 2);
 285         CRM_Utils_String::append($extra, '</li><li>', $extraLinks);
 286         $extra = "{$extraULName}<ul class='panel'><li>{$extra}</li></ul>";
 287       }
 288       $resultLinks = '';
 289       CRM_Utils_String::append($resultLinks, '', $mainLinks);
 290       if ($extra) {
 291         $result = "<span>{$resultLinks}</span><span class='btn-slide crm-hover-button'>{$extra}</span>";
 292       }
 293       else {
 294         $result = "<span>{$resultLinks}</span>";
 295       }
 296     }
 297
 298     return $result;
 299   }
 300
 301   /**
 302    * Given a set of links and a mask, return a filtered (by mask) array containing the final links with parsed values
 303    *   and calling hooks as appropriate.
 304    * Use this when passing a set of action links to the API or to the form without adding html formatting.
 305    *
 306    * @param array $links
 307    *   The set of link items.
 308    * @param int $mask
 309    *   The mask to be used. a null mask means all items.
 310    * @param array $values
 311    *   The array of values for parameter substitution in the link items.
 312    * @param null $op
 313    * @param null $objectName
 314    * @param int $objectId
 315    *
 316    * @return array|null
 317    *   The array describing each link
 318    */
 319   public static function filterLinks(
 320     $links,
 321     $mask,
 322     $values,
 323     $op = NULL,
 324     $objectName = NULL,
 325     $objectId = NULL
 326   ) {
 327     if (empty($links)) {
 328       return NULL;
 329     }
 330
 331     // make links indexed sequentially instead of by bitmask
 332     // otherwise it's next to impossible to reliably add new ones
 333     $seqLinks = array();
 334     foreach ($links as $bit => $link) {
 335       $link['bit'] = $bit;
 336       $seqLinks[] = $link;
 337     }
 338
 339     if ($op && $objectName && $objectId) {
 340       CRM_Utils_Hook::links($op, $objectName, $objectId, $seqLinks, $mask, $values);
 341     }
 342
 343     foreach ($seqLinks as $i => $link) {
 344       if (!$mask || !array_key_exists('bit', $link) || ($mask & $link['bit'])) {
 345         $seqLinks[$i]['extra'] = isset($link['extra']) ? self::replace($link['extra'], $values) : NULL;
 346
 347         if (isset($link['qs']) && !CRM_Utils_System::isNull($link['qs'])) {
 348           $seqLinks[$i]['url'] = self::replace($link['url'], $values);
 349           $seqLinks[$i]['qs'] = self::replace($link['qs'], $values);
 350         }
 351       }
 352       else {
 353         unset($seqLinks[$i]);
 354       }
 355     }
 356
 357     return $seqLinks;
 358   }
 359
 360   /**
 361    * Given a string and an array of values, substitute the real values
 362    * in the placeholder in the str in the CiviCRM format
 363    *
 364    * @param string $str
 365    *   The string to be replaced.
 366    * @param array $values
 367    *   The array of values for parameter substitution in the str.
 368    *
 369    * @return string
 370    *   the substituted string
 371    */
 372   public static function &replace(&$str, &$values) {
 373     foreach ($values as $n => $v) {
 374       $str = str_replace("%%$n%%", $v, $str);
 375     }
 376     return $str;
 377   }
 378
 379   /**
 380    * Get the mask for a permission (view, edit or null)
 381    *
 382    * @param array $permissions
 383    *
 384    * @return int
 385    *   The mask for the above permission
 386    */
 387   public static function mask($permissions) {
 388     $mask = NULL;
 389     if (!is_array($permissions) || CRM_Utils_System::isNull($permissions)) {
 390       return $mask;
 391     }
 392     //changed structure since we are handling delete separately - CRM-4418
 393     if (in_array(CRM_Core_Permission::VIEW, $permissions)) {
 394       $mask |= self::VIEW | self::EXPORT | self::BASIC | self::ADVANCED | self::BROWSE | self::MAP | self::PROFILE;
 395     }
 396     if (in_array(CRM_Core_Permission::DELETE, $permissions)) {
 397       $mask |= self::DELETE;
 398     }
 399     if (in_array(CRM_Core_Permission::EDIT, $permissions)) {
 400       //make sure we make self::MAX_ACTION = 2^n - 1
 401       //if we add more actions; ( n = total number of actions )
 402       $mask |= (self::MAX_ACTION & ~self::DELETE);
 403     }
 404
 405     return $mask;
 406   }
 407
 408 }