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