CRM/Contact/ActionMapping.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  * Class CRM_Contact_ActionMapping
  15  *
  16  * This defines the scheduled-reminder functionality for contact
  17  * entities. It is useful for, e.g., sending a reminder based on
  18  * birth date, modification date, or other custom dates on
  19  * the contact record.
  20  */
  21 class CRM_Contact_ActionMapping extends \Civi\ActionSchedule\Mapping {
  22
  23   /**
  24    * The value for civicrm_action_schedule.mapping_id which identifies the
  25    * "Contact" mapping.
  26    *
  27    * Note: This value is chosen to match legacy DB IDs.
  28    */
  29   const CONTACT_MAPPING_ID = 6;
  30
  31   /**
  32    * Register Contact-related action mappings.
  33    *
  34    * @param \Civi\ActionSchedule\Event\MappingRegisterEvent $registrations
  35    */
  36   public static function onRegisterActionMappings(\Civi\ActionSchedule\Event\MappingRegisterEvent $registrations) {
  37     $registrations->register(CRM_Contact_ActionMapping::create([
  38       'id' => CRM_Contact_ActionMapping::CONTACT_MAPPING_ID,
  39       'entity' => 'civicrm_contact',
  40       'entity_label' => ts('Contact'),
  41       'entity_value' => 'civicrm_contact',
  42       'entity_value_label' => ts('Date Field'),
  43       'entity_status' => 'contact_date_reminder_options',
  44       'entity_status_label' => ts('Annual Options'),
  45       'entity_date_start' => 'date_field',
  46     ]));
  47   }
  48
  49   private $contactDateFields = [
  50     'birth_date',
  51     'created_date',
  52     'modified_date',
  53   ];
  54
  55   /**
  56    * Determine whether a schedule based on this mapping is sufficiently
  57    * complete.
  58    *
  59    * @param \CRM_Core_DAO_ActionSchedule $schedule
  60    * @return array
  61    *   Array (string $code => string $message).
  62    *   List of error messages.
  63    */
  64   public function validateSchedule($schedule) {
  65     $errors = [];
  66     if (CRM_Utils_System::isNull($schedule->entity_value) || $schedule->entity_value === '0') {
  67       $errors['entity'] = ts('Please select a specific date field.');
  68     }
  69     elseif (count(CRM_Utils_Array::explodePadded($schedule->entity_value)) > 1) {
  70       $errors['entity'] = ts('You may only select one contact field per reminder');
  71     }
  72     elseif (CRM_Utils_System::isNull($schedule->entity_status) || $schedule->entity_status === '0') {
  73       $errors['entity'] = ts('Please select whether the reminder is sent each year.');
  74     }
  75
  76     return $errors;
  77   }
  78
  79   /**
  80    * Generate a query to locate recipients who match the given
  81    * schedule.
  82    *
  83    * @param \CRM_Core_DAO_ActionSchedule $schedule
  84    *   The schedule as configured by the administrator.
  85    * @param string $phase
  86    *   See, e.g., RecipientBuilder::PHASE_RELATION_FIRST.
  87    * @param array $defaultParams
  88    *
  89    * @return \CRM_Utils_SQL_Select
  90    * @throws \CRM_Core_Exception
  91    * @see RecipientBuilder
  92    */
  93   public function createQuery($schedule, $phase, $defaultParams) {
  94     $selectedValues = (array) \CRM_Utils_Array::explodePadded($schedule->entity_value);
  95     $selectedStatuses = (array) \CRM_Utils_Array::explodePadded($schedule->entity_status);
  96
  97     // FIXME: This assumes that $values only has one field, but UI shows multiselect.
  98     // Properly supporting multiselect would require total rewrite of this function.
  99     if (count($selectedValues) != 1 || !isset($selectedValues[0])) {
 100       throw new \CRM_Core_Exception("Error: Scheduled reminders may only have one contact field.");
 101     }
 102     elseif (in_array($selectedValues[0], $this->contactDateFields)) {
 103       $dateDBField = $selectedValues[0];
 104       $query = \CRM_Utils_SQL_Select::from("{$this->entity} e")->param($defaultParams);
 105       $query->param([
 106         'casAddlCheckFrom' => 'civicrm_contact e',
 107         'casContactIdField' => 'e.id',
 108         'casEntityIdField' => 'e.id',
 109         'casContactTableAlias' => 'e',
 110       ]);
 111       $query->where('e.is_deleted = 0 AND e.is_deceased = 0');
 112     }
 113     else {
 114       //custom field
 115       $customFieldParams = ['id' => substr($selectedValues[0], 7)];
 116       $customGroup = $customField = [];
 117       \CRM_Core_BAO_CustomField::retrieve($customFieldParams, $customField);
 118       $dateDBField = $customField['column_name'];
 119       $customGroupParams = ['id' => $customField['custom_group_id'], $customGroup];
 120       \CRM_Core_BAO_CustomGroup::retrieve($customGroupParams, $customGroup);
 121       $query = \CRM_Utils_SQL_Select::from("{$customGroup['table_name']} e")->param($defaultParams);
 122       $query->param([
 123         'casAddlCheckFrom' => "{$customGroup['table_name']} e",
 124         'casContactIdField' => 'e.entity_id',
 125         'casEntityIdField' => 'e.id',
 126         'casContactTableAlias' => NULL,
 127       ]);
 128       // possible to have no "where" in this case
 129       $query->where('1');
 130     }
 131
 132     $query['casDateField'] = 'e.' . $dateDBField;
 133
 134     if (in_array(2, $selectedStatuses)) {
 135       $query['casAnniversaryMode'] = 1;
 136       $query['casDateField'] = 'DATE_ADD(' . $query['casDateField'] . ', INTERVAL ROUND(DATEDIFF(DATE(' . $query['casNow'] . '), ' . $query['casDateField'] . ') / 365) YEAR)';
 137     }
 138
 139     return $query;
 140   }
 141
 142   /**
 143    * Determine whether a schedule based on this mapping should
 144    * send to additional contacts.
 145    */
 146   public function sendToAdditional($entityId): bool {
 147     return TRUE;
 148   }
 149
 150 }