Controller.php 15 KB

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