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 +--------------------------------------------------------------------+
13 * This class acts as our base controller class and adds additional
14 * functionality and smarts to the base QFC. Specifically we create
15 * our own action classes and handle the transitions ourselves by
16 * simulating a state machine. We also create direct jump links to any
17 * page that can be used universally.
19 * This concept has been discussed on the PEAR list and the QFC FAQ
20 * goes into a few details. Please check
21 * http://pear.php.net/manual/en/package.html.html-quickform-controller.faq.php
22 * for other useful tips and suggestions
25 * @copyright CiviCRM LLC https://civicrm.org/licensing
28 require_once 'HTML/QuickForm/Controller.php';
29 require_once 'HTML/QuickForm/Action/Direct.php';
32 * Class CRM_Core_Controller
34 class CRM_Core_Controller
extends HTML_QuickForm_Controller
{
37 * The title associated with this controller.
44 * The key associated with this controller.
51 * The name of the session scope where values are stored.
58 * The state machine associated with this controller.
62 protected $_stateMachine;
65 * Is this object being embedded in another object. If
66 * so the display routine needs to not do any work. (The
67 * parent object takes care of the display)
71 protected $_embedded = FALSE;
74 * After entire form execution complete,
75 * do we want to skip control redirection.
76 * Default - It get redirect to user context.
78 * Useful when we run form in non civicrm context
79 * and we need to transfer control back.(eg. drupal)
83 protected $_skipRedirection = FALSE;
86 * Are we in print mode? if so we need to modify the display
87 * functionality to do a minimal display :)
90 * Should match a CRM_Core_Smarty::PRINT_* constant,
91 * or equal 0 if not in print mode
96 * Should we generate a qfKey, true by default
100 public $_generateQFKey = TRUE;
107 public $_QFResponseType = 'html';
110 * Cache the smarty template for efficiency reasons.
112 * @var CRM_Core_Smarty
114 static protected $_template;
117 * Cache the session for efficiency reasons.
119 * @var CRM_Core_Session
121 static protected $_session;
124 * The parent of this form if embedded.
128 protected $_parent = NULL;
131 * The destination if set will override the destination the code wants to send it to.
135 public $_destination = NULL;
138 * The entry url for a top level form or wizard. Typically the URL with a reset=1
139 * used to redirect back to when we land into some session wierdness
143 public $_entryURL = NULL;
146 * All CRM single or multi page pages should inherit from this class.
148 * @param string $title
149 * Descriptive title of the controller.
151 * Whether controller is modal.
153 * @param string $scope
154 * Name of session if we want unique scope, used only by Controller_Simple.
155 * @param bool $addSequence
156 * Should we add a unique sequence number to the end of the key.
157 * @param bool $ignoreKey
158 * Should we not set a qfKey for this controller (for standalone forms).
160 * @throws \CRM_Core_Exception
162 public function __construct(
167 $addSequence = FALSE,
170 // this has to true for multiple tab session fix
173 // let the constructor initialize this, should happen only once
174 if (!isset(self
::$_template)) {
175 self
::$_template = CRM_Core_Smarty
::singleton();
176 self
::$_session = CRM_Core_Session
::singleton();
177 self
::$_template->ensureVariablesAreAssigned(['formTpl']);
180 // lets try to get it from the session and/or the request vars
181 // we do this early on in case there is a fatal error in retrieving the
182 // key and/or session
184 = CRM_Utils_Request
::retrieve('entryURL', 'String', $this);
186 // add a unique validable key to the name
187 $name = CRM_Utils_System
::getClassName($this);
188 if ($name == 'CRM_Core_Controller_Simple' && !empty($scope)) {
189 // use form name if we have, since its a lot better and
190 // definitely different for different forms
193 $name = $name . '_' . $this->key($name, $addSequence, $ignoreKey);
194 $this->_title
= $title;
196 $this->_scope
= $scope;
199 $this->_scope
= CRM_Utils_System
::getClassName($this);
201 $this->_scope
= $this->_scope
. '_' . $this->_key
;
203 // only use the civicrm cache if we have a valid key
204 // else we clash with other users CRM-7059
205 if (!empty($this->_key
)) {
206 CRM_Core_Session
::registerAndRetrieveSessionObjects([
207 "_{$name}_container",
208 ['CiviCRM', $this->_scope
],
212 parent
::__construct($name, $modal);
214 $snippet = $_REQUEST['snippet'] ??
NULL;
217 $this->_print
= CRM_Core_Smarty
::PRINT_PDF
;
219 elseif ($snippet == 4) {
220 // this is used to embed fragments of a form
221 $this->_print
= CRM_Core_Smarty
::PRINT_NOFORM
;
222 self
::$_template->assign('suppressForm', TRUE);
223 $this->_generateQFKey
= FALSE;
225 elseif ($snippet == 5) {
226 // mode deprecated in favor of json
227 // still used by dashlets, probably nothing else
228 $this->_print
= CRM_Core_Smarty
::PRINT_NOFORM
;
230 // Respond with JSON if in AJAX context (also support legacy value '6')
231 elseif (in_array($snippet, [CRM_Core_Smarty
::PRINT_JSON
, 6])) {
232 $this->_print
= CRM_Core_Smarty
::PRINT_JSON
;
233 $this->_QFResponseType
= 'json';
236 $this->_print
= CRM_Core_Smarty
::PRINT_SNIPPET
;
240 // if the request has a reset value, initialize the controller session
241 if (!empty($_GET['reset'])) {
244 // in this case we'll also cache the url as a hidden form variable, this allows us to
245 // redirect in case the session has disappeared on us
246 $this->_entryURL
= CRM_Utils_System
::makeURL(NULL, TRUE, FALSE, NULL, TRUE);
247 // In WordPress Shortcodes the standard entryURL generated via makeURL doesn't generally have id=x&reset=1 included so we add them here
248 // This prevents infinite loops caused when the session has timed out.
249 if (stripos($this->_entryURL
, 'id') === FALSE && (stripos($this->_entryURL
, 'transact') !== FALSE ||
stripos($this->_entryURL
, 'register') !== FALSE)) {
250 $this->_entryURL
.= '&id=' . CRM_Utils_Request
::retrieveValue('id', 'Positive') . '&reset=1';
252 $this->set('entryURL', $this->_entryURL
);
255 // set the key in the session
256 // do this at the end so we have initialized the object
257 // and created the scope etc
258 $this->set('qfKey', $this->_key
);
260 // also retrieve and store destination in session
261 $this->_destination
= CRM_Utils_Request
::retrieve(
262 'civicrmDestination',
271 public function fini() {
272 CRM_Core_BAO_Cache
::storeSessionToCache([
273 "_{$this->_name}_container",
274 ['CiviCRM', $this->_scope
],
279 * @param string $name
280 * @param bool $addSequence
281 * @param bool $ignoreKey
283 * @return mixed|string
285 public function key($name, $addSequence = FALSE, $ignoreKey = FALSE) {
286 $config = CRM_Core_Config
::singleton();
290 (isset($config->keyDisable
) && $config->keyDisable
)
295 // We need a form key. Check _POST first, then _GET.
296 // @todo Note: we currently have to check $_REQUEST, too, since that
297 // is currently overwritten by civicrm_api3_contribution_page_validate.
298 // It's bad form to use $_REQUEST because it's ambiguous; and it's bad form
299 // to change superglobals anyway. If PR
300 // https://github.com/civicrm/civicrm-core/pull/17324
301 // and/or related get merged, then we should remove the REQUEST reference here.
302 $key = $_POST['qfKey'] ??
$_GET['qfKey'] ??
$_REQUEST['qfKey'] ??
NULL;
303 if (!$key && in_array($_SERVER['REQUEST_METHOD'], ['GET', 'HEAD'])) {
304 // Generate a key if this is an initial request without one.
305 // We allow HEAD here because it is used by bots to validate URLs, so if
306 // we issue a 500 server error to them they may think the site is broken.
307 $key = CRM_Core_Key
::get($name, $addSequence);
310 // Other requests that usually change data (POST, but feasibly DELETE,
311 // PUT, PATCH...) always require a valid key.
312 $key = CRM_Core_Key
::validate($key, $name, $addSequence);
325 * Process the request, overrides the default QFC run method
326 * This routine actually checks if the QFC is modal and if it
327 * is the first invalid page, if so it call the requested action
328 * if not, it calls the display action on the first invalid page
329 * avoids the issue of users hitting the back button and getting
332 * This run is basically a composition of the original run and the
337 public function run() {
338 // the names of the action and page should be saved
339 // note that this is split into two, because some versions of
340 // php 5.x core dump on the triple assignment :)
341 $this->_actionName
= $this->getActionName();
342 list($pageName, $action) = $this->_actionName
;
344 if ($this->isModal()) {
345 if (!$this->isValid($pageName)) {
346 $pageName = $this->findInvalid();
351 // note that based on action, control might not come back!!
352 // e.g. if action is a valid JUMP, u basically do a redirect
353 // to the appropriate place
354 $this->wizardHeader($pageName);
355 return $this->_pages
[$pageName]->handle($action);
361 public function validate() {
362 $this->_actionName
= $this->getActionName();
363 list($pageName, $action) = $this->_actionName
;
365 $page = &$this->_pages
[$pageName];
367 $data = &$this->container();
368 $this->applyDefaults($pageName);
369 $page->isFormBuilt() or $page->buildForm();
370 // We use defaults and constants as if they were submitted
371 $data['values'][$pageName] = $page->exportValues();
372 $page->loadValues($data['values'][$pageName]);
373 // Is the page now valid?
374 if (TRUE === ($data['valid'][$pageName] = $page->validate())) {
377 return $page->_errors
;
381 * Helper function to add all the needed default actions.
383 * Note that the framework redefines all of the default QFC actions.
385 * @param string $uploadDirectory to store all the uploaded files
386 * @param array $uploadNames for the various upload buttons (note u can have more than 1 upload)
388 public function addActions($uploadDirectory = NULL, $uploadNames = NULL) {
390 'display' => 'CRM_Core_QuickForm_Action_Display',
391 'next' => 'CRM_Core_QuickForm_Action_Next',
392 'back' => 'CRM_Core_QuickForm_Action_Back',
393 'process' => 'CRM_Core_QuickForm_Action_Process',
394 'cancel' => 'CRM_Core_QuickForm_Action_Cancel',
395 'refresh' => 'CRM_Core_QuickForm_Action_Refresh',
396 'reload' => 'CRM_Core_QuickForm_Action_Reload',
397 'done' => 'CRM_Core_QuickForm_Action_Done',
398 'jump' => 'CRM_Core_QuickForm_Action_Jump',
399 'submit' => 'CRM_Core_QuickForm_Action_Submit',
402 foreach ($names as $name => $classPath) {
403 $action = new $classPath($this->_stateMachine
);
404 $this->addAction($name, $action);
407 $this->addUploadAction($uploadDirectory, $uploadNames);
411 * Getter method for stateMachine.
413 * @return CRM_Core_StateMachine
415 public function getStateMachine() {
416 return $this->_stateMachine
;
420 * Setter method for stateMachine.
422 * @param CRM_Core_StateMachine $stateMachine
424 public function setStateMachine($stateMachine) {
425 $this->_stateMachine
= $stateMachine;
429 * Add pages to the controller. Note that the controller does not really care
430 * the order in which the pages are added
432 * @param CRM_Core_StateMachine $stateMachine
433 * @param \const|int $action the mode in which the state machine is operating
434 * typically this will be add/view/edit
436 public function addPages(&$stateMachine, $action = CRM_Core_Action
::NONE
) {
437 $pages = $stateMachine->getPages();
438 foreach ($pages as $name => $value) {
439 $className = CRM_Utils_Array
::value('className', $value, $name);
440 $title = $value['title'] ??
NULL;
441 $options = $value['options'] ??
NULL;
442 $stateName = CRM_Utils_String
::getClassName($className);
443 if (!empty($value['className'])) {
447 $formName = CRM_Utils_String
::getClassName($name);
450 $ext = CRM_Extension_System
::singleton()->getMapper();
451 if ($ext->isExtensionClass($className)) {
452 require_once $ext->classToPath($className);
455 require_once str_replace('_', DIRECTORY_SEPARATOR
, $className) . '.php';
457 $
$stateName = new $className($stateMachine->find($className), $action, 'post', $formName);
459 $
$stateName->setTitle($title);
462 $
$stateName->setOptions($options);
464 if (property_exists($
$stateName, 'urlPath')) {
465 $
$stateName->urlPath
= explode('/', (string) CRM_Utils_System
::currentPath());
467 $this->addPage($
$stateName);
468 $this->addAction($stateName, new HTML_QuickForm_Action_Direct());
470 //CRM-6342 -we need kill the reference here,
471 //as we have deprecated reference object creation.
477 * QFC does not provide native support to have different 'submit' buttons.
478 * We introduce this notion to QFC by using button specific data. Thus if
479 * we have two submit buttons, we could have one displayed as a button and
480 * the other as an image, both are of type 'submit'.
483 * the name of the button that has been pressed by the user
485 public function getButtonName() {
486 $data = &$this->container();
487 return $data['_qf_button_name'] ??
NULL;
491 * Destroy all the session state of the controller.
493 public function reset() {
494 $this->container(TRUE);
495 self
::$_session->resetScope($this->_scope
);
499 * Virtual function to do any processing of data.
501 * Sometimes it is useful for the controller to actually process data.
502 * This is typically used when we need the controller to figure out
503 * what pages are potentially involved in this wizard. (this is dynamic
504 * and can change based on the arguments
506 public function process() {
510 * Store the variable with the value in the form scope.
512 * @param string|array $name name of the variable or an assoc array of name/value pairs
513 * @param mixed $value
514 * Value of the variable if string.
516 public function set($name, $value = NULL) {
517 self
::$_session->set($name, $value, $this->_scope
);
521 * Get the variable from the form scope.
523 * @param string $name
524 * name of the variable.
528 public function get($name) {
529 return self
::$_session->get($name, $this->_scope
);
533 * Create the header for the wizard from the list of pages.
534 * Store the created header in smarty
536 * @param string $currentPageName
537 * Name of the page being displayed.
541 public function wizardHeader($currentPageName) {
543 $wizard['steps'] = [];
545 foreach ($this->_pages
as $name => $page) {
547 $wizard['steps'][] = [
549 'title' => $page->getTitle(),
550 //'link' => $page->getLink ( ),
554 'stepNumber' => $count,
555 'collapsed' => FALSE,
558 if ($name == $currentPageName) {
559 $wizard['currentStepNumber'] = $count;
560 $wizard['currentStepName'] = $name;
561 $wizard['currentStepTitle'] = $page->getTitle();
565 $wizard['stepCount'] = $count;
567 $this->addWizardStyle($wizard);
569 $this->assign('wizard', $wizard);
574 * @param array $wizard
576 public function addWizardStyle(&$wizard) {
579 'stepPrefixCurrent' => '<i class="crm-i fa-chevron-right" aria-hidden="true"></i> ',
580 'stepPrefixPast' => '<i class="crm-i fa-check" aria-hidden="true"></i> ',
581 'stepPrefixFuture' => ' ',
582 'subStepPrefixCurrent' => ' ',
583 'subStepPrefixPast' => ' ',
584 'subStepPrefixFuture' => ' ',
590 * Assign value to name in template.
593 * @param mixed $value
596 public function assign($var, $value = NULL) {
597 self
::$_template->assign($var, $value);
601 * Assign value to name in template by reference.
604 * @param mixed $value
605 * (reference) value of variable.
607 public function assign_by_ref($var, &$value) {
608 self
::$_template->assign_by_ref($var, $value);
612 * Appends values to template variables.
614 * @param array|string $tpl_var the template variable name(s)
615 * @param mixed $value
616 * The value to append.
619 public function append($tpl_var, $value = NULL, $merge = FALSE) {
620 self
::$_template->append($tpl_var, $value, $merge);
624 * Returns an array containing template variables.
626 * @param string $name
630 public function get_template_vars($name = NULL) {
631 return self
::$_template->get_template_vars($name);
635 * Setter for embedded.
637 * @param bool $embedded
639 public function setEmbedded($embedded) {
640 $this->_embedded
= $embedded;
644 * Getter for embedded.
647 * return the embedded value
649 public function getEmbedded() {
650 return $this->_embedded
;
654 * Setter for skipRedirection.
656 * @param bool $skipRedirection
658 public function setSkipRedirection($skipRedirection) {
659 $this->_skipRedirection
= $skipRedirection;
663 * Getter for skipRedirection.
666 * return the skipRedirection value
668 public function getSkipRedirection() {
669 return $this->_skipRedirection
;
673 * Output HTTP headers for Word document
674 * (note .doc, not the newer .docx format)
678 * @param string|null $fileName
681 public function setWord($fileName = NULL) {
682 CRM_Core_Error
::deprecatedFunctionWarning('no alternative');
684 //Mark as a CSV file.
685 CRM_Utils_System
::setHttpHeader('Content-Type', 'application/vnd.ms-word');
687 //Force a download and name the file using the current timestamp.
689 $fileName = 'Contacts_' . $_SERVER['REQUEST_TIME'] . '.doc';
691 CRM_Utils_System
::setHttpHeader("Content-Disposition", "attachment; filename=Contacts_$fileName");
695 * Output HTTP headers for Excel document
696 * (note .xls, not the newer .xlsx format)
700 * @param string|null $fileName
703 public function setExcel($fileName = NULL) {
704 CRM_Core_Error
::deprecatedFunctionWarning('no alternative');
706 //Mark as an excel file.
707 CRM_Utils_System
::setHttpHeader('Content-Type', 'application/vnd.ms-excel');
709 //Force a download and name the file using the current timestamp.
711 $fileName = 'Contacts_' . $_SERVER['REQUEST_TIME'] . '.xls';
714 CRM_Utils_System
::setHttpHeader("Content-Disposition", "attachment; filename=Contacts_$fileName");
720 * Historically the $print argument has also accepted a string (xls or doc),
721 * but this usage is now deprecated.
723 * @param int|string $print
724 * Should match a CRM_Core_Smarty::PRINT_* constant,
725 * or equal 0 if not in print mode
729 public function setPrint($print) {
730 if ($print === "xls") {
733 elseif ($print === "doc") {
736 $this->_print
= $print;
743 * Value matching a CRM_Core_Smarty::PRINT_* constant,
744 * or 0 if not in print mode
746 public function getPrint() {
747 return $this->_print
;
753 public function getTemplateFile() {
755 if ($this->_print
== CRM_Core_Smarty
::PRINT_PAGE
) {
756 return 'CRM/common/print.tpl';
758 elseif ($this->_print
=== 'xls' ||
$this->_print
=== 'doc') {
759 return 'CRM/Contact/Form/Task/Excel.tpl';
762 return 'CRM/common/snippet.tpl';
766 $config = CRM_Core_Config
::singleton();
767 return 'CRM/common/' . strtolower($config->userFramework
) . '.tpl';
773 * @param $uploadNames
775 public function addUploadAction($uploadDir, $uploadNames) {
776 if (empty($uploadDir)) {
777 $config = CRM_Core_Config
::singleton();
778 $uploadDir = $config->uploadDir
;
781 if (empty($uploadNames)) {
782 $uploadNames = $this->get('uploadNames');
783 if (!empty($uploadNames)) {
784 $uploadNames = array_merge($uploadNames,
785 CRM_Core_BAO_File
::uploadNames()
789 $uploadNames = CRM_Core_BAO_File
::uploadNames();
793 $action = new CRM_Core_QuickForm_Action_Upload($this->_stateMachine
,
797 $this->addAction('upload', $action);
803 public function setParent($parent) {
804 $this->_parent
= $parent;
810 public function getParent() {
811 return $this->_parent
;
817 public function getDestination() {
818 return $this->_destination
;
823 * @param bool $setToReferer
825 public function setDestination($url = NULL, $setToReferer = FALSE) {
828 $url = $_SERVER['HTTP_REFERER'];
831 $config = CRM_Core_Config
::singleton();
832 $url = $config->userFrameworkBaseURL
;
836 $this->_destination
= $url;
837 $this->set('civicrmDestination', $this->_destination
);
843 public function cancelAction() {
844 $actionName = $this->getActionName();
845 list($pageName, $action) = $actionName;
846 return $this->_pages
[$pageName]->cancelAction();
850 * Write a simple fatal error message.
852 * Other controllers can decide to do something else and present the user a better message
853 * and/or redirect to the same page with a reset url
855 public function invalidKey() {
856 self
::invalidKeyCommon();
859 public function invalidKeyCommon() {
860 $msg = ts("We can't load the requested web page. This page requires cookies to be enabled in your browser settings. Please check this setting and enable cookies (if they are not enabled). Then try again. If this error persists, contact the site administrator for assistance.") . '<br /><br />' . ts('Site Administrators: This error may indicate that users are accessing this page using a domain or URL other than the configured Base URL. EXAMPLE: Base URL is http://example.org, but some users are accessing the page via http://www.example.org or a domain alias like http://myotherexample.org.') . '<br /><br />' . ts('Error type: Could not find a valid session key.');
861 throw new CRM_Core_Exception($msg);
865 * Instead of outputting a fatal error message, we'll just redirect
866 * to the entryURL if present
868 public function invalidKeyRedirect() {
869 if ($this->_entryURL
&& $url_parts = parse_url($this->_entryURL
)) {
870 // CRM-16832: Ensure local redirects only.
871 if (!empty($url_parts['path'])) {
872 // Prepend a slash, but don't duplicate it.
873 $redirect_url = '/' . ltrim($url_parts['path'], '/');
874 if (!empty($url_parts['query'])) {
875 $redirect_url .= '?' . $url_parts['query'];
877 CRM_Core_Session
::setStatus(ts('Your browser session has expired and we are unable to complete your form submission. We have returned you to the initial step so you can complete and resubmit the form. If you experience continued difficulties, please contact us for assistance.'));
878 return CRM_Utils_System
::redirect($redirect_url);
881 self
::invalidKeyCommon();