3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
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 +--------------------------------------------------------------------+
15 * @copyright CiviCRM LLC https://civicrm.org/licensing
21 * This class contains functions for email handling.
23 class CRM_Core_BAO_Email
extends CRM_Core_DAO_Email
implements Civi\Core\HookInterface
{
24 use CRM_Contact_AccessTrait
;
27 * Create email address.
29 * Note that the create function calls 'add' but has more business logic.
31 * @param array $params
36 public static function create($params) {
37 CRM_Core_BAO_Block
::handlePrimary($params, get_class());
39 $hook = empty($params['id']) ?
'create' : 'edit';
40 CRM_Utils_Hook
::pre($hook, 'Email', CRM_Utils_Array
::value('id', $params), $params);
42 $email = new CRM_Core_DAO_Email();
43 $email->copyValues($params);
44 if (!empty($email->email
)) {
45 // lower case email field to optimize queries
46 $strtolower = function_exists('mb_strtolower') ?
'mb_strtolower' : 'strtolower';
47 $email->email
= $strtolower($email->email
);
51 // Since we're setting bulkmail for 1 of this contact's emails, first reset
52 // all their other emails to is_bulkmail false. We shouldn't set the current
53 // email to false even though we are about to reset it to avoid
54 // contaminating the changelog if logging is enabled. (only 1 email
55 // address can have is_bulkmail = true)
57 // Note setting a the is_bulkmail to '' in $params results in $email->is_bulkmail === 'null'.
58 // @see https://lab.civicrm.org/dev/core/-/issues/2254
60 if ($email->is_bulkmail
== 1 && !empty($params['contact_id']) && !self
::isMultipleBulkMail()) {
64 WHERE contact_id = {$params['contact_id']}
66 if ($hook === 'edit') {
67 $sql .= " AND id <> {$params['id']}";
69 CRM_Core_DAO
::executeQuery($sql);
72 // handle if email is on hold
73 self
::holdEmail($email);
77 $contactId = (int) ($email->contact_id ?? CRM_Core_DAO
::getFieldValue(__CLASS__
, $email->id
, 'contact_id'));
78 if ($contactId && $email->is_primary
) {
79 $address = $email->email ?? CRM_Core_DAO
::getFieldValue(__CLASS__
, $email->id
, 'email');
80 self
::updateContactName($contactId, $address);
83 CRM_Utils_Hook
::post($hook, 'Email', $email->id
, $email);
88 * Event fired after modifying an Email.
89 * @param \Civi\Core\Event\PostEvent $event
91 public static function self_hook_civicrm_post(\Civi\Core\Event\PostEvent
$event) {
92 if ($event->action
!== 'delete' && !empty($event->object->is_primary
) && !empty($event->object->contact_id
)) {
93 // update the UF user email if that has changed
94 CRM_Core_BAO_UFMatch
::updateUFName($event->object->contact_id
);
99 * Takes an associative array and adds email.
101 * @param array $params
102 * (reference ) an assoc array of name/value pairs.
105 * CRM_Core_BAO_Email object on success, null otherwise
107 public static function add(&$params) {
108 CRM_Core_Error
::deprecatedFunctionWarning('apiv4 create');
109 return self
::create($params);
113 * Given the list of params in the params array, fetch the object
114 * and store the values in the values array
116 * @param array $entityBlock
117 * Input parameters to find object.
121 public static function getValues($entityBlock) {
122 return CRM_Core_BAO_Block
::getValues('email', $entityBlock);
126 * Get all the emails for a specified contact_id, with the primary email being first
131 * @param bool $updateBlankLocInfo
134 * the array of email id's
136 public static function allEmails($id, $updateBlankLocInfo = FALSE) {
143 civicrm_location_type.name as locationType,
144 civicrm_email.is_primary as is_primary,
145 civicrm_email.on_hold as on_hold,
146 civicrm_email.id as email_id,
147 civicrm_email.location_type_id as locationTypeId
149 LEFT JOIN civicrm_email ON ( civicrm_email.contact_id = civicrm_contact.id )
150 LEFT JOIN civicrm_location_type ON ( civicrm_email.location_type_id = civicrm_location_type.id )
151 WHERE civicrm_contact.id = %1
152 ORDER BY civicrm_email.is_primary DESC, email_id ASC ";
160 $emails = $values = [];
161 $dao = CRM_Core_DAO
::executeQuery($query, $params);
163 while ($dao->fetch()) {
165 'locationType' => $dao->locationType
,
166 'is_primary' => $dao->is_primary
,
167 'on_hold' => $dao->on_hold
,
168 'id' => $dao->email_id
,
169 'email' => $dao->email
,
170 'locationTypeId' => $dao->locationTypeId
,
173 if ($updateBlankLocInfo) {
174 $emails[$count++
] = $values;
177 $emails[$dao->email_id
] = $values;
184 * Get all the emails for a specified location_block id, with the primary email being first
186 * @param array $entityElements
187 * The array containing entity_id and.
191 * the array of email id's
193 public static function allEntityEmails(&$entityElements) {
194 if (empty($entityElements)) {
198 $entityId = $entityElements['entity_id'];
199 $entityTable = $entityElements['entity_table'];
201 $sql = " SELECT email, ltype.name as locationType, e.is_primary as is_primary, e.on_hold as on_hold,e.id as email_id, e.location_type_id as locationTypeId
202 FROM civicrm_loc_block loc, civicrm_email e, civicrm_location_type ltype, {$entityTable} ev
204 AND loc.id = ev.loc_block_id
205 AND e.id IN (loc.email_id, loc.email_2_id)
206 AND ltype.id = e.location_type_id
207 ORDER BY e.is_primary DESC, email_id ASC ";
217 $dao = CRM_Core_DAO
::executeQuery($sql, $params);
218 while ($dao->fetch()) {
219 $emails[$dao->email_id
] = [
220 'locationType' => $dao->locationType
,
221 'is_primary' => $dao->is_primary
,
222 'on_hold' => $dao->on_hold
,
223 'id' => $dao->email_id
,
224 'email' => $dao->email
,
225 'locationTypeId' => $dao->locationTypeId
,
233 * Set / reset hold status for an email
235 * @param object $email
238 public static function holdEmail(&$email) {
239 if ($email->id
&& $email->on_hold
=== NULL) {
240 // email is being updated but no change to on_hold.
243 if ($email->on_hold
=== 'null' ||
$email->on_hold
=== NULL) {
244 // legacy handling, deprecated.
247 $email->on_hold
= (int) $email->on_hold
;
249 //check for update mode
251 $params = [1 => [$email->id
, 'Integer']];
252 if ($email->on_hold
) {
257 AND hold_date IS NULL
259 if (CRM_Core_DAO
::singleValueQuery($sql, $params)) {
260 $email->hold_date
= date('YmdHis');
261 $email->reset_date
= 'null';
264 elseif ($email->on_hold
=== 0) {
265 // we do this lookup to see if reset_date should be changed.
270 AND hold_date IS NOT NULL
271 AND reset_date IS NULL
273 if (CRM_Core_DAO
::singleValueQuery($sql, $params)) {
274 //set reset date only if it is not set and if hold date is set
275 $email->on_hold
= FALSE;
276 $email->hold_date
= 'null';
277 $email->reset_date
= date('YmdHis');
282 if ($email->on_hold
) {
283 $email->hold_date
= date('YmdHis');
289 * Generate an array of Domain email addresses.
290 * @return array $domainEmails;
292 public static function domainEmails() {
294 $domainFrom = (array) CRM_Core_OptionGroup
::values('from_email_address');
295 foreach (array_keys($domainFrom) as $k) {
296 $domainEmail = $domainFrom[$k];
297 $domainEmails[$domainEmail] = htmlspecialchars($domainEmail);
299 return $domainEmails;
303 * Build From Email as the combination of all the email ids of the logged in user and
304 * the domain email id
307 * an array of email ids
309 public static function getFromEmail() {
310 // add all configured FROM email addresses
311 $fromEmailValues = self
::domainEmails();
313 if (!Civi
::settings()->get('allow_mail_from_logged_in_contact')) {
314 return $fromEmailValues;
317 $contactFromEmails = [];
318 // add logged in user's active email ids
319 $contactID = CRM_Core_Session
::getLoggedInContactID();
321 $contactEmails = self
::allEmails($contactID);
322 $fromDisplayName = CRM_Core_Session
::singleton()->getLoggedInContactDisplayName();
324 foreach ($contactEmails as $emailId => $emailVal) {
325 $email = trim($emailVal['email']);
326 if (!$email ||
$emailVal['on_hold']) {
329 $fromEmail = "$fromDisplayName <$email>";
330 $fromEmailHtml = htmlspecialchars($fromEmail) . ' ' . $emailVal['locationType'];
332 if (!empty($emailVal['is_primary'])) {
333 $fromEmailHtml .= ' ' . ts('(preferred)');
335 $contactFromEmails[$emailId] = $fromEmailHtml;
338 return CRM_Utils_Array
::crmArrayMerge($contactFromEmails, $fromEmailValues);
344 public static function isMultipleBulkMail() {
345 return Civi
::settings()->get('civimail_multiple_bulk_emails');
349 * Call common delete function.
351 * @see \CRM_Contact_BAO_Contact::on_hook_civicrm_post
357 public static function del($id) {
358 return (bool) self
::deleteRecord(['id' => $id]);
362 * Get filters for entity reference fields.
366 public static function getEntityRefFilters() {
367 $contactFields = CRM_Contact_BAO_Contact
::getEntityRefFilters();
368 foreach ($contactFields as $index => &$contactField) {
369 if (!empty($contactField['entity'])) {
370 // For now email_getlist can't parse state, country etc.
371 unset($contactFields[$index]);
373 elseif ($contactField['key'] !== 'contact_id') {
374 $contactField['entity'] = 'Contact';
375 $contactField['key'] = 'contact_id.' . $contactField['key'];
378 return $contactFields;
384 * @param int $contactId
385 * @param string $primaryEmail
387 public static function updateContactName($contactId, string $primaryEmail) {
388 if (is_string($primaryEmail) && $primaryEmail !== '' &&
389 !CRM_Contact_BAO_Contact
::hasName(['id' => $contactId])
391 CRM_Core_DAO
::setFieldValue('CRM_Contact_DAO_Contact', $contactId, 'display_name', $primaryEmail);
392 CRM_Core_DAO
::setFieldValue('CRM_Contact_DAO_Contact', $contactId, 'sort_name', $primaryEmail);
397 * Get default text for a message with the signature from the email sender populated.
399 * @param int $emailID
403 * @throws \API_Exception
404 * @throws \Civi\API\Exception\UnauthorizedException
406 public static function getEmailSignatureDefaults(int $emailID): array {
408 $defaultEmail = Email
::get(FALSE)
409 ->addSelect('signature_html', 'signature_text')
410 ->addWhere('id', '=', $emailID)->execute()->first();
412 'html_message' => empty($defaultEmail['signature_html']) ?
'' : '<br/><br/>--' . $defaultEmail['signature_html'],
413 'text_message' => empty($defaultEmail['signature_text']) ?
'' : "\n\n--\n" . $defaultEmail['signature_text'],