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 // if id is set & is_primary isn't we can assume no change
35 if (is_numeric(CRM_Utils_Array
::value('is_primary', $params)) ||
empty($params['id'])) {
36 CRM_Core_BAO_Block
::handlePrimary($params, get_class());
39 $email = CRM_Core_BAO_Email
::add($params);
45 * Takes an associative array and adds email.
47 * @param array $params
48 * (reference ) an assoc array of name/value pairs.
51 * CRM_Core_BAO_Email object on success, null otherwise
53 public static function add(&$params) {
54 $hook = empty($params['id']) ?
'create' : 'edit';
55 CRM_Utils_Hook
::pre($hook, 'Email', CRM_Utils_Array
::value('id', $params), $params);
57 if (isset($params['is_bulkmail']) && $params['is_bulkmail'] === 'null') {
58 CRM_Core_Error
::deprecatedFunctionWarning('It is not valid to set bulkmail to null, it is boolean');
59 $params['bulkmail'] = 0;
61 $email = new CRM_Core_DAO_Email();
62 $email->copyValues($params);
63 if (!empty($email->email
)) {
64 // lower case email field to optimize queries
65 $strtolower = function_exists('mb_strtolower') ?
'mb_strtolower' : 'strtolower';
66 $email->email
= $strtolower($email->email
);
70 * since we're setting bulkmail for 1 of this contact's emails, first reset all their other emails to is_bulkmail false
71 * We shouldn't set the current email to false even though we
72 * are about to reset it to avoid contaminating the changelog if logging is enabled.
73 * (only 1 email address can have is_bulkmail = true)
75 if ($email->is_bulkmail
&& !empty($params['contact_id']) && !self
::isMultipleBulkMail()) {
79 WHERE contact_id = {$params['contact_id']}
81 if ($hook === 'edit') {
82 $sql .= " AND id <> {$params['id']}";
84 CRM_Core_DAO
::executeQuery($sql);
87 // handle if email is on hold
88 self
::holdEmail($email);
92 if ($email->is_primary
) {
93 // update the UF user email if that has changed
94 CRM_Core_BAO_UFMatch
::updateUFName($email->contact_id
);
97 CRM_Utils_Hook
::post($hook, 'Email', $email->id
, $email);
102 * Given the list of params in the params array, fetch the object
103 * and store the values in the values array
105 * @param array $entityBlock
106 * Input parameters to find object.
110 public static function getValues($entityBlock) {
111 return CRM_Core_BAO_Block
::getValues('email', $entityBlock);
115 * Get all the emails for a specified contact_id, with the primary email being first
120 * @param bool $updateBlankLocInfo
123 * the array of email id's
125 public static function allEmails($id, $updateBlankLocInfo = FALSE) {
132 civicrm_location_type.name as locationType,
133 civicrm_email.is_primary as is_primary,
134 civicrm_email.on_hold as on_hold,
135 civicrm_email.id as email_id,
136 civicrm_email.location_type_id as locationTypeId
138 LEFT JOIN civicrm_email ON ( civicrm_email.contact_id = civicrm_contact.id )
139 LEFT JOIN civicrm_location_type ON ( civicrm_email.location_type_id = civicrm_location_type.id )
140 WHERE civicrm_contact.id = %1
141 ORDER BY civicrm_email.is_primary DESC, email_id ASC ";
149 $emails = $values = [];
150 $dao = CRM_Core_DAO
::executeQuery($query, $params);
152 while ($dao->fetch()) {
154 'locationType' => $dao->locationType
,
155 'is_primary' => $dao->is_primary
,
156 'on_hold' => $dao->on_hold
,
157 'id' => $dao->email_id
,
158 'email' => $dao->email
,
159 'locationTypeId' => $dao->locationTypeId
,
162 if ($updateBlankLocInfo) {
163 $emails[$count++
] = $values;
166 $emails[$dao->email_id
] = $values;
173 * Get all the emails for a specified location_block id, with the primary email being first
175 * @param array $entityElements
176 * The array containing entity_id and.
180 * the array of email id's
182 public static function allEntityEmails(&$entityElements) {
183 if (empty($entityElements)) {
187 $entityId = $entityElements['entity_id'];
188 $entityTable = $entityElements['entity_table'];
190 $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
191 FROM civicrm_loc_block loc, civicrm_email e, civicrm_location_type ltype, {$entityTable} ev
193 AND loc.id = ev.loc_block_id
194 AND e.id IN (loc.email_id, loc.email_2_id)
195 AND ltype.id = e.location_type_id
196 ORDER BY e.is_primary DESC, email_id ASC ";
206 $dao = CRM_Core_DAO
::executeQuery($sql, $params);
207 while ($dao->fetch()) {
208 $emails[$dao->email_id
] = [
209 'locationType' => $dao->locationType
,
210 'is_primary' => $dao->is_primary
,
211 'on_hold' => $dao->on_hold
,
212 'id' => $dao->email_id
,
213 'email' => $dao->email
,
214 'locationTypeId' => $dao->locationTypeId
,
222 * Set / reset hold status for an email
224 * @param object $email
227 public static function holdEmail(&$email) {
228 if ($email->id
&& $email->on_hold
=== NULL) {
229 // email is being updated but no change to on_hold.
232 if ($email->on_hold
=== 'null' ||
$email->on_hold
=== NULL) {
233 // legacy handling, deprecated.
236 $email->on_hold
= (int) $email->on_hold
;
238 //check for update mode
240 $params = [1 => [$email->id
, 'Integer']];
241 if ($email->on_hold
) {
246 AND hold_date IS NULL
248 if (CRM_Core_DAO
::singleValueQuery($sql, $params)) {
249 $email->hold_date
= date('YmdHis');
250 $email->reset_date
= 'null';
253 elseif ($email->on_hold
=== 0) {
254 // we do this lookup to see if reset_date should be changed.
259 AND hold_date IS NOT NULL
260 AND reset_date IS NULL
262 if (CRM_Core_DAO
::singleValueQuery($sql, $params)) {
263 //set reset date only if it is not set and if hold date is set
264 $email->on_hold
= FALSE;
265 $email->hold_date
= 'null';
266 $email->reset_date
= date('YmdHis');
271 if ($email->on_hold
) {
272 $email->hold_date
= date('YmdHis');
278 * Generate an array of Domain email addresses.
279 * @return array $domainEmails;
281 public static function domainEmails() {
283 $domainFrom = (array) CRM_Core_OptionGroup
::values('from_email_address');
284 foreach (array_keys($domainFrom) as $k) {
285 $domainEmail = $domainFrom[$k];
286 $domainEmails[$domainEmail] = htmlspecialchars($domainEmail);
288 return $domainEmails;
292 * Build From Email as the combination of all the email ids of the logged in user and
293 * the domain email id
296 * an array of email ids
298 public static function getFromEmail() {
299 // add all configured FROM email addresses
300 $fromEmailValues = self
::domainEmails();
302 if (!Civi
::settings()->get('allow_mail_from_logged_in_contact')) {
303 return $fromEmailValues;
306 $contactFromEmails = [];
307 // add logged in user's active email ids
308 $contactID = CRM_Core_Session
::getLoggedInContactID();
310 $contactEmails = self
::allEmails($contactID);
311 $fromDisplayName = CRM_Core_Session
::singleton()->getLoggedInContactDisplayName();
313 foreach ($contactEmails as $emailId => $emailVal) {
314 $email = trim($emailVal['email']);
315 if (!$email ||
$emailVal['on_hold']) {
318 $fromEmail = "$fromDisplayName <$email>";
319 $fromEmailHtml = htmlspecialchars($fromEmail) . ' ' . $emailVal['locationType'];
321 if (!empty($emailVal['is_primary'])) {
322 $fromEmailHtml .= ' ' . ts('(preferred)');
324 $contactFromEmails[$emailId] = $fromEmailHtml;
327 return CRM_Utils_Array
::crmArrayMerge($contactFromEmails, $fromEmailValues);
333 public static function isMultipleBulkMail() {
334 return Civi
::settings()->get('civimail_multiple_bulk_emails');
338 * Call common delete function.
344 public static function del($id) {
345 return CRM_Contact_BAO_Contact
::deleteObjectWithPrimary('Email', $id);
349 * Get filters for entity reference fields.
353 public static function getEntityRefFilters() {
354 $contactFields = CRM_Contact_BAO_Contact
::getEntityRefFilters();
355 foreach ($contactFields as $index => &$contactField) {
356 if (!empty($contactField['entity'])) {
357 // For now email_getlist can't parse state, country etc.
358 unset($contactFields[$index]);
360 elseif ($contactField['key'] !== 'contact_id') {
361 $contactField['entity'] = 'Contact';
362 $contactField['key'] = 'contact_id.' . $contactField['key'];
365 return $contactFields;