Koha/Calendar.pm

   1 package Koha::Calendar;
   2 use strict;
   3 use warnings;
   4 use 5.010;
   5
   6 use DateTime;
   7 use DateTime::Set;
   8 use DateTime::Duration;
   9 use C4::Context;
  10 use Koha::Caches;
  11 use Carp;
  12
  13 sub new {
  14     my ( $classname, %options ) = @_;
  15     my $self = {};
  16     bless $self, $classname;
  17     for my $o_name ( keys %options ) {
  18         my $o = lc $o_name;
  19         $self->{$o} = $options{$o_name};
  20     }
  21     if ( !defined $self->{branchcode} ) {
  22         croak 'No branchcode argument passed to Koha::Calendar->new';
  23     }
  24     $self->_init();
  25     return $self;
  26 }
  27
  28 sub _init {
  29     my $self       = shift;
  30     my $branch     = $self->{branchcode};
  31     my $dbh        = C4::Context->dbh();
  32     my $weekly_closed_days_sth = $dbh->prepare(
  33 'SELECT weekday FROM repeatable_holidays WHERE branchcode = ? AND weekday IS NOT NULL'
  34     );
  35     $weekly_closed_days_sth->execute( $branch );
  36     $self->{weekly_closed_days} = [ 0, 0, 0, 0, 0, 0, 0 ];
  37     while ( my $tuple = $weekly_closed_days_sth->fetchrow_hashref ) {
  38         $self->{weekly_closed_days}->[ $tuple->{weekday} ] = 1;
  39     }
  40     my $day_month_closed_days_sth = $dbh->prepare(
  41 'SELECT day, month FROM repeatable_holidays WHERE branchcode = ? AND weekday IS NULL'
  42     );
  43     $day_month_closed_days_sth->execute( $branch );
  44     $self->{day_month_closed_days} = {};
  45     while ( my $tuple = $day_month_closed_days_sth->fetchrow_hashref ) {
  46         $self->{day_month_closed_days}->{ $tuple->{month} }->{ $tuple->{day} } =
  47           1;
  48     }
  49
  50     $self->{days_mode}       ||= C4::Context->preference('useDaysMode');
  51     $self->{test}            = 0;
  52     return;
  53 }
  54
  55 sub exception_holidays {
  56     my ( $self ) = @_;
  57
  58     my $cache  = Koha::Caches->get_instance();
  59     my $cached = $cache->get_from_cache('exception_holidays');
  60     return $cached if $cached;
  61
  62     my $dbh = C4::Context->dbh;
  63     my $branch = $self->{branchcode};
  64     my $exception_holidays_sth = $dbh->prepare(
  65 'SELECT day, month, year FROM special_holidays WHERE branchcode = ? AND isexception = 1'
  66     );
  67     $exception_holidays_sth->execute( $branch );
  68     my $dates = [];
  69     while ( my ( $day, $month, $year ) = $exception_holidays_sth->fetchrow ) {
  70         push @{$dates},
  71           DateTime->new(
  72             day       => $day,
  73             month     => $month,
  74             year      => $year,
  75             time_zone => "floating",
  76           )->truncate( to => 'day' );
  77     }
  78     $self->{exception_holidays} =
  79       DateTime::Set->from_datetimes( dates => $dates );
  80     $cache->set_in_cache( 'exception_holidays', $self->{exception_holidays} );
  81     return $self->{exception_holidays};
  82 }
  83
  84 sub single_holidays {
  85     my ( $self, $date ) = @_;
  86     my $branchcode = $self->{branchcode};
  87     my $cache           = Koha::Caches->get_instance();
  88     my $single_holidays = $cache->get_from_cache('single_holidays');
  89
  90     # $single_holidays looks like:
  91     # {
  92     #   CPL =>  [
  93     #        [0] 20131122,
  94     #         ...
  95     #    ],
  96     #   ...
  97     # }
  98
  99     unless ($single_holidays) {
 100         my $dbh = C4::Context->dbh;
 101         $single_holidays = {};
 102
 103         # push holidays for each branch
 104         my $branches_sth =
 105           $dbh->prepare('SELECT distinct(branchcode) FROM special_holidays');
 106         $branches_sth->execute();
 107         while ( my $br = $branches_sth->fetchrow ) {
 108             my $single_holidays_sth = $dbh->prepare(
 109 'SELECT day, month, year FROM special_holidays WHERE branchcode = ? AND isexception = 0'
 110             );
 111             $single_holidays_sth->execute($br);
 112
 113             my @ymd_arr;
 114             while ( my ( $day, $month, $year ) =
 115                 $single_holidays_sth->fetchrow )
 116             {
 117                 my $dt = DateTime->new(
 118                     day       => $day,
 119                     month     => $month,
 120                     year      => $year,
 121                     time_zone => 'floating',
 122                 )->truncate( to => 'day' );
 123                 push @ymd_arr, $dt->ymd('');
 124             }
 125             $single_holidays->{$br} = \@ymd_arr;
 126         }    # br
 127         $cache->set_in_cache( 'single_holidays', $single_holidays,
 128             { expiry => 76800 } )    #24 hrs ;
 129     }
 130     my $holidays  = ( $single_holidays->{$branchcode} );
 131     for my $hols  (@$holidays ) {
 132             return 1 if ( $date == $hols )   #match ymds;
 133     }
 134     return 0;
 135 }
 136
 137 sub addDate {
 138     my ( $self, $startdate, $add_duration, $unit ) = @_;
 139
 140     # Default to days duration (legacy support I guess)
 141     if ( ref $add_duration ne 'DateTime::Duration' ) {
 142         $add_duration = DateTime::Duration->new( days => $add_duration );
 143     }
 144
 145     $unit ||= 'days'; # default days ?
 146     my $dt;
 147     if ( $unit eq 'hours' ) {
 148         # Fixed for legacy support. Should be set as a branch parameter
 149         my $return_by_hour = 10;
 150
 151         $dt = $self->addHours($startdate, $add_duration, $return_by_hour);
 152     } else {
 153         # days
 154         $dt = $self->addDays($startdate, $add_duration);
 155     }
 156     return $dt;
 157 }
 158
 159 sub addHours {
 160     my ( $self, $startdate, $hours_duration, $return_by_hour ) = @_;
 161     my $base_date = $startdate->clone();
 162
 163     $base_date->add_duration($hours_duration);
 164
 165     # If we are using the calendar behave for now as if Datedue
 166     # was the chosen option (current intended behaviour)
 167
 168     if ( $self->{days_mode} ne 'Days' &&
 169           $self->is_holiday($base_date) ) {
 170
 171         if ( $hours_duration->is_negative() ) {
 172             $base_date = $self->prev_open_days($base_date, 1);
 173         } else {
 174             $base_date = $self->next_open_days($base_date, 1);
 175         }
 176
 177         $base_date->set_hour($return_by_hour);
 178
 179     }
 180
 181     return $base_date;
 182 }
 183
 184 sub addDays {
 185     my ( $self, $startdate, $days_duration ) = @_;
 186     my $base_date = $startdate->clone();
 187
 188     $self->{days_mode} ||= q{};
 189
 190     if ( $self->{days_mode} eq 'Calendar' ) {
 191         # use the calendar to skip all days the library is closed
 192         # when adding
 193         my $days = abs $days_duration->in_units('days');
 194
 195         if ( $days_duration->is_negative() ) {
 196             while ($days) {
 197                 $base_date = $self->prev_open_days($base_date, 1);
 198                 --$days;
 199             }
 200         } else {
 201             while ($days) {
 202                 $base_date = $self->next_open_days($base_date, 1);
 203                 --$days;
 204             }
 205         }
 206
 207     } else { # Days, Datedue or Dayweek
 208         # use straight days, then use calendar to push
 209         # the date to the next open day as appropriate
 210         # if Datedue or Dayweek
 211         $base_date->add_duration($days_duration);
 212
 213         if ( $self->{days_mode} eq 'Datedue' ||
 214             $self->{days_mode} eq 'Dayweek') {
 215             # Datedue or Dayweek, then use the calendar to push
 216             # the date to the next open day if holiday
 217             if ( $self->is_holiday($base_date) ) {
 218                 my $dow = $base_date->day_of_week;
 219                 my $days = $days_duration->in_units('days');
 220                 # Is it a period based on weeks
 221                 my $push_amt = $days % 7 == 0 ?
 222                     $self->get_push_amt($base_date) : 1;
 223                 if ( $days_duration->is_negative() ) {
 224                     $base_date = $self->prev_open_days($base_date, $push_amt);
 225                 } else {
 226                     $base_date = $self->next_open_days($base_date, $push_amt);
 227                 }
 228             }
 229         }
 230     }
 231
 232     return $base_date;
 233 }
 234
 235 sub get_push_amt {
 236     my ( $self, $base_date) = @_;
 237
 238     my $dow = $base_date->day_of_week;
 239     # Representation fix
 240     # DateTime object dow (1-7) where Monday is 1
 241     # Arrays are 0-based where 0 = Sunday, not 7.
 242     if ( $dow == 7 ) {
 243         $dow = 0;
 244     }
 245
 246     return (
 247         # We're using Dayweek useDaysMode option
 248         $self->{days_mode} eq 'Dayweek' &&
 249         # It's not a permanently closed day
 250         !$self->{weekly_closed_days}->[$dow]
 251     ) ? 7 : 1;
 252 }
 253
 254 sub is_holiday {
 255     my ( $self, $dt ) = @_;
 256
 257     my $localdt = $dt->clone();
 258     my $day   = $localdt->day;
 259     my $month = $localdt->month;
 260
 261     #Change timezone to "floating" before doing any calculations or comparisons
 262     $localdt->set_time_zone("floating");
 263     $localdt->truncate( to => 'day' );
 264
 265
 266     if ( $self->exception_holidays->contains($localdt) ) {
 267         # exceptions are not holidays
 268         return 0;
 269     }
 270
 271     my $dow = $localdt->day_of_week;
 272     # Representation fix
 273     # DateTime object dow (1-7) where Monday is 1
 274     # Arrays are 0-based where 0 = Sunday, not 7.
 275     if ( $dow == 7 ) {
 276         $dow = 0;
 277     }
 278
 279     if ( $self->{weekly_closed_days}->[$dow] == 1 ) {
 280         return 1;
 281     }
 282
 283     if ( exists $self->{day_month_closed_days}->{$month}->{$day} ) {
 284         return 1;
 285     }
 286
 287     my $ymd   = $localdt->ymd('')  ;
 288     if ($self->single_holidays(  $ymd  ) == 1 ) {
 289         return 1;
 290     }
 291
 292     # damn have to go to work after all
 293     return 0;
 294 }
 295
 296 sub next_open_days {
 297     my ( $self, $dt, $to_add ) = @_;
 298     my $base_date = $dt->clone();
 299
 300     $base_date->add(days => $to_add);
 301     while ($self->is_holiday($base_date)) {
 302         my $add_next = $self->get_push_amt($base_date);
 303         $base_date->add(days => $add_next);
 304     }
 305     return $base_date;
 306 }
 307
 308 sub prev_open_days {
 309     my ( $self, $dt, $to_sub ) = @_;
 310     my $base_date = $dt->clone();
 311
 312     # It feels logical to be passed a positive number, though we're
 313     # subtracting, so do the right thing
 314     $to_sub = $to_sub > 0 ? 0 - $to_sub : $to_sub;
 315
 316     $base_date->add(days => $to_sub);
 317
 318     while ($self->is_holiday($base_date)) {
 319         my $sub_next = $self->get_push_amt($base_date);
 320         # Ensure we're subtracting when we need to be
 321         $sub_next = $sub_next > 0 ? 0 - $sub_next : $sub_next;
 322         $base_date->add(days => $sub_next);
 323     }
 324
 325     return $base_date;
 326 }
 327
 328 sub days_forward {
 329     my $self     = shift;
 330     my $start_dt = shift;
 331     my $num_days = shift;
 332
 333     return $start_dt unless $num_days > 0;
 334
 335     my $base_dt = $start_dt->clone();
 336
 337     while ($num_days--) {
 338         $base_dt = $self->next_open_days($base_dt, 1);
 339     }
 340
 341     return $base_dt;
 342 }
 343
 344 sub days_between {
 345     my $self     = shift;
 346     my $start_dt = shift;
 347     my $end_dt   = shift;
 348
 349     # Change time zone for date math and swap if needed
 350     $start_dt = $start_dt->clone->set_time_zone('floating');
 351     $end_dt = $end_dt->clone->set_time_zone('floating');
 352     if( $start_dt->compare($end_dt) > 0 ) {
 353         ( $start_dt, $end_dt ) = ( $end_dt, $start_dt );
 354     }
 355
 356     # start and end should not be closed days
 357     my $delta_days = $start_dt->delta_days($end_dt)->delta_days;
 358     while( $start_dt->compare($end_dt) < 1 ) {
 359         $delta_days-- if $self->is_holiday($start_dt);
 360         $start_dt->add( days => 1 );
 361     }
 362     return DateTime::Duration->new( days => $delta_days );
 363 }
 364
 365 sub hours_between {
 366     my ($self, $start_date, $end_date) = @_;
 367     my $start_dt = $start_date->clone()->set_time_zone('floating');
 368     my $end_dt = $end_date->clone()->set_time_zone('floating');
 369
 370     my $duration = $end_dt->delta_ms($start_dt);
 371     $start_dt->truncate( to => 'day' );
 372     $end_dt->truncate( to => 'day' );
 373
 374     # NB this is a kludge in that it assumes all days are 24 hours
 375     # However for hourly loans the logic should be expanded to
 376     # take into account open/close times then it would be a duration
 377     # of library open hours
 378     my $skipped_days = 0;
 379     while( $start_dt->compare($end_dt) < 1 ) {
 380         $skipped_days++ if $self->is_holiday($start_dt);
 381         $start_dt->add( days => 1 );
 382     }
 383
 384     if ($skipped_days) {
 385         $duration->subtract_duration(DateTime::Duration->new( hours => 24 * $skipped_days));
 386     }
 387
 388     return $duration;
 389 }
 390
 391 sub set_daysmode {
 392     my ( $self, $mode ) = @_;
 393
 394     # if not testing this is a no op
 395     if ( $self->{test} ) {
 396         $self->{days_mode} = $mode;
 397     }
 398
 399     return;
 400 }
 401
 402 sub clear_weekly_closed_days {
 403     my $self = shift;
 404     $self->{weekly_closed_days} = [ 0, 0, 0, 0, 0, 0, 0 ];    # Sunday only
 405     return;
 406 }
 407
 408 1;
 409 __END__
 410
 411 =head1 NAME
 412
 413 Koha::Calendar - Object containing a branches calendar
 414
 415 =head1 SYNOPSIS
 416
 417   use Koha::Calendar
 418
 419   my $c = Koha::Calendar->new( branchcode => 'MAIN' );
 420   my $dt = dt_from_string();
 421
 422   # are we open
 423   $open = $c->is_holiday($dt);
 424   # when will item be due if loan period = $dur (a DateTime::Duration object)
 425   $duedate = $c->addDate($dt,$dur,'days');
 426
 427
 428 =head1 DESCRIPTION
 429
 430   Implements those features of C4::Calendar needed for Staffs Rolling Loans
 431
 432 =head1 METHODS
 433
 434 =head2 new : Create a calendar object
 435
 436 my $calendar = Koha::Calendar->new( branchcode => 'MAIN' );
 437
 438 The option branchcode is required
 439
 440
 441 =head2 addDate
 442
 443     my $dt = $calendar->addDate($date, $dur, $unit)
 444
 445 C<$date> is a DateTime object representing the starting date of the interval.
 446
 447 C<$offset> is a DateTime::Duration to add to it
 448
 449 C<$unit> is a string value 'days' or 'hours' toflag granularity of duration
 450
 451 Currently unit is only used to invoke Staffs return Monday at 10 am rule this
 452 parameter will be removed when issuingrules properly cope with that
 453
 454
 455 =head2 addHours
 456
 457     my $dt = $calendar->addHours($date, $dur, $return_by_hour )
 458
 459 C<$date> is a DateTime object representing the starting date of the interval.
 460
 461 C<$offset> is a DateTime::Duration to add to it
 462
 463 C<$return_by_hour> is an integer value representing the opening hour for the branch
 464
 465 =head2 get_push_amt
 466
 467     my $amt = $calendar->get_push_amt($date)
 468
 469 C<$date> is a DateTime object representing a closed return date
 470
 471 Using the days_mode syspref value and the nature of the closed return
 472 date, return how many days we should jump forward to find another return date
 473
 474 =head2 addDays
 475
 476     my $dt = $calendar->addDays($date, $dur)
 477
 478 C<$date> is a DateTime object representing the starting date of the interval.
 479
 480 C<$offset> is a DateTime::Duration to add to it
 481
 482 C<$unit> is a string value 'days' or 'hours' toflag granularity of duration
 483
 484 Currently unit is only used to invoke Staffs return Monday at 10 am rule this
 485 parameter will be removed when issuingrules properly cope with that
 486
 487
 488 =head2 single_holidays
 489
 490 my $rc = $self->single_holidays(  $ymd  );
 491
 492 Passed a $date in Ymd (yyyymmdd) format -  returns 1 if date is a single_holiday, or 0 if not.
 493
 494
 495 =head2 is_holiday
 496
 497 $yesno = $calendar->is_holiday($dt);
 498
 499 passed a DateTime object returns 1 if it is a closed day
 500 0 if not according to the calendar
 501
 502 =head2 days_between
 503
 504 $duration = $calendar->days_between($start_dt, $end_dt);
 505
 506 Passed two dates returns a DateTime::Duration object measuring the length between them
 507 ignoring closed days. Always returns a positive number irrespective of the
 508 relative order of the parameters.
 509
 510 Note: This routine assumes neither the passed start_dt nor end_dt can be a closed day
 511
 512 =head2 hours_between
 513
 514 $duration = $calendar->hours_between($start_dt, $end_dt);
 515
 516 Passed two dates returns a DateTime::Duration object measuring the length between them
 517 ignoring closed days. Always returns a positive number irrespective of the
 518 relative order of the parameters.
 519
 520 Note: This routine assumes neither the passed start_dt nor end_dt can be a closed day
 521
 522 =head2 next_open_days
 523
 524 $datetime = $calendar->next_open_days($duedate_dt, $to_add)
 525
 526 Passed a Datetime and number of days,  returns another Datetime representing
 527 the next open day after adding the passed number of days. It is intended for
 528 use to calculate the due date when useDaysMode syspref is set to either
 529 'Datedue', 'Calendar' or 'Dayweek'.
 530
 531 =head2 prev_open_days
 532
 533 $datetime = $calendar->prev_open_days($duedate_dt, $to_sub)
 534
 535 Passed a Datetime and a number of days, returns another Datetime
 536 representing the previous open day after subtracting the number of passed
 537 days. It is intended for use to calculate the due date when useDaysMode
 538 syspref is set to either 'Datedue', 'Calendar' or 'Dayweek'.
 539
 540 =head2 set_daysmode
 541
 542 For testing only allows the calling script to change days mode
 543
 544 =head2 clear_weekly_closed_days
 545
 546 In test mode changes the testing set of closed days to a new set with
 547 no closed days. TODO passing an array of closed days to this would
 548 allow testing of more configurations
 549
 550 =head2 add_holiday
 551
 552 Passed a datetime object this will add it to the calendar's list of
 553 closed days. This is for testing so that we can alter the Calenfar object's
 554 list of specified dates
 555
 556 =head1 DIAGNOSTICS
 557
 558 Will croak if not passed a branchcode in new
 559
 560 =head1 BUGS AND LIMITATIONS
 561
 562 This only contains a limited subset of the functionality in C4::Calendar
 563 Only enough to support Staffs Rolling loans
 564
 565 =head1 AUTHOR
 566
 567 Colin Campbell colin.campbell@ptfs-europe.com
 568
 569 =head1 LICENSE AND COPYRIGHT
 570
 571 Copyright (c) 2011 PTFS-Europe Ltd All rights reserved
 572
 573 This program is free software: you can redistribute it and/or modify
 574 it under the terms of the GNU General Public License as published by
 575 the Free Software Foundation, either version 2 of the License, or
 576 (at your option) any later version.
 577
 578 This program is distributed in the hope that it will be useful,
 579 but WITHOUT ANY WARRANTY; without even the implied warranty of
 580 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 581 GNU General Public License for more details.
 582
 583 You should have received a copy of the GNU General Public License
 584 along with this program.  If not, see <http://www.gnu.org/licenses/>.