Controller.php 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517
  1. <?php
  2. /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
  3. /**
  4. * The class representing a Controller of MVC design pattern.
  5. *
  6. * PHP versions 4 and 5
  7. *
  8. * LICENSE: This source file is subject to version 3.01 of the PHP license
  9. * that is available through the world-wide-web at the following URI:
  10. * http://www.php.net/license/3_01.txt If you did not receive a copy of
  11. * the PHP License and are unable to obtain it through the web, please
  12. * send a note to license@php.net so we can mail you a copy immediately.
  13. *
  14. * @category HTML
  15. * @package HTML_QuickForm_Controller
  16. * @author Alexey Borzov <avb@php.net>
  17. * @author Bertrand Mansion <bmansion@mamasam.com>
  18. * @copyright 2003-2009 The PHP Group
  19. * @license http://www.php.net/license/3_01.txt PHP License 3.01
  20. * @version SVN: $Id: Controller.php 289084 2009-10-02 06:53:09Z avb $
  21. * @link http://pear.php.net/package/HTML_QuickForm_Controller
  22. */
  23. /**
  24. * The class representing a page of a multipage form.
  25. */
  26. //require_once 'HTML/QuickForm/Page.php';
  27. /**
  28. * The class representing a Controller of MVC design pattern.
  29. *
  30. * This class keeps track of pages and (default) action handlers for the form,
  31. * it manages keeping the form values in session, setting defaults and
  32. * constants for the form as a whole and getting its submit values.
  33. *
  34. * Generally you don't need to subclass this.
  35. *
  36. * @category HTML
  37. * @package HTML_QuickForm_Controller
  38. * @author Alexey Borzov <avb@php.net>
  39. * @author Bertrand Mansion <bmansion@mamasam.com>
  40. * @version Release: 1.0.10
  41. */
  42. class HTML_QuickForm_Controller
  43. {
  44. /**
  45. * Contains the pages (HTML_QuickForm_Page objects) of the miultipage form
  46. * @var array
  47. */
  48. var $_pages = array();
  49. /**
  50. * Contains the mapping of actions to corresponding HTML_QuickForm_Action objects
  51. * @var array
  52. */
  53. var $_actions = array();
  54. /**
  55. * Name of the form, used to store the values in session
  56. * @var string
  57. */
  58. var $_name;
  59. /**
  60. * Whether the form is modal
  61. * @var bool
  62. */
  63. var $_modal = true;
  64. /**
  65. * The action extracted from HTTP request: array('page', 'action')
  66. * @var array
  67. */
  68. var $_actionName = null;
  69. /**
  70. * Class constructor.
  71. *
  72. * Sets the form name and modal/non-modal behaviuor. Different multipage
  73. * forms should have different names, as they are used to store form
  74. * values in session. Modal forms allow passing to the next page only when
  75. * all of the previous pages are valid.
  76. *
  77. * @access public
  78. * @param string form name
  79. * @param bool whether the form is modal
  80. */
  81. function HTML_QuickForm_Controller($name, $modal = true)
  82. {
  83. $this->_name = $name;
  84. $this->_modal = $modal;
  85. }
  86. /**
  87. * Returns a reference to a session variable containing the form-page
  88. * values and pages' validation status.
  89. *
  90. * This is a "low-level" method, use exportValues() if you want just to
  91. * get the form's values.
  92. *
  93. * @access public
  94. * @param bool If true, then reset the container: clear all default, constant and submitted values
  95. * @return array
  96. */
  97. function &container($reset = false)
  98. {
  99. $name = '_' . $this->_name . '_container';
  100. if (!isset($_SESSION[$name]) || $reset) {
  101. $_SESSION[$name] = array(
  102. 'defaults' => array(),
  103. 'constants' => array(),
  104. 'values' => array(),
  105. 'valid' => array()
  106. );
  107. }
  108. foreach (array_keys($this->_pages) as $pageName) {
  109. if (!isset($_SESSION[$name]['values'][$pageName])) {
  110. $_SESSION[$name]['values'][$pageName] = array();
  111. $_SESSION[$name]['valid'][$pageName] = null;
  112. }
  113. }
  114. return $_SESSION[$name];
  115. }
  116. /**
  117. * Processes the request.
  118. *
  119. * This finds the current page, the current action and passes the action
  120. * to the page's handle() method.
  121. *
  122. * @access public
  123. * @throws PEAR_Error
  124. */
  125. function run()
  126. {
  127. // the names of the action and page should be saved
  128. list($page, $action) = $this->_actionName = $this->getActionName();
  129. return $this->_pages[$page]->handle($action);
  130. }
  131. /**
  132. * Registers a handler for a specific action.
  133. *
  134. * @access public
  135. * @param string name of the action
  136. * @param HTML_QuickForm_Action the handler for the action
  137. */
  138. function addAction($actionName, &$action)
  139. {
  140. $this->_actions[$actionName] =& $action;
  141. }
  142. /**
  143. * Adds a new page to the form
  144. *
  145. * @access public
  146. * @param HTML_QuickForm_Page
  147. */
  148. function addPage(&$page)
  149. {
  150. $page->controller =& $this;
  151. $this->_pages[$page->getAttribute('id')] =& $page;
  152. }
  153. /**
  154. * Returns a page
  155. *
  156. * @access public
  157. * @param string Name of a page
  158. * @return HTML_QuickForm_Page A reference to the page
  159. * @throws PEAR_Error
  160. */
  161. function &getPage($pageName)
  162. {
  163. if (!isset($this->_pages[$pageName])) {
  164. return PEAR::raiseError('HTML_QuickForm_Controller: Unknown page "' . $pageName . '"');
  165. }
  166. return $this->_pages[$pageName];
  167. }
  168. /**
  169. * Handles an action.
  170. *
  171. * This will be called if the page itself does not have a handler
  172. * to a specific action. The method also loads and uses default handlers
  173. * for common actions, if specific ones were not added.
  174. *
  175. * @access public
  176. * @param HTML_QuickForm_Page The page that failed to handle the action
  177. * @param string Name of the action
  178. * @throws PEAR_Error
  179. */
  180. function handle(&$page, $actionName)
  181. {
  182. if (isset($this->_actions[$actionName])) {
  183. return $this->_actions[$actionName]->perform($page, $actionName);
  184. }
  185. switch ($actionName) {
  186. case 'next':
  187. case 'back':
  188. case 'submit':
  189. case 'display':
  190. case 'jump':
  191. $className = 'HTML_QuickForm_Action_' . $actionName;
  192. $this->_actions[$actionName] =& new $className();
  193. return $this->_actions[$actionName]->perform($page, $actionName);
  194. break;
  195. default:
  196. return PEAR::raiseError('HTML_QuickForm_Controller: Unhandled action "' . $actionName . '" in page "' . $page->getAttribute('id') . '"');
  197. } // switch
  198. }
  199. /**
  200. * Checks whether the form is modal.
  201. *
  202. * @access public
  203. * @return bool
  204. */
  205. function isModal()
  206. {
  207. return $this->_modal;
  208. }
  209. /**
  210. * Checks whether the pages of the controller are valid
  211. *
  212. * @access public
  213. * @param string If set, check only the pages before (not including) that page
  214. * @return bool
  215. * @throws PEAR_Error
  216. */
  217. function isValid($pageName = null)
  218. {
  219. $data =& $this->container();
  220. foreach (array_keys($this->_pages) as $key) {
  221. if (isset($pageName) && $pageName == $key) {
  222. return true;
  223. } elseif (!$data['valid'][$key]) {
  224. // We should handle the possible situation when the user has never
  225. // seen a page of a non-modal multipage form
  226. if (!$this->isModal() && null === $data['valid'][$key]) {
  227. $page =& $this->_pages[$key];
  228. // Fix for bug #8687: the unseen page was considered
  229. // submitted, so defaults for checkboxes and multiselects
  230. // were not used. Shouldn't break anything since this flag
  231. // will be reset right below in loadValues().
  232. $page->_flagSubmitted = false;
  233. // Use controller's defaults and constants, if present
  234. $this->applyDefaults($key);
  235. $page->isFormBuilt() or $page->BuildForm();
  236. // We use defaults and constants as if they were submitted
  237. $data['values'][$key] = $page->exportValues();
  238. $page->loadValues($data['values'][$key]);
  239. // Is the page now valid?
  240. if (PEAR::isError($valid = $page->validate())) {
  241. return $valid;
  242. }
  243. $data['valid'][$key] = $valid;
  244. if (true === $valid) {
  245. continue;
  246. }
  247. }
  248. return false;
  249. }
  250. }
  251. return true;
  252. }
  253. /**
  254. * Returns the name of the page before the given.
  255. *
  256. * @access public
  257. * @param string
  258. * @return string
  259. */
  260. function getPrevName($pageName)
  261. {
  262. $prev = null;
  263. foreach (array_keys($this->_pages) as $key) {
  264. if ($key == $pageName) {
  265. return $prev;
  266. }
  267. $prev = $key;
  268. }
  269. }
  270. /**
  271. * Returns the name of the page after the given.
  272. *
  273. * @access public
  274. * @param string
  275. * @return string
  276. */
  277. function getNextName($pageName)
  278. {
  279. $prev = null;
  280. foreach (array_keys($this->_pages) as $key) {
  281. if ($prev == $pageName) {
  282. return $key;
  283. }
  284. $prev = $key;
  285. }
  286. return null;
  287. }
  288. /**
  289. * Finds the (first) invalid page
  290. *
  291. * @access public
  292. * @return string Name of an invalid page
  293. */
  294. function findInvalid()
  295. {
  296. $data =& $this->container();
  297. foreach (array_keys($this->_pages) as $key) {
  298. if (!$data['valid'][$key]) {
  299. return $key;
  300. }
  301. }
  302. return null;
  303. }
  304. /**
  305. * Extracts the names of the current page and the current action from
  306. * HTTP request data.
  307. *
  308. * @access public
  309. * @return array first element is page name, second is action name
  310. */
  311. function getActionName()
  312. {
  313. if (is_array($this->_actionName)) {
  314. return $this->_actionName;
  315. }
  316. $names = array_map('preg_quote', array_keys($this->_pages));
  317. $regex = '/^_qf_(' . implode('|', $names) . ')_(.+?)(_x)?$/';
  318. foreach (array_keys($_REQUEST) as $key) {
  319. if (preg_match($regex, $key, $matches)) {
  320. return array($matches[1], $matches[2]);
  321. }
  322. }
  323. if (isset($_REQUEST['_qf_default'])) {
  324. $matches = explode(':', $_REQUEST['_qf_default'], 2);
  325. if (isset($this->_pages[$matches[0]])) {
  326. return $matches;
  327. }
  328. }
  329. reset($this->_pages);
  330. return array(key($this->_pages), 'display');
  331. }
  332. /**
  333. * Initializes default form values.
  334. *
  335. * @access public
  336. * @param array default values
  337. * @param mixed filter(s) to apply to default values
  338. * @throws PEAR_Error
  339. */
  340. function setDefaults($defaultValues = null, $filter = null)
  341. {
  342. if (is_array($defaultValues)) {
  343. $data =& $this->container();
  344. return $this->_setDefaultsOrConstants($data['defaults'], $defaultValues, $filter);
  345. }
  346. }
  347. /**
  348. * Initializes constant form values.
  349. * These values won't get overridden by POST or GET vars
  350. *
  351. * @access public
  352. * @param array constant values
  353. * @param mixed filter(s) to apply to constant values
  354. * @throws PEAR_Error
  355. */
  356. function setConstants($constantValues = null, $filter = null)
  357. {
  358. if (is_array($constantValues)) {
  359. $data =& $this->container();
  360. return $this->_setDefaultsOrConstants($data['constants'], $constantValues, $filter);
  361. }
  362. }
  363. /**
  364. * Adds new values to defaults or constants array
  365. *
  366. * @access private
  367. * @param array array to add values to (either defaults or constants)
  368. * @param array values to add
  369. * @param mixed filters to apply to new values
  370. * @throws PEAR_Error
  371. */
  372. function _setDefaultsOrConstants(&$values, $newValues, $filter = null)
  373. {
  374. if (isset($filter)) {
  375. if (is_array($filter) && (2 != count($filter) || !is_callable($filter))) {
  376. foreach ($filter as $val) {
  377. if (!is_callable($val)) {
  378. return PEAR::raiseError(null, QUICKFORM_INVALID_FILTER, null, E_USER_WARNING, "Callback function does not exist in QuickForm_Controller::_setDefaultsOrConstants()", 'HTML_QuickForm_Error', true);
  379. } else {
  380. $newValues = $this->_arrayMapRecursive($val, $newValues);
  381. }
  382. }
  383. } elseif (!is_callable($filter)) {
  384. return PEAR::raiseError(null, QUICKFORM_INVALID_FILTER, null, E_USER_WARNING, "Callback function does not exist in QuickForm_Controller::_setDefaultsOrConstants()", 'HTML_QuickForm_Error', true);
  385. } else {
  386. $newValues = $this->_arrayMapRecursive($val, $newValues);
  387. }
  388. }
  389. $values = HTML_QuickForm::arrayMerge($values, $newValues);
  390. }
  391. /**
  392. * Recursively applies the callback function to the value
  393. *
  394. * @param mixed Callback function
  395. * @param mixed Value to process
  396. * @access private
  397. * @return mixed Processed values
  398. */
  399. function _arrayMapRecursive($callback, $value)
  400. {
  401. if (!is_array($value)) {
  402. return call_user_func($callback, $value);
  403. } else {
  404. $map = array();
  405. foreach ($value as $k => $v) {
  406. $map[$k] = $this->_arrayMapRecursive($callback, $v);
  407. }
  408. return $map;
  409. }
  410. }
  411. /**
  412. * Sets the default values for the given page
  413. *
  414. * @access public
  415. * @param string Name of a page
  416. */
  417. function applyDefaults($pageName)
  418. {
  419. $data =& $this->container();
  420. if (!empty($data['defaults'])) {
  421. $this->_pages[$pageName]->setDefaults($data['defaults']);
  422. }
  423. if (!empty($data['constants'])) {
  424. $this->_pages[$pageName]->setConstants($data['constants']);
  425. }
  426. }
  427. /**
  428. * Returns the form's values
  429. *
  430. * @access public
  431. * @param string name of the page, if not set then returns values for all pages
  432. * @return array
  433. */
  434. function exportValues($pageName = null)
  435. {
  436. $data =& $this->container();
  437. $values = array();
  438. if (isset($pageName)) {
  439. $pages = array($pageName);
  440. } else {
  441. $pages = array_keys($data['values']);
  442. }
  443. foreach ($pages as $page) {
  444. // skip elements representing actions
  445. foreach ($data['values'][$page] as $key => $value) {
  446. if (0 !== strpos($key, '_qf_')) {
  447. if (isset($values[$key]) && is_array($value)) {
  448. $values[$key] = HTML_QuickForm::arrayMerge($values[$key], $value);
  449. } else {
  450. $values[$key] = $value;
  451. }
  452. }
  453. }
  454. }
  455. return $values;
  456. }
  457. /**
  458. * Returns the element's value
  459. *
  460. * @access public
  461. * @param string name of the page
  462. * @param string name of the element in the page
  463. * @return mixed value for the element
  464. */
  465. function exportValue($pageName, $elementName)
  466. {
  467. $data =& $this->container();
  468. return isset($data['values'][$pageName][$elementName])? $data['values'][$pageName][$elementName]: null;
  469. }
  470. }
  471. ?>