1 <?php
  2 /**
  3  * Form.php
  4  *
  5  * @author  Elvyrra SAS
  6  * @license http://rem.mit-license.org/ MIT
  7  */
  8 
  9 namespace Hawk;
 10 
 11 /**
 12  * This class is used to generate, display and treat forms.
 13  *
 14  * @package Form
 15  */
 16 class Form{
 17     use Utils;
 18 
 19     const NO_EXIT = false;
 20     const EXIT_JSON = true;
 21 
 22     const VIEWS_DIR = 'form/';
 23 
 24     // Submission status
 25     const STATUS_SUCCESS = 'success';
 26     const STATUS_ERROR = 'error';
 27     const STATUS_CHECK_ERROR = 'check-error';
 28 
 29     // Submission return codes
 30     const HTTP_CODE_SUCCESS = 200; // OK
 31     const HTTP_CODE_CHECK_ERROR = 412; // Data format error
 32     const HTTP_CODE_ERROR = 424; // Treatment error
 33 
 34     // Actions
 35     const ACTION_REGISTER = 'register';
 36     const ACTION_DELETE = 'delete';
 37 
 38     // Default model for form
 39     const DEFAULT_MODEL = "GenericModel";
 40 
 41 
 42     /**
 43      * The submit method (Default : POST)
 44      */
 45     public $method = 'post',
 46 
 47     /**
 48      * The form name
 49      *
 50      * @var string
 51      */
 52     $name = '',
 53 
 54     /**
 55      * The form id
 56      *
 57      * @var string
 58      */
 59     $id = '',
 60 
 61     /**
 62      * The model class used for display and database treatment
 63      *
 64      * @var string
 65      */
 66     $model = self::DEFAULT_MODEL,
 67 
 68     /**
 69      * The object treated by the form
 70      *
 71      * @var Object
 72      */
 73     $object,
 74 
 75     /**
 76      * The width of the input labels (if defined, overrides the default label width defined in the theme)
 77      *
 78      * @var string
 79      */
 80     $labelWidth = '',
 81 
 82     /**
 83      * The submission status.
 84      * This variable can be used if you want to know the treatment status before executing other instructions
 85      *
 86      * @var string
 87      */
 88     $status = null,
 89 
 90     /**
 91      * The number of columns to display the form. Each fieldset will be displayed on a column.
 92      * For example, if you define 6 fieldsets in your form, and select 3 for this property,
 93      * the form will be displayed on 2 lines, with 3 fieldsets by line.
 94      *
 95      * @var int
 96      */
 97     $columns = 1,
 98 
 99 
100     /**
101      * This property can be set if you want to apply a css class to the form
102      *
103      * @var string
104      */
105     $class = '',
106 
107 
108     /**
109      * Defines if the form can autocompleted (Default true)
110      *
111      * @var bool
112      */
113     $autocomplete = true,
114 
115 
116     /**
117      * The form fieldsets
118      *
119      * @var array
120      */
121     $fieldsets = array(),
122 
123     /**
124      * The form inputs
125      *
126      * @var array
127      */
128     $inputs = array(),
129 
130     /**
131      * Defines if the form do an AJAX uplaod
132      *
133      * @var bool
134      */
135     $upload = false,
136 
137     /**
138      * If set to true, no return message will be displayed when the form is submitted
139      *
140      * @var bool
141      */
142     $nomessage = false,
143 
144 
145     /**
146      * Defines the form action. Default value is the current URL
147      *
148      * @var string
149      */
150     $action = '',
151 
152     /**
153      * The data returned by the form
154      *
155      * @var array
156      */
157     $returns = array(),
158 
159     /**
160      * The form errors
161      *
162      * @var array
163      */
164     $errors = array(),
165 
166     /**
167      * The reference to get the object in the database and update it. This property must be displayed as :
168      * array(
169      *     'field' => 'value',
170      *     'field2' => 'value2'
171      * )
172      *
173      * @var array
174      */
175     $reference = array();
176 
177     /**
178      * The database example, generated from the reference, to find the object to display and treat in the database
179      *
180      * @var DBExample
181      */
182     private $example = null,
183 
184     /**
185      * The action that is performed on form submission
186      *
187      * @var sting
188      */
189     $dbaction = self::ACTION_REGISTER;
190 
191     /**
192      * Form instances
193      *
194      * @var array
195      */
196     private static $instances = array();
197 
198 
199     /**
200      * Constructor
201      *
202      * @param array $param The form parameters
203      */
204     public function __construct($param = array()){
205         /*
206         * Default values
207         */
208         $this->action = App::request()->getUri();
209 
210         // Get the parameters of the instance
211         $data = $param;
212         unset($data['fieldsets']);
213         $this->setParam($data);
214 
215         if(!$this->name) {
216             $this->name = $this->id;
217         }
218 
219         if(!in_array($this->columns, array(1,2,3,4,6,12))) {
220             $this->columns = 1;
221         }
222 
223         if(!class_exists($this->model)) {
224             $trace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2);
225             $reflection = new \ReflectionClass($trace[1]['class']);
226             $this->model = $reflection->getNamespaceName() . '\\' . $this->model;
227         }
228 
229         if(!isset($data['object'])) {
230             if(isset($this->model) && !empty($this->reference)) {
231                 $model = $this->model;
232                 $this->example = new DBExample($this->reference);
233                 $this->object = $model::getByExample($this->example);
234             }
235             else{
236                 $this->object = null;
237             }
238         }
239         else{
240             $this->model = get_class($this->object);
241             $model = $this->model;
242             $id = $model::getPrimaryColumn();
243             $this->reference = array($id => $this->object->$id);
244         }
245 
246         $this->new = $this->object === null;
247 
248 
249         // Get the fields in the "fields" instance property, and add the default values for the fieldsets and fields
250         $this->fieldsets = array();
251         if(!empty($param['fieldsets'])) {
252             foreach($param['fieldsets'] as $name => &$fieldset){
253                 $inputs = array();
254                 $params = array();
255 
256                 $this->addFieldset(new FormFieldset($this, $name));
257 
258                 foreach($fieldset as $key => &$field){
259                     if($field instanceof FormInput) {
260                         $this->addInput($field, $name);
261                         if($field instanceof FileInput) {
262                             $this->upload = true;
263                         }
264                     }
265                     else {
266                         $this->fieldsets[$name]->setParam($key, $field);
267                     }
268                 }
269             }
270         }
271         else{
272             $this->addFieldset(new FormFieldset($this, 'form'));
273             foreach($this->inputs as &$field){
274                 if($field instanceof FormInput) {
275                     $this->addInput($field, 'form');
276 
277                     if($field instanceof FileInput) {
278                         $this->upload = true;
279                     }
280                 }
281             }
282         }
283 
284         // get the data of the form to display or register
285         $this->reload();
286 
287         self::$instances[$this->id] = $this;
288 
289 
290         $event = new Event(
291             'form.' . $this->id . '.instanciated', array(
292             'form' => $this
293             )
294         );
295         $event->trigger();
296     }
297 
298 
299     /**
300      * Get a form instance
301      *
302      * @param string $id the form id to get
303      *
304      * @static
305      *
306      * @return Form The form instance
307      */
308     public static function getInstance($id){
309         if(isset(self::$instances[$id])) {
310             return self::$instances[$id];
311         }
312         else{
313             return null;
314         }
315     }
316 
317     /**
318      * Set form parameters
319      *
320      * @param mixed $param The parameter name to set.
321      *                     If this parameter is an array, then this function will set all parameters defined
322      *                     by the keys of this array with the associated value
323      * @param mixed $value The value to apply to the parameter
324      */
325     public function setParam($param, $value = null){
326         if(is_array($param)) {
327             $this->map($param);
328         }
329         else{
330             $this->$param = $value;
331         }
332     }
333 
334 
335     /**
336      * Reload the form data
337      */
338     public function reload(){
339         // Set default value
340         $data = array();
341         foreach($this->inputs as $name => $field){
342             if(isset($field->default)) {
343                 $data[$name] = $field->default;
344             }
345 
346             if(!$this->submitted() && isset($this->object->$name)) {
347                 $data[$name] = $this->object->$name;
348             }
349         }
350 
351         if($this->submitted()) {
352             $data = strtolower($this->method) == 'get' ? App::request()->getParams() : App::request()->getBody();
353         }
354 
355         // Set the value in all inputs instances
356         $this->setData($data);
357     }
358 
359 
360     /**
361      * Set the values for field
362      *
363      * @param array  $data   The data to set, where the keys are the names of the field,
364      *                       and the array values, the values to affect
365      * @param string $prefix A prefix to apply on the field name,
366      *                       if it is defined as an array (used internally to the class)
367      */
368     public function setData($data, $prefix = '') {
369         foreach($data as $key => $value) {
370             $field = $prefix ? $prefix."[$key]" : $key;
371             if(isset($this->inputs[$field])) {
372                 $this->inputs[$field]->setValue($value);
373             }
374             elseif(is_array($value)) {
375                 $this->setData($value, $field);
376             }
377 
378         }
379     }
380 
381 
382     /**
383      * Get data of the form
384      *
385      * @param string $name If set, the function will return the value of the field,
386      *                     else it will return an array containing all field values
387      *
388      * @return mixed If $name is set, the function will return the value of the field,
389      *               else it will return an array containing all field values
390      */
391     public function getData($name = null){
392         if($name) {
393             return $this->inputs[$name]->value;
394         }
395         else{
396             $result = array();
397             foreach($this->inputs as $name => $field){
398                 $result[$name] = $field->value;
399             }
400 
401             return $result;
402         }
403     }
404 
405 
406     /**
407      * Add a fieldset to the form
408      *
409      * @param FormFieldset $fieldset The fieldset to add to the form
410      */
411     public function addFieldset(FormFieldset $fieldset){
412         $this->fieldsets[$fieldset->name] = $fieldset;
413     }
414 
415     /**
416      * Add an input to the form
417      *
418      * @param FormInput $input    The input to insert in the form
419      * @param string    $fieldset (optionnal) The fieldset where to insert the input.
420      *                            If not set, the input will be just included in $form->inputs, out of any fieldset
421      */
422     public function addInput(FormInput $input, $fieldset = ''){
423         if($input::INDEPENDANT) {
424             // This field is independant from the database
425             $input->independant = true;
426         }
427 
428         $labelWidth = $this->labelWidth;
429         if(isset($this->fieldsets[$fieldset]->labelWidth)) {
430             $labelWidth = $this->fieldsets[$fieldset]->labelWidth;
431         }
432         if(isset($input->labelWidth)) {
433             $labelWidth = $input->labelWidth;
434         }
435         $input->labelWidth = $labelWidth;
436 
437         $this->inputs[$input->name] = &$input;
438 
439         if($fieldset) {
440             $this->fieldsets[$fieldset]->inputs[$input->name] = $input;
441         }
442     }
443 
444 
445     /**
446      * Defines if the form has been submitted, and if so, return the action to perform (submitted or delete)
447      *
448      * @return mixed If the form is not submitted, this function will return FALSE.
449      *               Else, the function will return 'register' or 'delete', depending on the user action
450      */
451     public function submitted(){
452         if(App::request()->getMethod() == "delete") {
453             return self::ACTION_DELETE;
454         }
455 
456         $action = $this->method == 'get' ? App::request()->getParams('_submittedForm') : App::request()->getBody('_submittedForm');
457         return $action ? $action : false;
458     }
459 
460 
461     /**
462      * This method is used when you define your own template for displaying the form content.
463      * It will wrap the form content with the <form> tag, and all the parameters defined for this form
464      *
465      * @param string $content The form content to wrap
466      *
467      * @return string The HTML result
468      */
469     public function wrap($content){
470         App::logger()->info('display form ' . $this->id);
471 
472         // Filter input data that can be sent to the client
473         $clientVars = array(
474             'id',
475             'type',
476             'name',
477             'required',
478             'emptyValue',
479             'pattern',
480             'minimum',
481             'maximum',
482             'compare',
483             'errorAt'
484         );
485         $clientInputs = array();
486         foreach($this->inputs as $field){
487             $clientInputs[$field->name] = array_filter(
488                 get_object_vars($field),
489                 function ($key) use ($clientVars) {
490                     return in_array($key, $clientVars);
491                 },
492                 ARRAY_FILTER_USE_KEY
493             );
494 
495             $clientInputs[$field->name]['type'] = $field::TYPE;
496         }
497 
498         // Generate the script to include the form in the application, client side
499         $inputs = json_encode($clientInputs, JSON_HEX_APOS | JSON_HEX_QUOT | JSON_NUMERIC_CHECK);
500         $errors = json_encode($this->errors, JSON_HEX_APOS | JSON_HEX_QUOT | JSON_NUMERIC_CHECK);
501 
502         return
503         View::make(Theme::getSelected()->getView(Form::VIEWS_DIR . 'form.tpl'), array(
504             'form' => $this,
505             'content' => $content,
506         )) .
507 
508         View::make(Plugin::get('main')->getView('form.js.tpl'), array(
509             'form' => $this,
510             'inputs' => $inputs,
511             'errors' => $errors
512         ));
513     }
514 
515     /**
516      * Display the form (alias of display method)
517      *
518      * @return string The HTML result of form displaying
519      */
520     public function __toString(){
521         return $this->display();
522     }
523 
524     /**
525      * Display the form
526      *
527      * @return string The HTML result of form displaying
528      */
529     public function display(){
530         try{
531             if(empty($this->fieldsets)) {
532                 // Generate a fake fieldset, to keep the same engine for forms that have fieldsets or not
533                 $this->addFieldset(new FormFieldset($this, ''));
534                 foreach ($this->inputs as $name => $input) {
535                     $this->fieldsets['']->inputs[$name] = &$input;
536                 }
537             }
538 
539             // Generate the form content
540             $content = View::make(Theme::getSelected()->getView(Form::VIEWS_DIR . 'form-content.tpl'), array(
541                 'form' => $this,
542                 'column' => 0
543             ));
544 
545             // Wrap the content with the form tag
546             return $this->wrap($content);
547         }
548         catch(\Exception $e){
549             App::errorHandler()->exception($e);
550         }
551     }
552 
553 
554     /**
555      * Check if the submitted values are correct
556      *
557      * @param bool $exit If set to true and if the data is not valid,
558      *                    this function will output the validation result on HTTP response
559      *
560      * @return bool true if the data is valid, false else.
561      */
562     public function check($exit = self::EXIT_JSON){
563         if(empty($this->errors))
564         $this->errors = array();
565 
566         foreach($this->inputs as $name => $field){
567             $field->check($this);
568         }
569 
570         if(!empty($this->errors)) {
571             $this->status = self::STATUS_ERROR;
572             App::logger()->warning(App::session()->getUser()->username . ' has badly completed the form ' . $this->id);
573             if($exit) {
574                 /*** The form check failed ***/
575                 App::response()->setBody($this->response(self::STATUS_CHECK_ERROR, Lang::get('form.error-fill')));
576                 throw new AppStopException();
577             }
578             else{
579                 $this->addReturn('message', Lang::get('form.error-fill'));
580                 return false;
581             }
582         }
583 
584         /*** The form check return OK status ***/
585         return true;
586     }
587 
588     /**
589      * Register the submitted data in the database
590      *
591      * @param bool   $exit    If set to true, the script will output after function execution, not depending on the result
592      * @param string $success Defines the message to output if the action has been well executed
593      * @param string $error   Defines the message to output if an error occured
594      *
595      * @return mixed The id of the created or updated element in the database
596      */
597     public function register($exit = self::EXIT_JSON, $success = "", $error = ""){
598         try{
599             $this->dbaction = self::ACTION_REGISTER;
600 
601             if($this->model == self::DEFAULT_MODEL || !$this->reference) {
602                 throw new \Exception("The method register of the class Form can be called only if model and reference properties are set");
603             }
604             if(!$this->object) {
605                 $model = $this->model;
606                 $this->object = new $model($this->getData());
607             }
608             else{
609                 $this->object->set($this->reference);
610             }
611 
612 
613             foreach($this->inputs as $name => $field){
614                 /* Determine if we have to insert this field in the set of inserted values
615                 * A field can't be inserted if :
616                 *   it type is in the independant types
617                 *   the field is defined as independant
618                 *   the fiels is defined as no insert
619                 */
620                 if(!$field->independant && $field->insert !== false && !$field->disabled) {
621                     /*** Insert the field value in the set ***/
622                     $this->object->set($name, $field->dbvalue());
623                 }
624             }
625 
626             if(!$this->new) {
627                 $this->object->update();
628             }
629             else{
630                 $this->object->save();
631             }
632 
633 
634             $id = $this->object->getPrimaryColumn();
635 
636             $this->addReturn(
637                 array(
638                 'primary' => $this->object->$id,
639                 'action' => self::ACTION_REGISTER,
640                 'new' => $this->new
641                 )
642             );
643             $this->status = self::STATUS_SUCCESS;
644 
645             App::logger()->info(App::session()->getUser()->username . ' has updated the data on the form ' . $this->id);
646             if($exit) {
647                 // output the response
648                 App::response()->setBody($this->response(self::STATUS_SUCCESS, $success ? $success : Lang::get('form.success-register')));
649                 throw new AppStopException();
650             }
651             return $this->object->$id;
652         }
653         catch(DBException $e){
654             $this->status = self::STATUS_ERROR;
655             App::logger()->error('An error occured while registering data on the form ' . $this->id . ' : ' . $e->getMessage());
656             if($exit) {
657                 return $this->response(self::STATUS_ERROR, DEBUG_MODE ? $e->getMessage() : ($error ? $error : Lang::get('form.error-register')));
658             }
659             throw $e;
660         }
661     }
662 
663 
664     /**
665      * Delete the element from the database
666      *
667      * @param bool   $exit    If set to true, the script will output after function execution, not depending on the result
668      * @param string $success Defines the message to output if the action has been well executed
669      * @param string $error   Defines the message to output if an error occured
670      *
671      * @return mixed The id of the deleted object
672      */
673     public function delete($exit = self::EXIT_JSON, $success = "", $error = ""){
674         try{
675             $this->dbaction = self::ACTION_DELETE;
676 
677             if($this->model == self::DEFAULT_MODEL || !$this->reference) {
678                 throw new \Exception("The method delete of the class Form can be called only if model and reference properties are set");
679             }
680 
681             if(!$this->object) {
682                 throw new \Exception("This object instance cannot be removed : No such object");
683             }
684 
685             $id = $this->object->getPrimaryColumn();
686             $this->object->delete();
687 
688             $this->addReturn(
689                 array(
690                 'primary' => $this->object->$id,
691                 'action' => self::ACTION_DELETE
692                 )
693             );
694             $this->status = self::STATUS_SUCCESS;
695 
696             App::logger()->info('The delete action on the form ' . $this->id . ' was successflully completed');
697             if($exit) {
698                 App::response()->setBody($this->response(self::STATUS_SUCCESS, $success ? $success : Lang::get('form.success-delete')));
699                 throw new AppStopException();
700             }
701             return $this->object->$id;
702         }
703         catch(DBException $e){
704             $this->status = self::STATUS_ERROR;
705             App::logger()->error('An error occured while deleting the element of the form ' . $this->id . ' : ' . $e->getMessage());
706 
707             if($exit) {
708                 return $this->response(self::STATUS_ERROR, DEBUG_MODE ? $e->getMessage() : ($error ? $error : Lang::get('form.error-delete')));
709             }
710             throw $e;
711         }
712     }
713 
714     /**
715      * Add an error on a field
716      *
717      * @param string $name  The name of the input to apply the error
718      * @param string $error The error message to apply
719      */
720     public function error($name, $error){
721         $this->errors[$name] = $error;
722     }
723 
724 
725     /**
726      * Add data to return to the client. To add several returns in on function call, define the first parameter as an associative array
727      *
728      * @param string $name    The name of the data to return
729      * @param string $message The value to apply
730      */
731     public function addReturn($name, $message= ""){
732         if(is_array($name)) {
733             foreach($name as $key => $value)
734             $this->addReturn($key, $value);
735         }
736         else{
737             $this->returns[$name] = $message;
738         }
739     }
740 
741 
742     /**
743      * Return the response of the form (generally when submitted),
744      * and set the Response HTTP code corresponding to the response, and the response type as JSON
745      *
746      * @param string $status  The status to output. You can use the class constants STATUS_SUCCESS, STATUS_CHECK_ERROR or STATUS_ERROR
747      * @param string $message The message to output. If not set, the default message corresponding to the status will be output
748      *
749      * @return array The response result, that will be displayed as json when the script ends
750      */
751     public function response($status, $message = ''){
752         $response = array();
753         switch($status){
754             case self::STATUS_SUCCESS :
755                 // The form has been submitted correctly
756                 App::response()->setStatus(self::HTTP_CODE_SUCCESS);
757                 if(! $this->nomessage) {
758                     $response['message'] = $message ? $message : Lang::get('form.'.$status.'-'.$this->dbaction);
759                 }
760                 $response['data'] = $this->returns;
761                 break;
762 
763             case self::STATUS_CHECK_ERROR :
764                 // An error occured while checking field syntaxes
765                 App::response()->setStatus(self::HTTP_CODE_CHECK_ERROR);
766                 $response['message'] = $message ? $message : Lang::get('form.error-fill');
767                 $response['errors'] = $this->errors;
768                 break;
769 
770             case self::STATUS_ERROR :
771             default :
772                 App::response()->setStatus(self::HTTP_CODE_ERROR);
773                 $response['message'] = $message ? $message : Lang::get('form.'.$status.'-'.$this->dbaction);
774                 $response['errors'] = $this->errors;
775                 break;
776         }
777 
778         App::response()->setContentType('json');
779         return $response;
780     }
781 
782 
783 
784     /**
785      * Make a generic treatment that detect the action to execute, check the form if necessary, and execute the action
786      *
787      * @param bool $exit If true, exit the script after function execution
788      *
789      * @return mixed The id of the treated element
790      */
791     public function treat($exit = self::EXIT_JSON){
792         if($this->submitted() == self::ACTION_DELETE) {
793             return $this->delete($exit);
794         }
795         else{
796             if($this->check($exit)) {
797                 return $this->register($exit);
798             }
799             else{
800                 return false;
801             }
802         }
803     }
804 }
805 

Hawk - PHP documentation API documentation generated by ApiGen