CheckboxHistory class

<?php
namespace app\system;
/**
* Maintain a list of checkboxes and the immediate history
*
* Uses: array of  $key => $label
*
*   the key can be numbers or string the class works with keys
*
*   e.g.  $cbxHistory = new CheckboxHistory(array('key1' => 'label 1',
*                                                 'key2' => 'label 2',
*                                                 'key3' => 'label 3',
*                                                 ))
*
* It uses a string to hold whether each checkbox in the list currently is checked or not
*
*  e.g.   $cbxHistory->cbxStateString()
*
*         This will be stored in a hidden field $_POST and will become the $prvCheckedState
*
*
*
*  It generates all the details to
*     1) use in the checkbox HTML
*          'label' is for the html checkbox label
*          'value' is for the html checkbox value
*            note: the value is a position in the list not a key!
*
*     2) The state of the checkbox and whether is has just changed
*
*  e.g.  $cbxHistory->cbxDetails($key);
*
*        returns: array('label'       => $this->cbxLabel($key),
*                       'value'       => $this->cbxValue($key),
*                       'key'         => $key,
*
*                       'hasChanged'  => $this->hasChanged($key),
*                       'curChecked'  => $this->curChecked($key),
*                       'prvChecked'  => $this->prvChecked($key));
*
*  It uses a cbxStateString to know what the previous states of the checkbox
*
*    e.g.  $cbxHistory->setCbxCheckedState($oldCbxCheckedState);
*
*          This will normally be from the html 'hidden' cbxState field
*
*/

class CheckboxHistory implements ICheckboxHistory {

   protected $labelList = null;

   protected $curCheckedState = '';

   protected $prvCheckedState = '';

   protected $keyList = null; // needed to find the position of the key

   public function __construct(array $labelList, $prvStateStr = '')
   {
       $pos = 0;
       foreach($labelList as $key => $label) {
           $this->labelList[$key] = array('label' => $label, 'pos' => $pos);
           $pos++;
       }
       $this->curCheckedState = str_repeat('0', count($this->labelList));
       $this->prvCheckedState = str_repeat('0', count($this->labelList));
       $this->keyList = array_keys($labelList);
       if (!empty($prvStateStr)) {
           $this->fromCbxStateString($prvStateStr);
       }
   }

   /**
   * The label value to be used in the html
   *
   * @param mixed $key
   *
   * @return label text
   */
   public function cbxLabel($key)
   {
       return $this->labelList[$key]['label'];
   }

   /**
   * The value to be used for the checkbox in the html.
   *
   * It is actually the postion of the lookup key in the list
   *
   * @param mixed $key
   *
   * @return integer
   */
   public function cbxValue($key)
   {
       return $this->keyToPosition($key);
   }

   /**
   * The 'key' of the checkbox given the 'value' (position])
   *
   * It is actually the key at that position in the list
   *
   * @param integer position (value)
   *
   * @return integer
   */
   public function cbxKey($value)
   {
       return $this->keyList[$position];
   }

   /**
   * This is the current state vector of all the checkboxes
   *
   * It is stored in a 'hidden' field on the form
   *
   * It is used in the  fromCbxStateString() method
   *
   * @return string
   */
   public function cbxStateString()
   {
       return $this->curCheckedState;
   }


   /**
   * An array of checkbox keys
   *
   * used to convert the 'position' (value) to a key for lookup.
   *
   * @return array
   */
   public function cbxKeyList()
   {
       return $this->keyList;
   }

   /**
   * All the details (checkbox state) in one convenient list
   *
   * @param mixed $key
   *
   * @return array
   */
   public function cbxDetails($key)
   {
       return array('label'       => $this->cbxLabel($key),
                    'value'       => $this->cbxValue($key),
                    'key'         => $key,
                    'hasChanged'  => $this->hasChanged($key),
                    'curChecked'  => $this->curChecked($key),
                    'prvChecked'  => $this->prvChecked($key),
               );
   }

   public function cbxDetailsByKey($key) { return $this->cbxDetails($key); }

   /**
   * All the details (checkbox state) in one convenient list given a checkbox value
   *
   *
   * @param integer $position
   *
   * @return array
   */
   public function cbxDetailsByValue($position)
   {
       return $this->cbxDetails($this->keyList[$position]);
    }

  /**
  * All the cbxDetails as an iterator
  *
  *   The key of the array is position  (cbxValue)
  *
  * @return array
  */
  public function cbxDetailsArray()
  {
       $details = array();
       foreach($this->keyList as $key) {
           $details[] = $this->cbxDetails($key);
       }
       return $details;
  }

   /**
   * All the cbxDetails as an iterator
   *
   * The key of the array is position  (cbxValue)
   *
   * @return \ArrayIterator
   */
   public function getIterator()
   {
       return new \ArrayIterator($this->cbxDetailsArray());
   }


   /**
   * Set or unset a checkbox by key value
   *
   * @param mixed   $key
   * @param boolean $checked
   *
   * @return void
   */
   public function setCheckbox($key, $checked = true)
   {
           $keyPos = $this->keyToPosition($key);
           $this->curCheckedState[$keyPos] = $checked ? '1' : '0';
   }

   public function setCheckboxByKey($key, $checked = true) { $this->setCheckbox($key, $checked); }


   public function setCheckboxByValue($cbxValue, $checked = true)
   {
           $this->setCheckbox($this->keyList[$cbxValue], $checked);
   }

   /**
   * current state of a checkbox
   *
   * @param mixed $key
   *
   * @return boolean
   */
   public function curChecked($key)
   {
       $keyPos = $this->keyToPosition($key);
       return (bool) $this->curCheckedState[$keyPos];
   }

   /**
   * previous state of a checkbox
   *
   * @param mixed $key
   *
   * @return booleam
   */
   public function prvChecked($key)
   {
       $keyPos = $this->keyToPosition($key);
       return (bool) $this->prvCheckedState[$keyPos];
   }

   /**
   * Has the checkbox changed state (user checked or unchecked it)
   *
   * @param mixed $key
   *
   * @return boolean
   */
   public function hasChanged($key)
   {
       $keyPos = $this->keyToPosition($key);
       return $this->curCheckedState[$keyPos] !== $this->prvCheckedState[$keyPos];
   }

   /**
   * set the curCheckedState from an array of values ($positions)
   *
   * @param array $positionList i.e. $_POST
   *
   * @return void
   */
   public function fromCheckedList(array $checkedPos)
   {
       $this->curCheckedState = str_repeat('0', count($this->labelList));
       foreach ($checkedPos as $position) {
           $this->setCheckbox($this->keyList[$position], true);
       }
   }

   /**
   * This is the previous state of the all checkboxes
   *
   * It is obtained from the chechboxes 'hidden' field
   *
   * @param string $prvStateStr
   *
   * @return void
   */
   public function setCbxStateString($prvStateStr)
   {
       // must be the correct lentgth
       $this->prvCheckedState = str_pad($prvStateStr, count($this->labelList), $this->prvCheckedState);
   }


   // given a key get the postion of the key in the list
   protected function keyToPosition($key)
   {
       return $this->labelList[$key]['pos'];
   }
}