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
19 * This class contains functions for email handling.
21 class CRM_Core_BAO_Email
extends CRM_Core_DAO_Email
{
24 * Create email address.
26 * Note that the create function calls 'add' but has more business logic.
28 * @param array $params
33 public static function create($params) {
34 CRM_Core_BAO_Block
::handlePrimary($params, get_class());
36 $hook = empty($params['id']) ?
'create' : 'edit';
37 CRM_Utils_Hook
::pre($hook, 'Email', CRM_Utils_Array
::value('id', $params), $params);
39 $email = new CRM_Core_DAO_Email();
40 $email->copyValues($params);
41 if (!empty($email->email
)) {
42 // lower case email field to optimize queries
43 $strtolower = function_exists('mb_strtolower') ?
'mb_strtolower' : 'strtolower';
44 $email->email
= $strtolower($email->email
);
48 * since we're setting bulkmail for 1 of this contact's emails, first reset all their other emails to is_bulkmail false
49 * We shouldn't set the current email to false even though we
50 * are about to reset it to avoid contaminating the changelog if logging is enabled.
51 * (only 1 email address can have is_bulkmail = true)
53 if ($email->is_bulkmail
&& !empty($params['contact_id']) && !self
::isMultipleBulkMail()) {
57 WHERE contact_id = {$params['contact_id']}
59 if ($hook === 'edit') {
60 $sql .= " AND id <> {$params['id']}";
62 CRM_Core_DAO
::executeQuery($sql);
65 // handle if email is on hold
66 self
::holdEmail($email);
70 if ($email->is_primary
) {
71 // update the UF user email if that has changed
72 CRM_Core_BAO_UFMatch
::updateUFName($email->contact_id
);
75 CRM_Utils_Hook
::post($hook, 'Email', $email->id
, $email);
80 * Takes an associative array and adds email.
82 * @param array $params
83 * (reference ) an assoc array of name/value pairs.
86 * CRM_Core_BAO_Email object on success, null otherwise
88 public static function add(&$params) {
89 CRM_Core_Error
::deprecatedFunctionWarning('apiv4 create');
90 return self
::create($params);
94 * Given the list of params in the params array, fetch the object
95 * and store the values in the values array
97 * @param array $entityBlock
98 * Input parameters to find object.
102 public static function getValues($entityBlock) {
103 return CRM_Core_BAO_Block
::getValues('email', $entityBlock);
107 * Get all the emails for a specified contact_id, with the primary email being first
112 * @param bool $updateBlankLocInfo
115 * the array of email id's
117 public static function allEmails($id, $updateBlankLocInfo = FALSE) {
124 civicrm_location_type.name as locationType,
125 civicrm_email.is_primary as is_primary,
126 civicrm_email.on_hold as on_hold,
127 civicrm_email.id as email_id,
128 civicrm_email.location_type_id as locationTypeId
130 LEFT JOIN civicrm_email ON ( civicrm_email.contact_id = civicrm_contact.id )
131 LEFT JOIN civicrm_location_type ON ( civicrm_email.location_type_id = civicrm_location_type.id )
132 WHERE civicrm_contact.id = %1
133 ORDER BY civicrm_email.is_primary DESC, email_id ASC ";
141 $emails = $values = [];
142 $dao = CRM_Core_DAO
::executeQuery($query, $params);
144 while ($dao->fetch()) {
146 'locationType' => $dao->locationType
,
147 'is_primary' => $dao->is_primary
,
148 'on_hold' => $dao->on_hold
,
149 'id' => $dao->email_id
,
150 'email' => $dao->email
,
151 'locationTypeId' => $dao->locationTypeId
,
154 if ($updateBlankLocInfo) {
155 $emails[$count++
] = $values;
158 $emails[$dao->email_id
] = $values;
165 * Get all the emails for a specified location_block id, with the primary email being first
167 * @param array $entityElements
168 * The array containing entity_id and.
172 * the array of email id's
174 public static function allEntityEmails(&$entityElements) {
175 if (empty($entityElements)) {
179 $entityId = $entityElements['entity_id'];
180 $entityTable = $entityElements['entity_table'];
182 $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
183 FROM civicrm_loc_block loc, civicrm_email e, civicrm_location_type ltype, {$entityTable} ev
185 AND loc.id = ev.loc_block_id
186 AND e.id IN (loc.email_id, loc.email_2_id)
187 AND ltype.id = e.location_type_id
188 ORDER BY e.is_primary DESC, email_id ASC ";
198 $dao = CRM_Core_DAO
::executeQuery($sql, $params);
199 while ($dao->fetch()) {
200 $emails[$dao->email_id
] = [
201 'locationType' => $dao->locationType
,
202 'is_primary' => $dao->is_primary
,
203 'on_hold' => $dao->on_hold
,
204 'id' => $dao->email_id
,
205 'email' => $dao->email
,
206 'locationTypeId' => $dao->locationTypeId
,
214 * Set / reset hold status for an email
216 * @param object $email
219 public static function holdEmail(&$email) {
220 if ($email->id
&& $email->on_hold
=== NULL) {
221 // email is being updated but no change to on_hold.
224 if ($email->on_hold
=== 'null' ||
$email->on_hold
=== NULL) {
225 // legacy handling, deprecated.
228 $email->on_hold
= (int) $email->on_hold
;
230 //check for update mode
232 $params = [1 => [$email->id
, 'Integer']];
233 if ($email->on_hold
) {
238 AND hold_date IS NULL
240 if (CRM_Core_DAO
::singleValueQuery($sql, $params)) {
241 $email->hold_date
= date('YmdHis');
242 $email->reset_date
= 'null';
245 elseif ($email->on_hold
=== 0) {
246 // we do this lookup to see if reset_date should be changed.
251 AND hold_date IS NOT NULL
252 AND reset_date IS NULL
254 if (CRM_Core_DAO
::singleValueQuery($sql, $params)) {
255 //set reset date only if it is not set and if hold date is set
256 $email->on_hold
= FALSE;
257 $email->hold_date
= 'null';
258 $email->reset_date
= date('YmdHis');
263 if ($email->on_hold
) {
264 $email->hold_date
= date('YmdHis');
270 * Generate an array of Domain email addresses.
271 * @return array $domainEmails;
273 public static function domainEmails() {
275 $domainFrom = (array) CRM_Core_OptionGroup
::values('from_email_address');
276 foreach (array_keys($domainFrom) as $k) {
277 $domainEmail = $domainFrom[$k];
278 $domainEmails[$domainEmail] = htmlspecialchars($domainEmail);
280 return $domainEmails;
284 * Build From Email as the combination of all the email ids of the logged in user and
285 * the domain email id
288 * an array of email ids
290 public static function getFromEmail() {
291 // add all configured FROM email addresses
292 $fromEmailValues = self
::domainEmails();
294 if (!Civi
::settings()->get('allow_mail_from_logged_in_contact')) {
295 return $fromEmailValues;
298 $contactFromEmails = [];
299 // add logged in user's active email ids
300 $contactID = CRM_Core_Session
::getLoggedInContactID();
302 $contactEmails = self
::allEmails($contactID);
303 $fromDisplayName = CRM_Core_Session
::singleton()->getLoggedInContactDisplayName();
305 foreach ($contactEmails as $emailId => $emailVal) {
306 $email = trim($emailVal['email']);
307 if (!$email ||
$emailVal['on_hold']) {
310 $fromEmail = "$fromDisplayName <$email>";
311 $fromEmailHtml = htmlspecialchars($fromEmail) . ' ' . $emailVal['locationType'];
313 if (!empty($emailVal['is_primary'])) {
314 $fromEmailHtml .= ' ' . ts('(preferred)');
316 $contactFromEmails[$emailId] = $fromEmailHtml;
319 return CRM_Utils_Array
::crmArrayMerge($contactFromEmails, $fromEmailValues);
325 public static function isMultipleBulkMail() {
326 return Civi
::settings()->get('civimail_multiple_bulk_emails');
330 * Call common delete function.
336 public static function del($id) {
337 return CRM_Contact_BAO_Contact
::deleteObjectWithPrimary('Email', $id);
341 * Get filters for entity reference fields.
345 public static function getEntityRefFilters() {
346 $contactFields = CRM_Contact_BAO_Contact
::getEntityRefFilters();
347 foreach ($contactFields as $index => &$contactField) {
348 if (!empty($contactField['entity'])) {
349 // For now email_getlist can't parse state, country etc.
350 unset($contactFields[$index]);
352 elseif ($contactField['key'] !== 'contact_id') {
353 $contactField['entity'] = 'Contact';
354 $contactField['key'] = 'contact_id.' . $contactField['key'];
357 return $contactFields;