[Sommaire] [Imprimer]

   1  <?php
   2  
   3      /**
   4       * \defgroup Forms
   5       *
   6       * The Form class helps in data validation.
   7       */
   8      
   9      /**
  10       * Set this to true if you want to get some debug information every time
  11       * a validation error occurs
  12       */
  13      define( "FORM_VALIDATOR_DEBUG", false );
  14      
  15      /**
  16       * \ingroup Forms
  17       *
  18       * This the class used for form validation. It works helped by the Validator classes to perform data validation,
  19       * as well as in conjunction with the Action and View classes. It is fact internally used by the Action class and it is
  20       * capable of reporting to the view class which fields of a given form generated an error.
  21       */
  22      class FormValidator 
  23      {
  24          var $_fieldValidators;
  25          var $_validationResults;
  26          var $_fieldValues;
  27          var $_formIsValidated;
  28          var $_formHasRun;
  29          var $_fieldErrorMessages;
  30          var $_formDebug;
  31              
  32          /**
  33           * initializes the form validator
  34           */
  35  		function FormValidator()
  36          {
  37              
  38              
  39              // internal arrays used by the class
  40              $this->_fieldValidators = Array();
  41              $this->_validationResults = Array();
  42              $this->_fieldValues = Array();
  43              $this->_fieldErrorMessages = Array();
  44              
  45              $this->_formDebug = FORM_VALIDATOR_DEBUG;
  46              
  47              // the form hasn't been validated yet
  48              $this->_formIsValidated = false;
  49              
  50              // form hasn't run yet
  51              $this->_formHasRun = false;
  52          }
  53          
  54          /**
  55           * registers a new validator, for validating data coming from fields
  56           * 
  57           * @param fieldName The name of the field from the form that we're going to validate
  58           * @param validator A valid class inheriting from the Validator base class and that implements
  59           * the validate() method, that will be used for validating fields.
  60           * @param onlyIfAvailable validate this field only if its value is not emtpy
  61           * @return Always true
  62           */
  63  		function registerFieldValidator( $fieldName, $validatorClass, $onlyIfAvailable = false )
  64          {
  65              $this->_fieldValidators["$fieldName"] = Array( "validator" => $validatorClass, "onlyIfAvailable" => $onlyIfAvailable );        
  66          }
  67          
  68          /**
  69           * it is also possible to specify custom error messages from within the php code,
  70           * instead of leaving it up to the templates to decide which error message to show
  71           *
  72           * @param fieldName
  73           * @param errorMessage
  74           * @return Always true
  75           */
  76  		function setFieldErrorMessage( $fieldName, $errorMessage )
  77          {
  78              $this->_fieldErrorMessages["$fieldName"] = $errorMessage;
  79          }
  80          
  81          /**
  82           * validates the data in the field
  83           *
  84           * @return True if all the fields validate or false otherwise
  85           */
  86  		function validate( $request )
  87          {
  88              if( empty( $this->_fieldValidators ) || !is_array( $this->_fieldValidators ))
  89                  return true;
  90      
  91              $validationResult = false;
  92              $finalValidationResult = true;
  93              
  94              foreach( $this->_fieldValidators as $fieldName => $fieldValidationArrayInfo ) {            
  95                  // get the validator object
  96                  $fieldValidatorClass = $fieldValidationArrayInfo["validator"];
  97                  // and whether we should use it always or only when the field has a non-empty value
  98                  $onlyIfAvailable = $fieldValidationArrayInfo["onlyIfAvailable"];
  99                  
 100                  // get the value of the field
 101                  $fieldValue = $request->getValue( $fieldName );
 102                  
 103                  if( $fieldValue == "" && $onlyIfAvailable ) {
 104                      $validationResult = true;
 105                  }
 106                  else {
 107                      $validationResult = $fieldValidatorClass->validate( $fieldValue );
 108                  }
 109                  
 110                  $this->_validationResults["$fieldName"] = $validationResult;
 111                  $this->_fieldValues["$fieldName"] = $fieldValue;
 112                  
 113                  // if one of the validations is false, then cancel the whole thing
 114                  $finalValidationResult = $finalValidationResult && $validationResult;                
 115              }
 116              
 117              // the form has already run
 118              $this->_formHasRun = true;
 119              
 120              // but... has it validated?
 121              $this->_formIsValidated = $finalValidationResult;
 122              
 123              // in case we have to display some debug information
 124              if( !$finalValidationResult && $this->_formDebug )
 125                  $this->dump();
 126              
 127              return $finalValidationResult;
 128          }
 129          
 130          /**
 131           * forces a field to be true
 132           *
 133           * @param fieldName
 134           * @return always true
 135           */
 136  		function registerField( $fieldName )
 137          {
 138              lt_include( PLOG_CLASS_PATH."class/data/validator/emptyvalidator.class.php" );        
 139              $this->registerFieldValidator( $fieldName, new EmptyValidator());
 140              
 141              return true;
 142          }
 143          
 144          /**
 145           * returns whether the field was validated successfully or not. Do not use
 146           * this method *before* calling FormValidator::validate()
 147           *
 148           * @param field The name of the field in the form
 149           * @return True if it validates or false otherwise
 150           */
 151  		function isFieldValid( $field )
 152          {
 153              if( $this->formIsValid())
 154                  $valid = true;
 155              else
 156                  $valid = $this->_validationResults["$field"];
 157                  
 158              return $valid;
 159          }
 160          
 161          /**
 162           * returns an array where the field name is the key and the value will be
 163           * either '0' or '1' depending on whether the field validated successfully or not
 164           *
 165           * @return An associative array
 166           */
 167  		function getFormValidationResults()
 168          {
 169              return $this->_validationResults;
 170          }
 171          
 172          /**
 173           * returns an array where the key is the field and the value is the value of the field, but it
 174           * will only contain those fields which have been registered
 175           *
 176           * @return An associative array
 177           */
 178  		function getFieldValues()
 179          {
 180              return $this->_fieldValues;
 181          }
 182          
 183          /**
 184           * returns whether the form is valid or not
 185           *
 186           * @return a boolean
 187           */
 188  		function formIsValid()
 189          {
 190              return $this->_formIsValidated;
 191          }
 192          
 193          /**
 194           * changes the form validation status
 195           *
 196           * @param valid
 197           */
 198  		function setFormIsValid( $valid )
 199          {
 200              $this->_formIsValidated = $valid;
 201          }
 202          
 203          /**
 204           * changes the processing status of a field
 205           *
 206           * @param fieldName
 207           * @return True
 208           */
 209  		function setFieldValidationStatus( $fieldName, $newStatus )
 210          {
 211              $this->_validationResults["$fieldName"] = $newStatus;
 212              
 213              // if we're setting some field to false, then the whole form becomes
 214              // non-validated too!
 215              $this->_formIsValidated = false;
 216              $this->_formHasRun = true;
 217              
 218              return true;
 219          }
 220          
 221          /**
 222           * returns true if the form has already been executed (if FormValidator::validate()
 223           * has already been called or not) Use this function when performing validatdion
 224           * of data in your templates, since otherwise FormValidator::fieldIsValid and
 225           * FormValidator::formIsValid() will always return false if validate() has not
 226           * been called!
 227           *
 228           * @return returns true if the form has already been validated, or false otherwise
 229           */
 230  		function formHasRun()
 231          {
 232              return $this->_formHasRun;
 233          }
 234          
 235          /**
 236           * returns the custom error message for the field, if any
 237           *
 238           * @param fieldName
 239           */
 240  		function getFieldErrorMessage( $fieldName )
 241          {
 242              return $this->_fieldErrorMessages["$fieldName"];
 243          }
 244          
 245          /**
 246           * dumps the current status of the form, useful for debugging 
 247           * purposes when we know that a field is not validating correctly but there
 248           * is no error message displayed on the screen
 249           */
 250  		function dump()
 251          {
 252              print("<pre>");
 253              foreach( $this->_fieldValidators as $field => $validationInfo ) {
 254                  print( "field = $field - validator class = ".get_class( $validationInfo["validator"] ).
 255                         " - status = ".$this->_validationResults["$field"]."<br/>" );
 256              }
 257              print("</pre>");
 258          }
 259      }
 260  ?>