Civi/ActionSchedule/Mapping.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 namespace Civi\ActionSchedule;
  13
  14 /**
  15  * Class Mapping
  16  * @package Civi\ActionSchedule
  17  *
  18  * This is the initial implementation of MappingInterface; it was
  19  * constructed by cutting out swaths from CRM_Core_BAO_ActionSchedule.
  20  * New implementers should consider implementing MappingInterface on
  21  * their own.
  22  *
  23  * Background: The original designers of ActionMappings intended that
  24  * one could create and configure new mappings through the database.
  25  * To, e.g., define the filtering options for CiviEvent, you
  26  * would insert a record in "civicrm_action_mapping" with fields like
  27  * "entity" (a table name, eg "civicrm_event"), "entity_value" (an
  28  * option-group name, eg "event_types").
  29  *
  30  * Unfortunately, the metadata in "civicrm_action_mapping" proved
  31  * inadequate and was not updated to cope. Instead, a number
  32  * of work-arounds for specific entities were hard-coded into
  33  * the core action-scheduling code. Ultimately, to add a new
  34  * mapping type, one needed to run around and patch a dozen
  35  * places.
  36  *
  37  * The new MappingInterface makes no pretense of database-driven
  38  * configuration. The dozen places have been consolidated and
  39  * replaced with functions in MappingInterface.
  40  *
  41  * This "Mapping" implementation is a refactoring of the old
  42  * hard-coded bits. Internally, it uses the concepts from
  43  * "civicrm_action_mapping". The resulting code is more
  44  * convoluted than a clean implementation of MappingInterface, but
  45  * it strictly matches the old behavior (based on logging/comparing
  46  * the queries produced through ActionScheduleTest).
  47  */
  48 abstract class Mapping implements MappingInterface {
  49
  50   private static $fields = [
  51     'id',
  52     'entity',
  53     'entity_label',
  54     'entity_value',
  55     'entity_value_label',
  56     'entity_status',
  57     'entity_status_label',
  58     'entity_date_start',
  59     'entity_date_end',
  60   ];
  61
  62   /**
  63    * Create mapping.
  64    *
  65    * @param array $params
  66    *
  67    * @return static
  68    */
  69   public static function create($params) {
  70     return new static($params);
  71   }
  72
  73   /**
  74    * Class constructor.
  75    *
  76    * @param array $params
  77    */
  78   public function __construct($params) {
  79     foreach (self::$fields as $field) {
  80       if (isset($params[$field])) {
  81         $this->{$field} = $params[$field];
  82       }
  83     }
  84   }
  85
  86   protected $id;
  87
  88   /**
  89    * The basic entity to query (table name).
  90    *
  91    * @var string
  92    *   Ex: 'civicrm_activity', 'civicrm_event'.
  93    */
  94   protected $entity;
  95
  96   /**
  97    * The basic entity to query (label).
  98    *
  99    * @var string
 100    *   Ex: 'Activity', 'Event'
 101    */
 102   private $entity_label;
 103
 104   /**
 105    * Level 1 filter -- the field/option-list to filter on.
 106    *
 107    * @var string
 108    *   Ex: 'activity_type', 'civicrm_event', 'event_template'.
 109    */
 110   private $entity_value;
 111
 112   /**
 113    * Level 1 filter -- The field label.
 114    *
 115    * @var string
 116    *   Ex: 'Activity Type', 'Event Name', 'Event Template'.
 117    */
 118   private $entity_value_label;
 119
 120   /**
 121    * Level 2 filter -- the field/option-list to filter on.
 122    * @var string
 123    *   Ex: 'activity_status, 'civicrm_participant_status_type', 'auto_renew_options'.
 124    */
 125   private $entity_status;
 126
 127   /**
 128    * Level 2 filter -- the field label.
 129    * @var string
 130    *   Ex: 'Activity Status', 'Participant Status', 'Auto Rewnewal Options'.
 131    */
 132   private $entity_status_label;
 133
 134   /**
 135    * Date filter -- the field name.
 136    * @var string|null
 137    *   Ex: 'event_start_date'
 138    */
 139   private $entity_date_start;
 140
 141   /**
 142    * Date filter -- the field name.
 143    * @var string|null
 144    *   Ex: 'event_end_date'.
 145    */
 146   private $entity_date_end;
 147
 148   /**
 149    * @return mixed
 150    */
 151   public function getId() {
 152     return $this->id;
 153   }
 154
 155   /**
 156    * @return string
 157    */
 158   public function getEntity() {
 159     return $this->entity;
 160   }
 161
 162   /**
 163    * Get a printable label for this mapping type.
 164    *
 165    * @return string
 166    */
 167   public function getLabel() {
 168     return $this->entity_label;
 169   }
 170
 171   /**
 172    * Get a printable label to use a header on the 'value' filter.
 173    *
 174    * @return string
 175    */
 176   public function getValueHeader() {
 177     return $this->entity_value_label;
 178   }
 179
 180   /**
 181    * Get a printable label to use a header on the 'status' filter.
 182    *
 183    * @return string
 184    */
 185   public function getStatusHeader() {
 186     return $this->entity_status_label;
 187   }
 188
 189   /**
 190    * Get a list of value options.
 191    *
 192    * @return array
 193    *   Array(string $value => string $label).
 194    *   Ex: array(123 => 'Phone Call', 456 => 'Meeting').
 195    */
 196   public function getValueLabels() {
 197     return self::getValueLabelMap($this->entity_value);
 198   }
 199
 200   /**
 201    * Get a list of status options.
 202    *
 203    * @param string|int $value
 204    *   The list of status options may be contingent upon the selected filter value.
 205    *   This is the selected filter value.
 206    * @return array
 207    *   Array(string $value => string $label).
 208    *   Ex: Array(123 => 'Completed', 456 => 'Scheduled').
 209    */
 210   public function getStatusLabels($value) {
 211     if ($this->entity_status === 'auto_renew_options') {
 212       if ($value && \CRM_Core_DAO::getFieldValue('CRM_Member_DAO_MembershipType', $value, 'auto_renew')) {
 213         return \CRM_Core_OptionGroup::values('auto_renew_options');
 214       }
 215       else {
 216         return [];
 217       }
 218     }
 219     return self::getValueLabelMap($this->entity_status);
 220   }
 221
 222   /**
 223    * Get a list of available date fields.
 224    *
 225    * @return array
 226    *   Array(string $fieldName => string $fieldLabel).
 227    */
 228   public function getDateFields() {
 229     $dateFieldLabels = [];
 230     if (!empty($this->entity_date_start)) {
 231       $dateFieldLabels[$this->entity_date_start] = ucwords(str_replace('_', ' ', $this->entity_date_start));
 232     }
 233     if (!empty($this->entity_date_end)) {
 234       $dateFieldLabels[$this->entity_date_end] = ucwords(str_replace('_', ' ', $this->entity_date_end));
 235     }
 236     return $dateFieldLabels;
 237   }
 238
 239   /**
 240    * Get a list of recipient types.
 241    *
 242    * Note: A single schedule may filter on *zero* or *one* recipient types.
 243    * When an admin chooses a value, it's stored in $schedule->recipient.
 244    *
 245    * @return array
 246    *   array(string $value => string $label).
 247    *   Ex: array('assignee' => 'Activity Assignee').
 248    */
 249   public function getRecipientTypes() {
 250     return [];
 251   }
 252
 253   /**
 254    * Get a list of recipients which match the given type.
 255    *
 256    * Note: A single schedule may filter on *multiple* recipients.
 257    * When an admin chooses value(s), it's stored in $schedule->recipient_listing.
 258    *
 259    * @param string $recipientType
 260    *   Ex: 'participant_role'.
 261    * @return array
 262    *   Array(mixed $name => string $label).
 263    *   Ex: array(1 => 'Attendee', 2 => 'Volunteer').
 264    * @see getRecipientTypes
 265    */
 266   public function getRecipientListing($recipientType) {
 267     return [];
 268   }
 269
 270   protected static function getValueLabelMap($name) {
 271     static $valueLabelMap = NULL;
 272     if ($valueLabelMap === NULL) {
 273       // CRM-20510: Include CiviCampaign activity types along with CiviCase IF component is enabled
 274       $valueLabelMap['activity_type'] = \CRM_Core_PseudoConstant::activityType(TRUE, TRUE, FALSE, 'label', TRUE);
 275       asort($valueLabelMap['activity_type']);
 276
 277       $valueLabelMap['activity_status'] = \CRM_Core_PseudoConstant::activityStatus();
 278       $valueLabelMap['event_type'] = \CRM_Event_PseudoConstant::eventType();
 279       $valueLabelMap['civicrm_event'] = \CRM_Event_PseudoConstant::event(NULL, FALSE, "( is_template IS NULL OR is_template != 1 )");
 280       $valueLabelMap['civicrm_participant_status_type'] = \CRM_Event_PseudoConstant::participantStatus(NULL, NULL, 'label');
 281       $valueLabelMap['event_template'] = \CRM_Event_PseudoConstant::eventTemplates();
 282       $valueLabelMap['auto_renew_options'] = \CRM_Core_OptionGroup::values('auto_renew_options');
 283       $valueLabelMap['contact_date_reminder_options'] = \CRM_Core_OptionGroup::values('contact_date_reminder_options');
 284       $valueLabelMap['civicrm_membership_type'] = \CRM_Member_PseudoConstant::membershipType();
 285
 286       $allCustomFields = \CRM_Core_BAO_CustomField::getFields('');
 287       $dateFields = [
 288         'birth_date' => ts('Birth Date'),
 289         'created_date' => ts('Created Date'),
 290         'modified_date' => ts('Modified Date'),
 291       ];
 292       foreach ($allCustomFields as $fieldID => $field) {
 293         if ($field['data_type'] == 'Date') {
 294           $dateFields["custom_$fieldID"] = $field['label'];
 295         }
 296       }
 297       $valueLabelMap['civicrm_contact'] = $dateFields;
 298     }
 299
 300     return $valueLabelMap[$name];
 301   }
 302
 303   /**
 304    * Determine whether a schedule based on this mapping is sufficiently
 305    * complete.
 306    *
 307    * @param \CRM_Core_DAO_ActionSchedule $schedule
 308    * @return array
 309    *   Array (string $code => string $message).
 310    *   List of error messages.
 311    */
 312   public function validateSchedule($schedule) {
 313     return [];
 314   }
 315
 316   /**
 317    * Generate a query to locate contacts who match the given
 318    * schedule.
 319    *
 320    * @param \CRM_Core_DAO_ActionSchedule $schedule
 321    * @param string $phase
 322    *   See, e.g., RecipientBuilder::PHASE_RELATION_FIRST.
 323    * @param array $defaultParams
 324    * @return \CRM_Utils_SQL_Select
 325    */
 326   abstract public function createQuery($schedule, $phase, $defaultParams);
 327
 328   /**
 329    * Determine whether a schedule based on this mapping should
 330    * reset the reminder state if the trigger date changes.
 331    *
 332    * @return bool
 333    *
 334    * @param \CRM_Core_DAO_ActionSchedule $schedule
 335    */
 336   public function resetOnTriggerDateChange($schedule) {
 337     return FALSE;
 338   }
 339
 340 }