File Source for gform_ctrl.class.php

<?php
// *** Tangra (Application Framework and Tools for PHP)
// $Id$
//
/**
* Contains class GForm_Ctrl
*
* @package tangra_lib
* @subpackage form
*/
/**
*
*/
require_once(TANGRA_MAIN_DIR.'core/vars_manager.class.php');
/**
*
*/
require_once(TANGRA_MAIN_DIR.'form/guardable_form.class.php');
/**
*
*/
require_once(TANGRA_MAIN_DIR.'form/form_ctrl.class.php');
/**
* Controller for Guarder_Form
*
* @package tangra_lib
* @subpackage form
*/
abstract class GForm_Ctrl extends Form_Ctrl {
/**
* Holds Form_Guard object
*
* @var Form_Guard
* @internal
*/
protected $form_guard;
/**
* Holds Vars_Manager object
*
* @var Vars_Manager
* @internal
*/
private $vm;
/**
* Array of processed states ids
*
* @var array
* @internal
*/
private $processed_states;
/**
* Array containing guarded_pairs
*
* @var array
* @internal
*/
private $form_guarded_pairs;
private $permanent_external_params = array();
/**
* Constructor
*
* @param stying $<ystem_name Name of the controller
* @param Vars_Manager $vm Permanent Vars_Manager that will be used. Session of Thread VM
*/
function __construct($system_name, Vars_Manager $vm) {
parent::__construct($system_name);
$this->set_vm($vm);
$this->init_guard_vars();
}
/**
* Prepares form for show
* @internal
*
*/
public function prepare_for_show() {
parent::prepare_for_show();
$form_id = $this->form_guard->new_guard_pair();
$this->set_permanent_external_params($form_id);
}
/**
* Processes submit
*
* @param Web_Context $context
* @return integer Returned value will be Form_Ctrl::SUBMIT_RESULT_ERROR or Form_Ctrl::SUBMIT_RESULT_OK
* @internal
*/
public function process_submit(Web_Context $context) {
$this->form->capture_submit($context);
$form_id = $this->form->get_field_html_value('form_id');
$this->permanent_external_params = $this->retrieve_permanent_external_params($form_id);
if ($this->form_guard->is_fresh_submit($form_id)) {
$ret = $this->handle_fresh_submit($form_id);
} else {
$ret = $this->handle_repeated_submit($form_id);
}
return $ret;
}
/**
* Initialization of guard pairs array and permanent variable
*
* @internal
*/
protected function init_guard_vars() {
$vm = $this->get_vm();
if (!$vm->is_var_registered($this->get_system_name().'_form_guarded_pairs')) {
$vm->register_var($this->get_system_name().'_form_guarded_pairs');
$vm->set_var($this->get_system_name().'_form_guarded_pairs', new Vars_Manager());
}
$this->form_guarded_pairs = &$vm->get_var($this->get_system_name().'_form_guarded_pairs');
if (!$vm->is_var_registered($this->get_system_name().'_processed_states')) {
$vm->register_var($this->get_system_name().'_processed_states');
$vm->set_var($this->get_system_name().'_processed_states', new Vars_Manager());
}
$this->processed_states = &$vm->get_var($this->get_system_name().'_processed_states');
$this->form_guard = new Form_Guard($this->form, $this->form_guarded_pairs);
}
/**
* Called right after submit is accepted.
*
* After a form is submited and basic_check is passed, Form->accept_submit() method is called
* to transfer values from $_POST to fields' values. Immediately after that
* $this->on_accepted_submit() is called in order to give the user a chance to manipulate
* fields values if there is such need (which happens vary rare, only in low level code. If required
* in high level code that may indicate that there is some design flaw).
*
*/
protected function on_accepted_submit() {
}
/**
* Place for your own processing of the validated form data.
*
* Called after form is passed successfully basic_check and also on_good_submit returned true.
* For the sake of example - this method is used in form controllers with object to save the object in the DB.
* Normally is not used in high level code.
*
*/
protected function on_process_submit() {
}
/**
* Sets Vars_Manager that will be used
*
* @param Vars_Manager $vm
* @internal
*/
protected function set_vm(Vars_Manager $vm) {
$this->vm = $vm;
}
/**
* Returns reference to used Vars_Mananger
*
* @return Vars_Manager
* @internal
*/
protected function get_vm() {
return $this->vm;
}
/**
* Returns copy of used Vars_Mananger
*
* @return Vars_Mananger
* @internal
*/
protected function query_vm() {
return $this->vm;
}
/**
* Handles fresh submit of the form.
*
* GForm_Ctrl guarantees that only one submit of the form (with same data, for
* example when visitor to your site clicks multiple times on submit button) will be processed.
* That means, for example, that you will not get multiple rows in your database with same data,
* just because visitor was impatient and pumped same form again and again.
*
*
*
* @param unknown_type $form_id
* @return unknown
* @internal
* @see GForm_Ctrl::handle_repeated_submit()
*/
private function handle_fresh_submit($form_id) {
//it is first submit of this form
$this->form->basic_check();
$this->form->accept_submit();
$this->on_accepted_submit();
if ($this->form->is_form_ok()) {
if ($this->on_good_submit($this->form)) {
$this->on_process_submit();
$this->add_processed_state($form_id, true);
$ret = Form_Ctrl::SUBMIT_RESULT_OK;
} else {
$this->on_bad_submit();
$this->add_processed_state($form_id, false);
$ret = Form_Ctrl::SUBMIT_RESULT_ERROR;
}
} else {
$this->on_bad_submit();
$this->add_processed_state($form_id, false);
$ret = Form_Ctrl::SUBMIT_RESULT_ERROR;
}
return $ret;
}
/**
* Handles repeated submit.
*
* A submit is considered repeated when form_guard detects that same data is submited more than once.
* In this case "same data" means not just the casual form data but also form_id and guard_value
* hidden fields. handle_repeated_submit is smart enough to detect state of the last fresh submit
* (@see GForm_Ctrl::handle_fresh_submit) and to return it.
* Usualy repeated submits happens when impatient visitor to your site clicks submit button on a
* form multile times. Other case is when page that has received submit is refreshed with F5 or
* "Refresh" button of the browser.
* From application point of view repeated submits are just "skipped", i.e. there are no calls of
* on_process_submit
*From visitor's point of view repeated submit is 100% transparent - he/she does not notice any
* additional activities
*
* @param unknown_type $form_id
* @return unknown
* @internal
*/
private function handle_repeated_submit($form_id) {
//second+ submit. Cause: double click on submit button, or refreshed page
if ($this->is_already_processed($form_id)) {
//we have already processed this event, just show them last result
$last_state = $this->get_processed_state($form_id);
if ($last_state) {
$ret = Form_Ctrl::SUBMIT_RESULT_OK;
} else {
$this->form->basic_check();
$this->form->accept_submit();
$this->on_accepted_submit();
if ($this->form->is_form_ok()) {
$this->on_good_submit($this->form);
}
$ret = Form_Ctrl::SUBMIT_RESULT_ERROR;
}
} else {
// we never generated such guarded pair, so we assume
// that this is hackers activity and we are closing application immediatly.
// exception can be changed to more concrete class if you intend to intercept it
throw new Tangra_Exception('Form protection detected abnormal condition.');
}
return $ret;
}
/**
* Checks if this submit is already processed
*
* @param string $form_id
* @return boolean
* @internal
*/
private function is_already_processed($form_id) {
return $this->processed_states->is_var_registered($form_id.'_processed');
}
/**
* Adds new processed state
*
* @param string $form_id
* @param boolean $state
* @internal
*/
private function add_processed_state($form_id, $state) {
$this->processed_states->register_var($form_id.'_processed');
$this->processed_states->set_var($form_id.'_processed', $state);
}
/**
* Returns processed state for submit identified with <var>$form_id</var>
*
* @param string $form_id
* @return boolean
*/
private function get_processed_state($form_id) {
return $this->processed_states->get_var($form_id.'_processed');
}
/**
* Stores external parameters in vars manager.
*
* @param string $form_id
* @internal
*/
private function set_permanent_external_params($form_id) {
$vm = $this->get_vm();
$external_params_var_name = GForm_Ctrl::compose_external_params_var_name();
if (!$vm->is_var_registered($external_params_var_name)) {
$vm->register_var($external_params_var_name);
}
$tmp = array($form_id => $this->permanent_external_params);
$vm->set_var($external_params_var_name, $tmp);
}
/**
* Retrieves stored external parameters
*
* @param string $form_id
* @return array
* @internal
*/
private function retrieve_permanent_external_params($form_id) {
$vm = $this->get_vm();
$external_params_var_name = GForm_Ctrl::compose_external_params_var_name();
$ret = array();
if ($vm->is_var_registered($external_params_var_name)) {
$arr = $vm->get_var($external_params_var_name);
foreach($arr as $form_id_key => $ep_arr) {
if ($form_id_key == $form_id) {
$ret = $ep_arr;
break;
}
}
}
return $ret;
}
/**
* Composes string with external parameters vars name.
*
* @return string
* @internal
*/
private function compose_external_params_var_name() {
return $this->get_system_name().'_external_params';
}
/**
* Sets parameter that will be stored in vars manager and automatically retrieved after each submit
*
* @param string $param_name Parameter name
* @param mixed $param_value Parameter actual value
*/
public function set_permanent_external_param($param_name, $param_value, $do_export = false) {
$this->permanent_external_params[$param_name] = array('value' => $param_value, 'do_export' => $do_export);
}
/**
* Returns value of previosly set external parameter
*
* @param string $param_name Parameter name
* @param boolean $forgiving If true this function will return false if there is no parameter with name $param_name. Otherwise will throw exception. Default is false.
* @return mixed
*/
public function get_permanent_external_param($param_name, $forgiving = false) {
if (!array_key_exists($param_name, $this->permanent_external_params)) {
if (!$forgiving) {
throw new Tangra_Exception('Such param does not exists: '.$param_name);
}
$ret = false;
} else {
$ret = $this->permanent_external_params[$param_name]['value'];
}
return $ret;
}
/**
* Gets TPLE_Exports for the form
*
* @return TPLE_Exports
*/
public function get_tple_exports() {
foreach($this->permanent_external_params as $key => $par) {
if ($par['do_export']) {
$this->export($this->form->get_name().'_pep_'.$key, $par['value']);
}
}
return parent::get_tple_exports();
}
}

Source for file gform_ctrl.class.php