Source for file timeslotrule.php

Documentation is available at timeslotrule.php

  1. <?php
  2. /**
  3. * Timeslot validation based on rules passed to us (presumably from an SQL entry)
  4. *
  5. * @author    Stuart Prescott
  6. * @copyright  Copyright Stuart Prescott
  7. * @license    http://opensource.org/licenses/gpl-license.php GNU Public License
  8. * @version    $Id$
  9. * @package    Bumblebee
  10. * @subpackage Bookings
  11. */
  12.  
  13. /** Load ancillary functions */
  14. require_once 'inc/typeinfo.php';
  15. checkValidInclude();
  16.  
  17. /** date manipulation routines */
  18. require_once 'inc/date.php';
  19. /** timeslot object for bookings/vacancies */
  20. require_once 'timeslot.php';
  21.  
  22. /** date-time operation control: look for match with start of slot */
  23. define('TSSTART',  'tstart');
  24. /** date-time operation control: look for match with end of slot */
  25. define('TSSTOP',   'tstop');
  26. /** date-time operation control: look for slot where this time is within the slot */
  27. define('TSWITHIN', 2);
  28. /** date-time operation control: look for slot following this time */
  29. define('TSNEXT',   3);
  30. // define('TSSLOT',   4);
  31. /** number of extra elements that will be in the array created from the slot rules */
  32. define('TSARRAYMIN', 1);
  33. /** flag that slot was not found by the slot finding routines */
  34. define('TS_SLOT_NOT_FOUND', -10000);
  35.  
  36.  
  37. /**
  38. * Timeslot validation based on rules passed to us (presumably from an SQL entry)
  39. *
  40. * @package    Bumblebee
  41. * @subpackage Bookings
  42. * @todo //TODO:       more documentation
  43. */
  44. class TimeSlotRule {
  45.   var $picture = '';
  46.   var $slots;
  47.  
  48.   var $DEBUG = 0;
  49.  
  50.   function TimeSlotRule($pic) {
  51.     $this->picture = $pic;
  52.     $this->_interpret();
  53.   }
  54.  
  55.   /**
  56.    * timeslot picture syntax (concatinate onto one line, no spaces)
  57.    * [x] or [x-y]
  58.    *         specify the day of week (or range of days). 0=Sunday, 6=Saturday
  59.    * <slot;slot;slot>
  60.    *         around the comma-separated slot specifications for that day. All times from 00:00 to 24:00
  61.    *         must be included in the list
  62.    * starttime-stoptime/num_slots-discount%,comment
  63.    *         HH:MM time slots with the length of each slot.
  64.    *         e.g. 09:00-17:00/1 specifies a slot starting at 9am and finishing 5pm.
  65.    *              both 00:00 and 24:00 are valid, also 32:00 for 8am the next day (o'night)
  66.    *         num_slots is integer, or wildcard of * for freely adjustable time
  67.    *         e.g. 09:00-12:00/3 specifies 3 slots 9-10, 10-11 and 11-12.
  68.    *         discount (optional) is the percentage discount applied to bookings in that slot
  69.    *         comment  (optional) is displayed in vacant or unavailable slots
  70.    *
  71.    * EXAMPLES:
  72.    *
  73.    * [0-6]<00:00-08:00/*;08:00-13:00/1;13:00-18:00/1;18:00-24:00/*>
  74.    *    Available all days, free booking until 8am and after 6pm, other slots as defined
  75.    * [0]<00:00-24:00/0,Unavailable>[1-5]<09:00-17:00/01:00>[6]<00:00-24:00/0,Unavailable>
  76.    *    Not available Sunday and Saturday. Only available weekdays 9am till 5pm with 1hr booking
  77.    *    granularity. Calendar views of Sat & Sun will see message "Unavailable"
  78.    * [0]<>[1-5]<00:00-09:00/*;09:00-17:00/8;17:00-24:00/*-50%>[6]<>
  79.    *    Not available Sunday and Saturday. Available weekdays 9am till 5pm with 1hr booking
  80.    *    granularity, before 9am and after 5pm with no granularity and at a 50% discount.
  81.    * [0]<>[1-5]<09:00-13:00/4;13:00-17:00/2;17:00-33:00/1>[6]<>
  82.    *    Not available Sunday and Saturday. Available weekdays 9am till 5pm with 1hr booking
  83.    *    granularity, before 9am and after 5pm with no granularity
  84.    *
  85.    */
  86.   function _interpret() {
  87.     $this->slots = array();
  88.     for ($dow=0; $dow<=6; $dow++) {
  89.       $this->slots[$dow] = array();
  90.     }
  91.     $this->_findDayLines();
  92.     for ($dow=0; $dow<=6; $dow++) {
  93.       $this->_fillDaySlots($dow);
  94.     }
  95.   }
  96.  
  97.   function _findDayLines() {
  98.     $daylines = array();
  99.     preg_match_all('/\[.+?\>/', $this->picture, $daylines);
  100.     foreach ($daylines[0] as $d) {
  101.       $day = array();
  102.       #echo "considering $d\n";
  103.       if (preg_match('/\[(\d)\]/', $d, $day)) {
  104.         #echo "found match: ".$day[1]."\n";
  105.         $this->slots[$day[1]]['picture']=$d;
  106.       }
  107.       if (preg_match('/\[(\d)-(\d)\]/', $d, $day)) {
  108.         #echo "found multimatch: ".$day[1].'.'.$day[2]."\n";
  109.         for ($i=$day[1]; $i<=$day[2]; $i++) {
  110.           $this->slots[$i]['picture']=$d;
  111.         }
  112.       }
  113.     }
  114.   }
  115.  
  116.   function _fillDaySlots($dow) {
  117.     $times = array();
  118.     #preDump($this->slots[$dow]['picture']);
  119.     preg_match('/\<(.*)\>/', $this->slots[$dow]['picture'], $times);
  120.     #preDump($times);
  121.     if ($times[0] == '<>') {
  122.       $times[1]='00:00-24:00/0';
  123.     }
  124.  
  125.     $i=0;
  126.     foreach(preg_split('/;/', $times[1]) as $slot) {
  127.       #echo "found slot=$slot\n";
  128.       #$this->slots[$dow][$i] = array();
  129.       $tmp = array();
  130.       if (preg_match('/(\d\d:\d\d)-(\d\d:\d\d)\/(\d+|\*)(-\d+%)?(?:,(.+))?/', $slot, $tmp)) {
  131.         /* regexp:       HH:MM    -  HH:MM     /n         -x%       ,comment
  132.            group:         1            2        3          4          5
  133.            notes:
  134.               n can be digit or *
  135.               x is optional and can be one or more digits
  136.               ,comment is optional and the comma is not included in the captured pattern
  137.               ?: means don't capture the contents of that subpattern () to $tmp
  138.         */
  139.         $start    = $tmp[1];
  140.         $stop     = $tmp[2];
  141.         $tstart   = new SimpleTime($start);
  142.         $tstop    = new SimpleTime($stop);
  143.         $numslots = $tmp[3];
  144.         $optional=4;
  145.         $discount = 0; $comment = '';
  146.         while (isset($tmp[$optional])) {
  147.           if (substr($tmp[$optional], 0, 1) == '-' && substr($tmp[$optional], -1, 1) == '%') {
  148.             // then it's a discouint
  149.             $discount = substr($tmp[$optional],1,-1);
  150.           } else {
  151.             // then it's the comment at the end
  152.             $comment  = $tmp[$optional];
  153.           }
  154.           $optional++;
  155.         }
  156.         //echo "(start,stop,slots) = ($start,$stop,$numslots)\n";
  157.         //echo "(discount,comment) = ($discount,$comment)<br />\n";
  158.         if ($numslots != '*' && $numslots != '0') {
  159.           #echo "Trying to interpolate timeslots\n";
  160.           $tgran = new SimpleTime($tstop->subtract($tstart)/$numslots);
  161.           $siblingSlot=1;
  162.           for ($time = clone($tstart); $time->ticks < $tstop->ticks; $time->addTime($tgran)) {
  163.             //echo $time->timeString().' '. $tstop->timeString().' '.$tgran->timeString()."<br />\n";
  164.             $sstop = clone($time);
  165.             $sstop->addTime($tgran);
  166.             $this->slots[$dow][$i] = new RuleSlot($slot, $start, $stop, clone($time), $sstop, $tgran);
  167.             $this->slots[$dow][$i]->numslotsInGroup = 1;
  168.             $this->slots[$dow][$i]->numslotsFollowing = $numslots - $siblingSlot;
  169.             $this->slots[$dow][$i]->comment = $comment;
  170.             $this->slots[$dow][$i]->discount = $discount;
  171.             if ($time->ticks != $tstart->ticks) {
  172.               $this->slots[$dow][$i-1]->nextSlot = &$this->slots[$dow][$i];
  173.             }
  174.             $i++;
  175.             $siblingSlot++;
  176.           }
  177.         } else {
  178.           #echo "No need to interpolate\n";
  179.           $this->slots[$dow][$i] = new RuleSlot($slot, $start, $stop, $tstart, $tstop);
  180.           $this->slots[$dow][$i]->numslotsInGroup = 1;
  181.           $this->slots[$dow][$i]->numslotsFollowing = 0;
  182.           $this->slots[$dow][$i]->isFreeForm = $numslots == '*';
  183.           $this->slots[$dow][$i]->isAvailable = $numslots != '0';
  184.           $this->slots[$dow][$i]->comment = $comment;
  185.           $this->slots[$dow][$i]->discount = $discount;
  186.           $i++;
  187.         }
  188.       }
  189.     }
  190.     #var_dump($this->slots);
  191.   }
  192.  
  193. /*  function allSlotStart() {
  194.     echo "STUB: ". __FILE__ .' '. __LINE__;
  195.     return array('09:00','10:00','15:00');
  196.   }*/
  197.  
  198.   /**
  199.    * return true if the specified date & time correspond to a valid starting time according
  200.    * to this object's slot rules.
  201.    */
  202.   function isValidStart($date) {
  203.     return $this->_isValidStartStop($date, TSSTART);
  204.   }
  205.  
  206.   /**
  207.    * return true if the specified date & time correspond to a valid stopping time according
  208.    * to this object's slot rules.
  209.    */
  210.   function isValidStop($date) {
  211.     $startday = clone($date);
  212.     $startday->dayRound();
  213.     //echo "$startday->dateTimeString() =? $date->dateTimeString()\n";
  214.     if ($startday->ticks == $date->ticks) {
  215.       $time = new SimpleTime('24:00');
  216.       $startday->addDays(-1);
  217.       //echo "$startday->dateTimeString() + $time->timeString()\n";
  218.       return $this->_isValidStartStop($time, TSSTOP, $startday);
  219.     }
  220.     return $this->_isValidStartStop($date, TSSTOP);
  221.   }
  222.  
  223.   /**
  224.    * perform the above operations with no code duplication
  225.    */
  226.   function _isValidStartStop($date, $type, $daysdate=0) {
  227.     return ! is_object($this->_findSlot($date, $type, $daysdate));
  228.   }
  229.  
  230.   /**
  231.    * return true if the specified dates & times are valid start/stop times
  232.    * to this object's slot rules.
  233.    */
  234.   function isValidSlot($startdate, $stopdate) {
  235.     return $this->isValidStart($startdate) && $this->isValidStop($stopdate);
  236.   }
  237.  
  238.   /**
  239.    * return true if the specified dates & times are valid as above, but only occupy one slot
  240.    */
  241.   function isValidSingleSlot($startdate, $stopdate) {
  242.     $slot = $this->_findSlot($startdate, TSSTART);
  243.     return $slot->stop->ticks == $stopdate->ticks;
  244.   }
  245.  
  246.   /**
  247.    * return the corresponding the slot specified by the given start date.
  248.    * ASSUMES that the specified date is a valid start, else behaviour is undefined.
  249.    *
  250.    * @param mixed SimpleDate $date the date to match or SimpleTime to match
  251.    * @param mixed optional SimpleDate iff $date was a SimpleTime. Provide the date component
  252.    */
  253.   function findSlotByStart($date, $datetime=0) {
  254.     return $this->_findSlot($date, TSSTART, $datetime);
  255.   }
  256.  
  257.   /**
  258.    * return the
  259.    * as per findSlotByStart
  260.    */
  261.   function findSlotByStop($date, $datetime=0) {
  262.     return $this->_findSlot($date, TSSTOP, $datetime);
  263.   }
  264.  
  265.   /**
  266.    * return the corresponding startdate/time to a time that is possibly within a slot
  267.    */
  268.   function findSlotFromWithin($date, $datetime=0) {
  269.     return $this->_findSlot($date, TSWITHIN, $datetime);
  270.   }
  271.  
  272.   /**
  273.    * returns the slot that starts >= the date specified.
  274.    */
  275.   function findNextSlot($date, $datetime=0) {
  276.     return $this->_findSlot($date, TSNEXT, $datetime);
  277.   }
  278.  
  279.  
  280.   /**
  281.    * return the corresponding slot number of the starting or stopping date-time $date
  282.    * returns -1 if no matching slot found.
  283.    * $match is TSSTART, TSSTOP, TSWITHIN, TSNEXT depending on what matching is queried.
  284.    * $return is TSSTART or TSSTOP depending on the required return value
  285.    *
  286.    * this function will return a slot from the previous day if the slot spans days and
  287.    * that is the appropriate slot.
  288.    *
  289.    * WARNING: There be dragons....
  290.    */
  291.   function _findSlot($date, $match, $datetime=0) {
  292.     #$this->DEBUG=10;
  293.     //$this->log("TimeSlotRule::_findSlot:($date->dateTimeString(), $match, $datetime)", 10);
  294.     //preDump(debug_backtrace());
  295.     if ($datetime == 0) {
  296.       $time = $date->timePart();
  297.       $dow = $date->dow();
  298.       $day = clone($date);
  299.     } else {
  300.       $time = clone($date);
  301.       $dow = $datetime->dow();
  302.       $day = clone($datetime);
  303.       //echo "Found $time->timeString(), $dow, $day->dateTimeString()\n";
  304.     }
  305.     $slot=0;
  306.     $timecmp = $match;
  307.     if ($match == TSWITHIN) $timecmp = TSSTOP;
  308.     if ($match == TSNEXT)   $timecmp = TSSTART;
  309.     $startvar = TSSTART;
  310.     $stopvar  = TSSTOP;
  311.     #preDump($this->slots[$dow]);
  312.     $this->log("TimeSlotRule::_findSlot:(".$time->timeString().", ".$this->slots[$dow][0]->$startvar->ticks.", $time->ticks, $dow)", 10);
  313.     if ($time->ticks < $this->slots[$dow][0]->$startvar->ticks
  314.         || $match ==  TSSTOP && $time->ticks <= $this->slots[$dow][0]->$startvar->ticks) {
  315.       $dow = ($dow+6)%7;
  316.       $day->addDays(-1);
  317.       $time->addSecs(24*60*60);
  318.       $this->log("Stepped back a day to do the comparison");
  319.     }
  320. /*    $this->log("TimeSlotRule::_findSlot:($time->timeString(), ".$this->slots[$dow][0]->$stopvar->ticks.", $time->ticks, $dow)", 10);
  321.     if ($time->ticks > $this->slots[$dow][count($this->slots[$dow])-1-TSARRAYMIN]->$stopvar->ticks) {
  322.       $dow = ($dow+1)%7;
  323.       $day->addDays(1);
  324.       $time->addSecs(-24*60*60);
  325.       $this->log("Stepped forward a day to do the comparison");
  326.     }*/
  327.     $this->log("Asking for ($dow, $slot, $timecmp, $match)", 10);
  328.     //preDump($this->slots[$dow]);
  329.     while(
  330.             //print_r("Asking for ($dow, $slot, $match)<br />") &&
  331.             $slot < count($this->slots[$dow])-TSARRAYMIN
  332.             && $time->ticks >= $this->slots[$dow][$slot]->$timecmp->ticks) {
  333.       //echo $time->ticks .'#'. $this->slots[$dow][$slot]->$timecmp->ticks."\n";
  334.       //echo $slot .'#'.(count($this->slots[$dow])-TSARRAYMIN)."\n";
  335.       $slot++;
  336.     }
  337.     #echo count($this->slots[$dow])-TSARRAYMIN."/";
  338.     #echo $time->ticks .', '. $this->slots[$dow][$slot-1]->$timecmp->ticks."\n";
  339.     $this->log("Final ($dow, $slot, $match)",10);
  340.     if ($match == TSSTART || $match == TSSTOP) {
  341.       $slot--;
  342.       $finalslot = ($slot < count($this->slots[$dow])-TSARRAYMIN
  343.                     && $slot >= 0
  344.                     && $time->ticks == $this->slots[$dow][$slot]->$timecmp->ticks)
  345.                     ? $slot : TS_SLOT_NOT_FOUND ;
  346.     } elseif ($match == TSWITHIN) {
  347.       $a=TSSTART;
  348.       $b=TSSTOP;
  349.       $finalslot =  ($slot < count($this->slots[$dow])-TSARRAYMIN
  350.                       && $time->ticks >= $this->slots[$dow][$slot]->$a->ticks
  351.                       && $time->ticks <  $this->slots[$dow][$slot]->$b->ticks)
  352.                       ? $slot : TS_SLOT_NOT_FOUND ;
  353.       //echo "Found containing slot: $finalslot\n";
  354.     } else { //TSNEXT
  355.       if ($slot >= count($this->slots[$dow])-TSARRAYMIN) {
  356.         //echo "Looking for next slot in overflow:\n";
  357.         do {
  358.           //echo "($dow, $day->dateTimeString(),".count($this->slots[$dow]).")\n";
  359.           $dow = ($dow+1) % 7;
  360.           $day->addDays(1);
  361.           $finalslot=0;
  362.         } while (count($this->slots[$dow]) <= TSARRAYMIN);
  363.         //echo "($dow, $day->dateTimeString(),".TSARRAYMIN.")\n".count($this->slots[$dow]);
  364.       } else {
  365.         $finalslot = $slot;
  366.       }
  367.     }
  368.     $this->log("ReallyFinal ($dow, $finalslot, $match)",10);
  369.     if ($finalslot == TS_SLOT_NOT_FOUND) {
  370.       //trigger_error('Could not find a match to this time slot.', E_USER_NOTICE);
  371.       return 0;
  372.       $finalslot==0;
  373.     }
  374.     $returnSlot = clone($this->slots[$dow][$finalslot]);
  375.     //preDump($returnSlot);
  376.     #echo $day->datetimestring();
  377.     $returnSlot->setDate($day);
  378.     #preDump($returnSlot->dump());
  379.     return $returnSlot;
  380.   }
  381.  
  382.   function dump($html=1) {
  383.     #preDump($this->slots);
  384.     #return;
  385.     $eol = $html ? "<br />\n" : "\n";
  386.     $s = '';
  387.     $s .= "Initial Pattern = '". $this->picture ."'".$eol;
  388.     for ($day=0; $day<=6; $day++) {
  389.       $s .= "Day Pattern[$day] = '". $this->slots[$day]['picture'] ."'".$eol;
  390.       //for ($j=0; $j<count($this->slots[$day]) && isset($this->slots[$day][$j]); $j++) {
  391.       foreach ($this->slots[$day] as $k => $v) {
  392.         if (is_numeric($k)) {
  393.           $s .= $v->dump($html);
  394. //           $s .= "\t" . $v->tstart->timeString()
  395. //                 ." - ". $v->tstop->timeString() .$eol;
  396.         }
  397.       }
  398.     }
  399.     return $s;
  400.   }
  401.  
  402.   function log($logstring, $prio=10) {
  403.     if ($prio <= $this->DEBUG) {
  404.       echo $logstring."<br />\n";
  405.     }
  406.   }
  407.  
  408.  
  409. } //class TimeSlotRule
  410.  
  411.  
  412.  
  413. /**
  414. * Data object for an individual time slot defined by the time slot picture
  415. *
  416. * @author    Stuart Prescott
  417. * @copyright  Copyright Stuart Prescott
  418. * @license    http://opensource.org/licenses/gpl-license.php GNU Public License
  419. * @version    $Id$
  420. * @package    Bumblebee
  421. * @subpackage Bookings
  422. * @todo //TODO:       more documentation
  423. */
  424. class RuleSlot {
  425.   var $tstart;
  426.   var $tstop;
  427.   var $tgran;
  428.   var $start;
  429.   var $stop;
  430.   var $startStr;
  431.   var $stopStr;
  432.   var $numslotsFollowing = 0;
  433.   var $numslotsInGroup = 1;
  434.   var $isFreeForm = 0;
  435.   var $isAvailable = 1;
  436.   var $picture = '';
  437.   var $nextSlot;
  438.   var $comment = '';
  439.   var $discount = 0;
  440.  
  441.   function RuleSlot($picture, $startStr, $stopStr, $tstart, $tstop, $tgran=NULL) {
  442.     $this->picture = $picture;
  443.     $this->startStr = $startStr;
  444.     $this->stopStr = $stopStr;
  445.     $this->tstart = $tstart;
  446.     $this->tstop = $tstop;
  447.     $this->tgran = type_is_a($tgran, 'SimpleTime') ? $tgran : new SimpleTime(0);
  448.   }
  449.  
  450.   function setDate($date) {
  451.     $this->start = clone($date);
  452.     $this->start->setTime($this->tstart);
  453.     $this->stop = clone($date);
  454.     $this->stop->setTime($this->tstop);
  455.   }
  456.  
  457.   function dump($html=1) {
  458.     $eol = $html ? "<br />\n" : "\n";
  459.     return 'Slot:'."\t"
  460.           .$this->tstart->timeString().' - '
  461.           .$this->tstop->timeString().' : '
  462.           .($this->isAvailable? 'Available' : 'Not available')
  463.           .($this->isFreeForm ? ' Freeform' : '')
  464.           .($this->comment !== '' && $this->comment !== NULL ? ' Comment = '.$this->comment : '')
  465.           .$eol
  466.     ;
  467.   }
  468.  
  469.   function allSlotDurations($offset=0) {
  470.     $duration = array();
  471.     $cslot = $this;
  472.     $cdur = $this->tgran;
  473.     for ($i=0; $i<=$this->numslotsFollowing; $i++) {
  474.       #echo $i.': length='.$cslot->tgran->timeString().', sum='.$cdur->timeString()."<br />\n";
  475.       $dur = clone($cdur);
  476.       $dur->addSecs($offset);
  477.       $duration[] = clone($cdur);
  478.       $cdur->addTime($cslot->tgran);
  479.       $cslot = $cslot->nextSlot;
  480.     }
  481.     return $duration;
  482.   }
  483.  
  484.   function allSlotEnds() {
  485.     $ends = array();
  486.     $cslot = $this;
  487.     for ($i=0; $i<=$this->numslotsFollowing; $i++) {
  488.       $cslot->setDate($this->start);
  489.       $ends[] = clone($cslot->stop);
  490.       $cslot = $cslot->nextSlot;
  491.     }
  492.     return $ends;
  493.   }
  494.  

Documentation generated on Tue, 06 Mar 2007 10:02:04 +0000 by phpDocumentor 1.3.0