1: <?php
  2: 
  3: /**
  4:  * This file contains the PifaAbstractFormProcessor class.
  5:  *
  6:  * @package    Plugin
  7:  * @subpackage FormAssistant
  8:  * @author     Marcus Gnaß <marcus.gnass@4fb.de>
  9:  * @copyright  four for business AG
 10:  * @link       http://www.4fb.de
 11:  */
 12: 
 13: // assert CONTENIDO framework
 14: defined('CON_FRAMEWORK') || die('Illegal call: Missing framework initialization - request aborted.');
 15: 
 16: /**
 17:  * This form post helper should simplify the implementation of typical form
 18:  * processing.
 19:  * Its main method process() wraps the steps read data from request,
 20:  * validate data and persist data in database. In order to make this approach
 21:  * more customizable three protected "event handler" were defined that can be
 22:  * implemented by a concrete implementation of this class. These allow to
 23:  * preprocess the data read from the request before it's going to be validated
 24:  * and to be postprocessed after it's been persisted into the database.
 25:  *
 26:  * @author Marcus Gnaß <marcus.gnass@4fb.de>
 27:  */
 28: abstract class PifaAbstractFormProcessor {
 29: 
 30:     /**
 31:      * @var PifaAbstractFormModule
 32:      */
 33:     private $_module = NULL;
 34: 
 35:     /**
 36:      * @todo Should be private instead of protected as it can be accessed via getForm()
 37:      * @var PifaForm
 38:      */
 39:     protected $_form = NULL;
 40: 
 41:     /**
 42:      * Create an instance.
 43:      * The processor aggregates the form module and the form.
 44:      * The idform is read from the given modules settings.
 45:      *
 46:      * In former implementations of the processor the modules had no settings
 47:      * and thus no idform. Thats why optionally the idform gan be given
 48:      * explicitly. This shoud be removed when all processors are refactored.
 49:      *
 50:      * @param PifaAbstractFormModule $module
 51:      * @param int $idform
 52:      * @throws PifaException if id of form could not be determined from module
 53:      *         or param
 54:      * @throws PifaException if form could not be loaded
 55:      */
 56:     public function __construct(PifaAbstractFormModule $module = NULL, $idform = NULL) {
 57:         $this->_module = $module;
 58: 
 59:         // for backward compatibility
 60:         if (NULL !== $this->_module) {
 61:             $idform = $this->_module->getSetting('pifaform_idform');
 62:         }
 63: 
 64:         // assure $idform to be an integer
 65:         $idform = cSecurity::toInteger($idform);
 66:         if (0 === $idform) {
 67:             $msg = Pifa::i18n('MISSING_IDFORM');
 68:             throw new PifaException($msg);
 69:         }
 70: 
 71:         // load form
 72:         $this->_form = new PifaForm($idform);
 73:         if (false === $this->_form->isLoaded()) {
 74:             $msg = Pifa::i18n('FORM_LOAD_ERROR');
 75:             throw new PifaException($msg);
 76:         }
 77:     }
 78: 
 79:     /**
 80:      * @return PifaAbstractFormModule
 81:      */
 82:     public function getModule() {
 83:         return $this->_module;
 84:     }
 85: 
 86:     /**
 87:      * @param PifaAbstractFormModule $_module
 88:      */
 89:     public function setModule($_module) {
 90:         $this->_module = $_module;
 91:     }
 92: 
 93:     /**
 94:      * @return PifaForm
 95:      */
 96:     public function getForm() {
 97:         return $this->_form;
 98:     }
 99: 
100:     /**
101:      * @param PifaForm $_form
102:      */
103:     public function setForm($_form) {
104:         $this->_form = $_form;
105:     }
106: 
107:     /**
108:      * Template method to postprocess data that has just been read from request.
109:      * This can be usefull e.g. to remove default values for certain form
110:      * fields.
111:      */
112:     abstract protected function _processReadData();
113: 
114:     /**
115:      * Template method to postprocess data that has just been validated.
116:      * I cannot yet imagine a situatio where this could be useful but added
117:      * this method for completeness' sake.
118:      *
119:      * @throws PifaValidationException
120:      */
121:     abstract protected function _processValidatedData();
122: 
123:     /**
124:      * Template method to postprocess data that has just been stored to
125:      * database.
126:      * This can be usefull e.g. to send form values via email or process them
127:      * in another way.
128:      *
129:      * @throws PifaDatabaseException
130:      */
131:     abstract protected function _processStoredData();
132: 
133:     /**
134:      * Processes a form.
135:      * Therefor the forms values are read from the appropriate request,
136:      * validated and written to database.
137:      * After each step a method is called that allows to postprocess the forms
138:      * data or even the form itself. This postprocessing is optional and can be
139:      * implemented in concrete implementations of this abstratc class
140:      *
141:      * @throws PifaException if there is no form to process
142:      * @throws PifaValidationException if data is invalid
143:      * @throws PifaDatabaseException if data could not be stored
144:      */
145:     public function process() {
146: 
147:         // assert there is a form to process
148:         if (NULL === $this->_form) {
149:             $msg = Pifa::i18n('MISSING_IDFORM');
150:             throw new PifaException($msg);
151:         }
152: 
153:         // perform steps as described in documentation
154: 
155:         $this->_form->fromForm();
156:         $this->_processReadData();
157: 
158:         $this->_form->validate();
159:         $this->_processValidatedData();
160: 
161:         $this->_form->storeData();
162:         $this->_processStoredData();
163:     }
164: }
165: