INFRA-132 comments to end with full stops
[civicrm-core.git] / CRM / Campaign / BAO / Campaign.php
1 <?php
2 /*
3 +--------------------------------------------------------------------+
4 | CiviCRM version 4.6 |
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2014 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
9 | |
10 | CiviCRM is free software; you can copy, modify, and distribute it |
11 | under the terms of the GNU Affero General Public License |
12 | Version 3, 19 November 2007 and the CiviCRM Licensing Exception. |
13 | |
14 | CiviCRM is distributed in the hope that it will be useful, but |
15 | WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
17 | See the GNU Affero General Public License for more details. |
18 | |
19 | You should have received a copy of the GNU Affero General Public |
20 | License and the CiviCRM Licensing Exception along |
21 | with this program; if not, contact CiviCRM LLC |
22 | at info[AT]civicrm[DOT]org. If you have questions about the |
23 | GNU Affero General Public License or the licensing of CiviCRM, |
24 | see the CiviCRM license FAQ at http://civicrm.org/licensing |
25 +--------------------------------------------------------------------+
26 */
27
28 /**
29 *
30 * @package CRM
31 * @copyright CiviCRM LLC (c) 2004-2014
32 * $Id$
33 *
34 */
35 class CRM_Campaign_BAO_Campaign extends CRM_Campaign_DAO_Campaign {
36
37 /**
38 * Takes an associative array and creates a campaign object.
39 *
40 * the function extract all the params it needs to initialize the create a
41 * contact object. the params array could contain additional unused name/value
42 * pairs
43 *
44 * @param array $params
45 * (reference ) an assoc array of name/value pairs.
46 *
47 * @return CRM_Campaign_DAO_Campaign
48 */
49 public static function create(&$params) {
50 if (empty($params)) {
51 return NULL;
52 }
53
54 if (!(CRM_Utils_Array::value('id', $params))) {
55
56 if (!(CRM_Utils_Array::value('created_id', $params))) {
57 $session = CRM_Core_Session::singleton();
58 $params['created_id'] = $session->get('userID');
59 }
60
61 if (!(CRM_Utils_Array::value('created_date', $params))) {
62 $params['created_date'] = date('YmdHis');
63 }
64
65 if (!(CRM_Utils_Array::value('name', $params))) {
66 $params['name'] = CRM_Utils_String::titleToVar($params['title'], 64);
67 }
68 }
69
70 $campaign = new CRM_Campaign_DAO_Campaign();
71 $campaign->copyValues($params);
72 $campaign->save();
73
74 /* Create the campaign group record */
75
76 $groupTableName = CRM_Contact_BAO_Group::getTableName();
77
78 if (isset($params['groups']) && !empty($params['groups']['include']) && is_array($params['groups']['include'])) {
79 foreach ($params['groups']['include'] as $entityId) {
80 $dao = new CRM_Campaign_DAO_CampaignGroup();
81 $dao->campaign_id = $campaign->id;
82 $dao->entity_table = $groupTableName;
83 $dao->entity_id = $entityId;
84 $dao->group_type = 'Include';
85 $dao->save();
86 $dao->free();
87 }
88 }
89
90 //store custom data
91 if (!empty($params['custom']) &&
92 is_array($params['custom'])
93 ) {
94 CRM_Core_BAO_CustomValueTable::store($params['custom'], 'civicrm_campaign', $campaign->id);
95 }
96
97 return $campaign;
98 }
99
100 /**
101 * Delete the campaign.
102 *
103 * @param int $id
104 * Id of the campaign.
105 *
106 * @return bool|mixed
107 */
108 public static function del($id) {
109 if (!$id) {
110 return FALSE;
111 }
112 $dao = new CRM_Campaign_DAO_Campaign();
113 $dao->id = $id;
114 return $dao->delete();
115 }
116
117 /**
118 * Retrieve DB object based on input parameters.
119 *
120 * It also stores all the retrieved values in the default array.
121 *
122 * @param array $params
123 * (reference ) an assoc array of name/value pairs.
124 * @param array $defaults
125 * (reference ) an assoc array to hold the flattened values.
126 *
127 * @return \CRM_Campaign_DAO_Campaign|null
128 */
129 public function retrieve(&$params, &$defaults) {
130 $campaign = new CRM_Campaign_DAO_Campaign();
131
132 $campaign->copyValues($params);
133
134 if ($campaign->find(TRUE)) {
135 CRM_Core_DAO::storeValues($campaign, $defaults);
136 return $campaign;
137 }
138 return NULL;
139 }
140
141 /**
142 * Return the all eligible campaigns w/ cache.
143 *
144 * @param int $includeId
145 * Lets inlcude this campaign by force.
146 * @param int $excludeId
147 * Do not include this campaign.
148 * @param bool $onlyActive
149 * Consider only active campaigns.
150 *
151 * @param bool $onlyCurrent
152 * @param bool $appendDatesToTitle
153 * @param bool $forceAll
154 *
155 * @return mixed
156 * $campaigns a set of campaigns.
157 */
158 public static function getCampaigns(
159 $includeId = NULL,
160 $excludeId = NULL,
161 $onlyActive = TRUE,
162 $onlyCurrent = TRUE,
163 $appendDatesToTitle = FALSE,
164 $forceAll = FALSE
165 ) {
166 static $campaigns;
167 $cacheKey = 0;
168 $cacheKeyParams = array(
169 'includeId',
170 'excludeId',
171 'onlyActive',
172 'onlyCurrent',
173 'appendDatesToTitle',
174 'forceAll',
175 );
176 foreach ($cacheKeyParams as $param) {
177 $cacheParam = $$param;
178 if (!$cacheParam) {
179 $cacheParam = 0;
180 }
181 $cacheKey .= '_' . $cacheParam;
182 }
183
184 if (!isset($campaigns[$cacheKey])) {
185 $where = array('( camp.title IS NOT NULL )');
186 if ($excludeId) {
187 $where[] = "( camp.id != $excludeId )";
188 }
189 if ($onlyActive) {
190 $where[] = '( camp.is_active = 1 )';
191 }
192 if ($onlyCurrent) {
193 $where[] = '( camp.end_date IS NULL OR camp.end_date >= NOW() )';
194 }
195 $whereClause = implode(' AND ', $where);
196 if ($includeId) {
197 $whereClause .= " OR ( camp.id = $includeId )";
198 }
199
200 //lets force all.
201 if ($forceAll) {
202 $whereClause = '( 1 )';
203 }
204
205 $query = "
206 SELECT camp.id,
207 camp.title,
208 camp.start_date,
209 camp.end_date
210 FROM civicrm_campaign camp
211 WHERE {$whereClause}
212 Order By camp.title";
213
214 $campaign = CRM_Core_DAO::executeQuery($query);
215 $campaigns[$cacheKey] = array();
216 $config = CRM_Core_Config::singleton();
217
218 while ($campaign->fetch()) {
219 $title = $campaign->title;
220 if ($appendDatesToTitle) {
221 $dates = array();
222 foreach (array('start_date', 'end_date') as $date) {
223 if ($campaign->$date) {
224 $dates[] = CRM_Utils_Date::customFormat($campaign->$date, $config->dateformatFull);
225 }
226 }
227 if (!empty($dates)) {
228 $title .= ' (' . implode('-', $dates) . ')';
229 }
230 }
231 $campaigns[$cacheKey][$campaign->id] = $title;
232 }
233 }
234
235 return $campaigns[$cacheKey];
236 }
237
238 /**
239 * Wrapper to self::getCampaigns( )
240 * w/ permissions and component check.
241 *
242 * @param int $includeId
243 * @param int $excludeId
244 * @param bool $onlyActive
245 * @param bool $onlyCurrent
246 * @param bool $appendDatesToTitle
247 * @param bool $forceAll
248 * @param bool $doCheckForComponent
249 * @param bool $doCheckForPermissions
250 *
251 * @return mixed
252 */
253 public static function getPermissionedCampaigns(
254 $includeId = NULL,
255 $excludeId = NULL,
256 $onlyActive = TRUE,
257 $onlyCurrent = TRUE,
258 $appendDatesToTitle = FALSE,
259 $forceAll = FALSE,
260 $doCheckForComponent = TRUE,
261 $doCheckForPermissions = TRUE
262 ) {
263 $cacheKey = 0;
264 $cachekeyParams = array(
265 'includeId',
266 'excludeId',
267 'onlyActive',
268 'onlyCurrent',
269 'appendDatesToTitle',
270 'doCheckForComponent',
271 'doCheckForPermissions',
272 'forceAll',
273 );
274 foreach ($cachekeyParams as $param) {
275 $cacheKeyParam = $$param;
276 if (!$cacheKeyParam) {
277 $cacheKeyParam = 0;
278 }
279 $cacheKey .= '_' . $cacheKeyParam;
280 }
281
282 static $validCampaigns;
283 if (!isset($validCampaigns[$cacheKey])) {
284 $isValid = TRUE;
285 $campaigns = array(
286 'campaigns' => array(),
287 'hasAccessCampaign' => FALSE,
288 'isCampaignEnabled' => FALSE,
289 );
290
291 //do check for component.
292 if ($doCheckForComponent) {
293 $campaigns['isCampaignEnabled'] = $isValid = self::isCampaignEnable();
294 }
295
296 //do check for permissions.
297 if ($doCheckForPermissions) {
298 $campaigns['hasAccessCampaign'] = $isValid = self::accessCampaign();
299 }
300
301 //finally retrieve campaigns from db.
302 if ($isValid) {
303 $campaigns['campaigns'] = self::getCampaigns($includeId,
304 $excludeId,
305 $onlyActive,
306 $onlyCurrent,
307 $appendDatesToTitle,
308 $forceAll
309 );
310 }
311
312 //store in cache.
313 $validCampaigns[$cacheKey] = $campaigns;
314 }
315
316 return $validCampaigns[$cacheKey];
317 }
318
319 /**
320 * Is CiviCampaign enabled.
321 * @return bool
322 */
323 public static function isCampaignEnable() {
324 static $isEnable = NULL;
325
326 if (!isset($isEnable)) {
327 $isEnable = FALSE;
328 $config = CRM_Core_Config::singleton();
329 if (in_array('CiviCampaign', $config->enableComponents)) {
330 $isEnable = TRUE;
331 }
332 }
333
334 return $isEnable;
335 }
336
337 /**
338 * Retrieve campaigns for dashboard.
339 *
340 */
341 public static function getCampaignSummary($params = array(), $onlyCount = FALSE) {
342 $campaigns = array();
343
344 //build the limit and order clause.
345 $limitClause = $orderByClause = $lookupTableJoins = NULL;
346 if (!$onlyCount) {
347 $sortParams = array(
348 'sort' => 'start_date',
349 'offset' => 0,
350 'rowCount' => 10,
351 'sortOrder' => 'desc',
352 );
353 foreach ($sortParams as $name => $default) {
354 if (!empty($params[$name])) {
355 $sortParams[$name] = $params[$name];
356 }
357 }
358
359 //need to lookup tables.
360 $orderOnCampaignTable = TRUE;
361 if ($sortParams['sort'] == 'status') {
362 $orderOnCampaignTable = FALSE;
363 $lookupTableJoins = "
364 LEFT JOIN civicrm_option_value status ON ( status.value = campaign.status_id OR campaign.status_id IS NULL )
365 INNER JOIN civicrm_option_group grp ON ( status.option_group_id = grp.id AND grp.name = 'campaign_status' )";
366 $orderByClause = "ORDER BY status.label {$sortParams['sortOrder']}";
367 }
368 elseif ($sortParams['sort'] == 'campaign_type') {
369 $orderOnCampaignTable = FALSE;
370 $lookupTableJoins = "
371 LEFT JOIN civicrm_option_value campaign_type ON ( campaign_type.value = campaign.campaign_type_id
372 OR campaign.campaign_type_id IS NULL )
373 INNER JOIN civicrm_option_group grp ON ( campaign_type.option_group_id = grp.id AND grp.name = 'campaign_type' )";
374 $orderByClause = "ORDER BY campaign_type.label {$sortParams['sortOrder']}";
375 }
376 elseif ($sortParams['sort'] == 'isActive') {
377 $sortParams['sort'] = 'is_active';
378 }
379 if ($orderOnCampaignTable) {
380 $orderByClause = "ORDER BY campaign.{$sortParams['sort']} {$sortParams['sortOrder']}";
381 }
382 $limitClause = "LIMIT {$sortParams['offset']}, {$sortParams['rowCount']}";
383 }
384
385 //build the where clause.
386 $queryParams = $where = array();
387 if (!empty($params['id'])) {
388 $where[] = "( campaign.id = %1 )";
389 $queryParams[1] = array($params['id'], 'Positive');
390 }
391 if (!empty($params['name'])) {
392 $where[] = "( campaign.name LIKE %2 )";
393 $queryParams[2] = array('%' . trim($params['name']) . '%', 'String');
394 }
395 if (!empty($params['title'])) {
396 $where[] = "( campaign.title LIKE %3 )";
397 $queryParams[3] = array('%' . trim($params['title']) . '%', 'String');
398 }
399 if (!empty($params['start_date'])) {
400 $startDate = CRM_Utils_Date::processDate($params['start_date']);
401 $where[] = "( campaign.start_date >= %4 OR campaign.start_date IS NULL )";
402 $queryParams[4] = array($startDate, 'String');
403 }
404 if (!empty($params['end_date'])) {
405 $endDate = CRM_Utils_Date::processDate($params['end_date'], '235959');
406 $where[] = "( campaign.end_date <= %5 OR campaign.end_date IS NULL )";
407 $queryParams[5] = array($endDate, 'String');
408 }
409 if (!empty($params['description'])) {
410 $where[] = "( campaign.description LIKE %6 )";
411 $queryParams[6] = array('%' . trim($params['description']) . '%', 'String');
412 }
413 if (!empty($params['campaign_type_id'])) {
414 $typeId = $params['campaign_type_id'];
415 if (is_array($params['campaign_type_id'])) {
416 $typeId = implode(' , ', $params['campaign_type_id']);
417 }
418 $where[] = "( campaign.campaign_type_id IN ( {$typeId} ) )";
419 }
420 if (!empty($params['status_id'])) {
421 $statusId = $params['status_id'];
422 if (is_array($params['status_id'])) {
423 $statusId = implode(' , ', $params['status_id']);
424 }
425 $where[] = "( campaign.status_id IN ( {$statusId} ) )";
426 }
427 if (array_key_exists('is_active', $params)) {
428 $active = "( campaign.is_active = 1 )";
429 if (!empty($params['is_active'])) {
430 $active = "( campaign.is_active = 0 OR campaign.is_active IS NULL )";
431 }
432 $where[] = $active;
433 }
434 $whereClause = NULL;
435 if (!empty($where)) {
436 $whereClause = ' WHERE ' . implode(" \nAND ", $where);
437 }
438
439 $properties = array(
440 'id',
441 'name',
442 'title',
443 'start_date',
444 'end_date',
445 'status_id',
446 'is_active',
447 'description',
448 'campaign_type_id',
449 );
450
451 $selectClause = '
452 SELECT campaign.id as id,
453 campaign.name as name,
454 campaign.title as title,
455 campaign.is_active as is_active,
456 campaign.status_id as status_id,
457 campaign.end_date as end_date,
458 campaign.start_date as start_date,
459 campaign.description as description,
460 campaign.campaign_type_id as campaign_type_id';
461 if ($onlyCount) {
462 $selectClause = 'SELECT COUNT(*)';
463 }
464 $fromClause = 'FROM civicrm_campaign campaign';
465
466 $query = "{$selectClause} {$fromClause} {$lookupTableJoins} {$whereClause} {$orderByClause} {$limitClause}";
467
468 //in case of only count.
469 if ($onlyCount) {
470 return (int) CRM_Core_DAO::singleValueQuery($query, $queryParams);
471 }
472
473 $campaign = CRM_Core_DAO::executeQuery($query, $queryParams);
474 while ($campaign->fetch()) {
475 foreach ($properties as $property) {
476 $campaigns[$campaign->id][$property] = $campaign->$property;
477 }
478 }
479
480 return $campaigns;
481 }
482
483 /**
484 * Get the campaign count.
485 *
486 */
487 public static function getCampaignCount() {
488 return (int) CRM_Core_DAO::singleValueQuery('SELECT COUNT(*) FROM civicrm_campaign');
489 }
490
491 /**
492 * Get Campaigns groups.
493 *
494 * @param int $campaignId
495 * Campaign id.
496 *
497 * @return array
498 */
499 public static function getCampaignGroups($campaignId) {
500 static $campaignGroups;
501 if (!$campaignId) {
502 return array();
503 }
504
505 if (!isset($campaignGroups[$campaignId])) {
506 $campaignGroups[$campaignId] = array();
507
508 $query = "
509 SELECT grp.title, grp.id
510 FROM civicrm_campaign_group campgrp
511 INNER JOIN civicrm_group grp ON ( grp.id = campgrp.entity_id )
512 WHERE campgrp.group_type = 'Include'
513 AND campgrp.entity_table = 'civicrm_group'
514 AND campgrp.campaign_id = %1";
515
516 $groups = CRM_Core_DAO::executeQuery($query, array(1 => array($campaignId, 'Positive')));
517 while ($groups->fetch()) {
518 $campaignGroups[$campaignId][$groups->id] = $groups->title;
519 }
520 }
521
522 return $campaignGroups[$campaignId];
523 }
524
525 /**
526 * Update the is_active flag in the db.
527 *
528 * @param int $id
529 * Id of the database record.
530 * @param bool $is_active
531 * Value we want to set the is_active field.
532 *
533 * @return CRM_Campaign_DAO_Campaign|null
534 * DAO object on sucess, null otherwise
535 */
536 public static function setIsActive($id, $is_active) {
537 return CRM_Core_DAO::setFieldValue('CRM_Campaign_DAO_Campaign', $id, 'is_active', $is_active);
538 }
539
540 /**
541 * @return bool
542 */
543 public static function accessCampaign() {
544 static $allow = NULL;
545
546 if (!isset($allow)) {
547 $allow = FALSE;
548 if (CRM_Core_Permission::check('manage campaign') ||
549 CRM_Core_Permission::check('administer CiviCampaign')
550 ) {
551 $allow = TRUE;
552 }
553 }
554
555 return $allow;
556 }
557
558 /**
559 * Add select element for campaign
560 * and assign needful info to templates.
561 *
562 * @param CRM_Core_Form $form
563 * @param int $connectedCampaignId
564 */
565 public static function addCampaign(&$form, $connectedCampaignId = NULL) {
566 //some forms do set default and freeze.
567 $appendDates = TRUE;
568 if ($form->get('action') & CRM_Core_Action::VIEW) {
569 $appendDates = FALSE;
570 }
571
572 $campaignDetails = self::getPermissionedCampaigns($connectedCampaignId, NULL, TRUE, TRUE, $appendDates);
573 $fields = array('campaigns', 'hasAccessCampaign', 'isCampaignEnabled');
574 foreach ($fields as $fld) {
575 $$fld = CRM_Utils_Array::value($fld, $campaignDetails);
576 }
577
578 //lets see do we have past campaigns.
579 $hasPastCampaigns = FALSE;
580 $allActiveCampaigns = CRM_Campaign_BAO_Campaign::getCampaigns(NULL, NULL, TRUE, FALSE);
581 if (count($allActiveCampaigns) > count($campaigns)) {
582 $hasPastCampaigns = TRUE;
583 }
584 $hasCampaigns = FALSE;
585 if (!empty($campaigns)) {
586 $hasCampaigns = TRUE;
587 }
588 if ($hasPastCampaigns) {
589 $hasCampaigns = TRUE;
590 $form->add('hidden', 'included_past_campaigns');
591 }
592
593 $showAddCampaign = FALSE;
594 $alreadyIncludedPastCampaigns = FALSE;
595 if ($connectedCampaignId || ($isCampaignEnabled && $hasAccessCampaign)) {
596 $showAddCampaign = TRUE;
597 //lets add past campaigns as options to quick-form element.
598 if ($hasPastCampaigns && $form->getElementValue('included_past_campaigns')) {
599 $campaigns = $allActiveCampaigns;
600 $alreadyIncludedPastCampaigns = TRUE;
601 }
602 $campaign = &$form->add('select',
603 'campaign_id',
604 ts('Campaign'),
605 array('' => ts('- select -')) + $campaigns,
606 FALSE,
607 array('class' => 'crm-select2')
608 );
609 //lets freeze when user does not has access or campaign is disabled.
610 if (!$isCampaignEnabled || !$hasAccessCampaign) {
611 $campaign->freeze();
612 }
613 }
614
615 $addCampaignURL = NULL;
616 if (empty($campaigns) && $hasAccessCampaign && $isCampaignEnabled) {
617 $addCampaignURL = CRM_Utils_System::url('civicrm/campaign/add', 'reset=1');
618 }
619
620 $includePastCampaignURL = NULL;
621 if ($hasPastCampaigns && $isCampaignEnabled && $hasAccessCampaign) {
622 $includePastCampaignURL = CRM_Utils_System::url('civicrm/ajax/rest',
623 'className=CRM_Campaign_Page_AJAX&fnName=allActiveCampaigns',
624 FALSE, NULL, FALSE
625 );
626 }
627
628 //carry this info to templates.
629 $infoFields = array(
630 'hasCampaigns',
631 'addCampaignURL',
632 'showAddCampaign',
633 'hasPastCampaigns',
634 'hasAccessCampaign',
635 'isCampaignEnabled',
636 'includePastCampaignURL',
637 'alreadyIncludedPastCampaigns',
638 );
639 foreach ($infoFields as $fld) {
640 $campaignInfo[$fld] = $$fld;
641 }
642 $form->assign('campaignInfo', $campaignInfo);
643 }
644
645 /**
646 * Add campaign in component search.
647 * and assign needful info to templates.
648 *
649 * @param CRM_Core_Form $form
650 * @param string $elementName
651 */
652 public static function addCampaignInComponentSearch(&$form, $elementName = 'campaign_id') {
653 $campaignInfo = array();
654 $campaignDetails = self::getPermissionedCampaigns(NULL, NULL, FALSE, FALSE, FALSE, TRUE);
655 $fields = array('campaigns', 'hasAccessCampaign', 'isCampaignEnabled');
656 foreach ($fields as $fld) {
657 $$fld = CRM_Utils_Array::value($fld, $campaignDetails);
658 }
659 $showCampaignInSearch = FALSE;
660 if ($isCampaignEnabled && $hasAccessCampaign && !empty($campaigns)) {
661 //get the current campaign only.
662 $currentCampaigns = self::getCampaigns(NULL, NULL, FALSE);
663 $pastCampaigns = array_diff($campaigns, $currentCampaigns);
664 $allCampaigns = array();
665 if (!empty($currentCampaigns)) {
666 $allCampaigns = array('crm_optgroup_current_campaign' => ts('Current Campaigns')) + $currentCampaigns;
667 }
668 if (!empty($pastCampaigns)) {
669 $allCampaigns += array('crm_optgroup_past_campaign' => ts('Past Campaigns')) + $pastCampaigns;
670 }
671
672 $showCampaignInSearch = TRUE;
673 $form->add('select', $elementName, ts('Campaigns'), $allCampaigns, FALSE,
674 array('id' => 'campaigns', 'multiple' => 'multiple', 'class' => 'crm-select2')
675 );
676 }
677 $infoFields = array(
678 'elementName',
679 'hasAccessCampaign',
680 'isCampaignEnabled',
681 'showCampaignInSearch',
682 );
683 foreach ($infoFields as $fld) {
684 $campaignInfo[$fld] = $$fld;
685 }
686 $form->assign('campaignInfo', $campaignInfo);
687 }
688
689 }