Koha/Hold.pm

   1 package Koha::Hold;
   2
   3 # Copyright ByWater Solutions 2014
   4 # Copyright 2017 Koha Development team
   5 #
   6 # This file is part of Koha.
   7 #
   8 # Koha is free software; you can redistribute it and/or modify it
   9 # under the terms of the GNU General Public License as published by
  10 # the Free Software Foundation; either version 3 of the License, or
  11 # (at your option) any later version.
  12 #
  13 # Koha is distributed in the hope that it will be useful, but
  14 # WITHOUT ANY WARRANTY; without even the implied warranty of
  15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  16 # GNU General Public License for more details.
  17 #
  18 # You should have received a copy of the GNU General Public License
  19 # along with Koha; if not, see <http://www.gnu.org/licenses>.
  20
  21 use Modern::Perl;
  22
  23 use List::MoreUtils qw( any );
  24
  25 use C4::Context;
  26 use C4::Letters qw( GetPreparedLetter EnqueueLetter );
  27 use C4::Log qw( logaction );
  28
  29 use Koha::AuthorisedValues;
  30 use Koha::DateUtils qw( dt_from_string );
  31 use Koha::Patrons;
  32 use Koha::Biblios;
  33 use Koha::Items;
  34 use Koha::Libraries;
  35 use Koha::Old::Holds;
  36 use Koha::Calendar;
  37 use Koha::Plugins;
  38
  39 use Koha::Exceptions::Hold;
  40
  41 use base qw(Koha::Object);
  42
  43 =head1 NAME
  44
  45 Koha::Hold - Koha Hold object class
  46
  47 =head1 API
  48
  49 =head2 Class methods
  50
  51 =cut
  52
  53 =head3 age
  54
  55 returns the number of days since a hold was placed, optionally
  56 using the calendar
  57
  58 my $age = $hold->age( $use_calendar );
  59
  60 =cut
  61
  62 sub age {
  63     my ( $self, $use_calendar ) = @_;
  64
  65     my $today = dt_from_string;
  66     my $age;
  67
  68     if ( $use_calendar ) {
  69         my $calendar = Koha::Calendar->new( branchcode => $self->branchcode );
  70         $age = $calendar->days_between( dt_from_string( $self->reservedate ), $today );
  71     }
  72     else {
  73         $age = $today->delta_days( dt_from_string( $self->reservedate ) );
  74     }
  75
  76     $age = $age->in_units( 'days' );
  77
  78     return $age;
  79 }
  80
  81 =head3 suspend_hold
  82
  83 my $hold = $hold->suspend_hold( $suspend_until_dt );
  84
  85 =cut
  86
  87 sub suspend_hold {
  88     my ( $self, $dt ) = @_;
  89
  90     my $date = $dt ? $dt->clone()->truncate( to => 'day' )->datetime : undef;
  91
  92     if ( $self->is_found ) {    # We can't suspend found holds
  93         if ( $self->is_waiting ) {
  94             Koha::Exceptions::Hold::CannotSuspendFound->throw( status => 'W' );
  95         }
  96         elsif ( $self->is_in_transit ) {
  97             Koha::Exceptions::Hold::CannotSuspendFound->throw( status => 'T' );
  98         }
  99         elsif ( $self->is_in_processing ) {
 100             Koha::Exceptions::Hold::CannotSuspendFound->throw( status => 'P' );
 101         }
 102         else {
 103             Koha::Exceptions::Hold::CannotSuspendFound->throw(
 104                       'Unhandled data exception on found hold (id='
 105                     . $self->id
 106                     . ', found='
 107                     . $self->found
 108                     . ')' );
 109         }
 110     }
 111
 112     $self->suspend(1);
 113     $self->suspend_until($date);
 114     $self->store();
 115
 116     Koha::Plugins->call(
 117         'after_hold_action',
 118         {
 119             action  => 'suspend',
 120             payload => { hold => $self->get_from_storage }
 121         }
 122     );
 123
 124     logaction( 'HOLDS', 'SUSPEND', $self->reserve_id, $self )
 125         if C4::Context->preference('HoldsLog');
 126
 127     return $self;
 128 }
 129
 130 =head3 resume
 131
 132 my $hold = $hold->resume();
 133
 134 =cut
 135
 136 sub resume {
 137     my ( $self ) = @_;
 138
 139     $self->suspend(0);
 140     $self->suspend_until( undef );
 141
 142     $self->store();
 143
 144     Koha::Plugins->call(
 145         'after_hold_action',
 146         {
 147             action  => 'resume',
 148             payload => { hold => $self->get_from_storage }
 149         }
 150     );
 151
 152     logaction( 'HOLDS', 'RESUME', $self->reserve_id, $self )
 153         if C4::Context->preference('HoldsLog');
 154
 155     return $self;
 156 }
 157
 158 =head3 delete
 159
 160 $hold->delete();
 161
 162 =cut
 163
 164 sub delete {
 165     my ( $self ) = @_;
 166
 167     my $deleted = $self->SUPER::delete($self);
 168
 169     logaction( 'HOLDS', 'DELETE', $self->reserve_id, $self )
 170         if C4::Context->preference('HoldsLog');
 171
 172     return $deleted;
 173 }
 174
 175 =head3 set_transfer
 176
 177 =cut
 178
 179 sub set_transfer {
 180     my ( $self ) = @_;
 181
 182     $self->priority(0);
 183     $self->found('T');
 184     $self->store();
 185
 186     return $self;
 187 }
 188
 189 =head3 set_waiting
 190
 191 =cut
 192
 193 sub set_waiting {
 194     my ( $self, $desk_id ) = @_;
 195
 196     $self->priority(0);
 197
 198     my $today = dt_from_string();
 199
 200     my $values = {
 201         found => 'W',
 202         ( !$self->waitingdate ? ( waitingdate => $today->ymd ) : () ),
 203         desk_id => $desk_id,
 204     };
 205
 206     my $requested_expiration;
 207     if ($self->expirationdate) {
 208         $requested_expiration = dt_from_string($self->expirationdate);
 209     }
 210
 211     my $max_pickup_delay = C4::Context->preference("ReservesMaxPickUpDelay");
 212     my $cancel_on_holidays = C4::Context->preference('ExpireReservesOnHolidays');
 213
 214     my $expirationdate = $today->clone;
 215     $expirationdate->add(days => $max_pickup_delay);
 216
 217     if ( C4::Context->preference("ExcludeHolidaysFromMaxPickUpDelay") ) {
 218         my $itemtype = $self->item ? $self->item->effective_itemtype : $self->biblio->itemtype;
 219         my $daysmode = Koha::CirculationRules->get_effective_daysmode(
 220             {
 221                 categorycode => $self->borrower->categorycode,
 222                 itemtype     => $itemtype,
 223                 branchcode   => $self->branchcode,
 224             }
 225         );
 226         my $calendar = Koha::Calendar->new( branchcode => $self->branchcode, days_mode => $daysmode );
 227
 228         $expirationdate = $calendar->days_forward( dt_from_string(), $max_pickup_delay );
 229     }
 230
 231     # If patron's requested expiration date is prior to the
 232     # calculated one, we keep the patron's one.
 233     my $cmp = $requested_expiration ? DateTime->compare($requested_expiration, $expirationdate) : 0;
 234     $values->{expirationdate} = $cmp == -1 ? $requested_expiration->ymd : $expirationdate->ymd;
 235
 236     $self->set($values)->store();
 237
 238     return $self;
 239 }
 240
 241 =head3 is_pickup_location_valid
 242
 243     if ($hold->is_pickup_location_valid({ library_id => $library->id }) ) {
 244         ...
 245     }
 246
 247 Returns a I<boolean> representing if the passed pickup location is valid for the hold.
 248 It throws a I<Koha::Exceptions::_MissingParameter> if the library_id parameter is not
 249 passed.
 250
 251 =cut
 252
 253 sub is_pickup_location_valid {
 254     my ( $self, $params ) = @_;
 255
 256     Koha::Exceptions::MissingParameter->throw('The library_id parameter is mandatory')
 257         unless $params->{library_id};
 258
 259     my $pickup_locations;
 260
 261     if ( $self->itemnumber ) { # item-level
 262         $pickup_locations = $self->item->pickup_locations({ patron => $self->patron });
 263     }
 264     else { # biblio-level
 265         $pickup_locations = $self->biblio->pickup_locations({ patron => $self->patron });
 266     }
 267
 268     return any { $_->branchcode eq $params->{library_id} } $pickup_locations->as_list;
 269 }
 270
 271 =head3 set_pickup_location
 272
 273     $hold->set_pickup_location(
 274         {
 275             library_id => $library->id,
 276           [ force   => 0|1 ]
 277         }
 278     );
 279
 280 Updates the hold pickup location. It throws a I<Koha::Exceptions::Hold::InvalidPickupLocation> if
 281 the passed pickup location is not valid.
 282
 283 Note: It is up to the caller to verify if I<AllowHoldPolicyOverride> is set when setting the
 284 B<force> parameter.
 285
 286 =cut
 287
 288 sub set_pickup_location {
 289     my ( $self, $params ) = @_;
 290
 291     Koha::Exceptions::MissingParameter->throw('The library_id parameter is mandatory')
 292         unless $params->{library_id};
 293
 294     if (
 295         $params->{force}
 296         || $self->is_pickup_location_valid(
 297             { library_id => $params->{library_id} }
 298         )
 299       )
 300     {
 301         # all good, set the new pickup location
 302         $self->branchcode( $params->{library_id} )->store;
 303     }
 304     else {
 305         Koha::Exceptions::Hold::InvalidPickupLocation->throw;
 306     }
 307
 308     return $self;
 309 }
 310
 311 =head3 set_processing
 312
 313 $hold->set_processing;
 314
 315 Mark the hold as in processing.
 316
 317 =cut
 318
 319 sub set_processing {
 320     my ( $self ) = @_;
 321
 322     $self->priority(0);
 323     $self->found('P');
 324     $self->store();
 325
 326     return $self;
 327 }
 328
 329 =head3 is_found
 330
 331 Returns true if hold is waiting, in transit or in processing
 332
 333 =cut
 334
 335 sub is_found {
 336     my ($self) = @_;
 337
 338     return 0 unless $self->found();
 339     return 1 if $self->found() eq 'W';
 340     return 1 if $self->found() eq 'T';
 341     return 1 if $self->found() eq 'P';
 342 }
 343
 344 =head3 is_waiting
 345
 346 Returns true if hold is a waiting hold
 347
 348 =cut
 349
 350 sub is_waiting {
 351     my ($self) = @_;
 352
 353     my $found = $self->found;
 354     return $found && $found eq 'W';
 355 }
 356
 357 =head3 is_in_transit
 358
 359 Returns true if hold is a in_transit hold
 360
 361 =cut
 362
 363 sub is_in_transit {
 364     my ($self) = @_;
 365
 366     return 0 unless $self->found();
 367     return $self->found() eq 'T';
 368 }
 369
 370 =head3 is_in_processing
 371
 372 Returns true if hold is a in_processing hold
 373
 374 =cut
 375
 376 sub is_in_processing {
 377     my ($self) = @_;
 378
 379     return 0 unless $self->found();
 380     return $self->found() eq 'P';
 381 }
 382
 383 =head3 is_cancelable_from_opac
 384
 385 Returns true if hold is a cancelable hold
 386
 387 Holds may be only canceled if they are not found.
 388
 389 This is used from the OPAC.
 390
 391 =cut
 392
 393 sub is_cancelable_from_opac {
 394     my ($self) = @_;
 395
 396     return 1 unless $self->is_found();
 397     return 0; # if ->is_in_transit or if ->is_waiting or ->is_in_processing
 398 }
 399
 400 =head3 is_at_destination
 401
 402 Returns true if hold is waiting
 403 and the hold's pickup branch matches
 404 the hold item's holding branch
 405
 406 =cut
 407
 408 sub is_at_destination {
 409     my ($self) = @_;
 410
 411     return $self->is_waiting() && ( $self->branchcode() eq $self->item()->holdingbranch() );
 412 }
 413
 414 =head3 biblio
 415
 416 Returns the related Koha::Biblio object for this hold
 417
 418 =cut
 419
 420 sub biblio {
 421     my ($self) = @_;
 422
 423     $self->{_biblio} ||= Koha::Biblios->find( $self->biblionumber() );
 424
 425     return $self->{_biblio};
 426 }
 427
 428 =head3 patron
 429
 430 Returns the related Koha::Patron object for this hold
 431
 432 =cut
 433
 434 sub patron {
 435     my ($self) = @_;
 436
 437     my $patron_rs = $self->_result->patron;
 438     return Koha::Patron->_new_from_dbic($patron_rs);
 439 }
 440
 441 =head3 item
 442
 443 Returns the related Koha::Item object for this Hold
 444
 445 =cut
 446
 447 sub item {
 448     my ($self) = @_;
 449
 450     $self->{_item} ||= Koha::Items->find( $self->itemnumber() );
 451
 452     return $self->{_item};
 453 }
 454
 455 =head3 branch
 456
 457 Returns the related Koha::Library object for this Hold
 458
 459 =cut
 460
 461 sub branch {
 462     my ($self) = @_;
 463
 464     $self->{_branch} ||= Koha::Libraries->find( $self->branchcode() );
 465
 466     return $self->{_branch};
 467 }
 468
 469 =head3 desk
 470
 471 Returns the related Koha::Desk object for this Hold
 472
 473 =cut
 474
 475 sub desk {
 476     my $self = shift;
 477     my $desk_rs = $self->_result->desk;
 478     return unless $desk_rs;
 479     return Koha::Desk->_new_from_dbic($desk_rs);
 480 }
 481
 482 =head3 borrower
 483
 484 Returns the related Koha::Patron object for this Hold
 485
 486 =cut
 487
 488 # FIXME Should be renamed with ->patron
 489 sub borrower {
 490     my ($self) = @_;
 491
 492     $self->{_borrower} ||= Koha::Patrons->find( $self->borrowernumber() );
 493
 494     return $self->{_borrower};
 495 }
 496
 497 =head3 is_suspended
 498
 499 my $bool = $hold->is_suspended();
 500
 501 =cut
 502
 503 sub is_suspended {
 504     my ( $self ) = @_;
 505
 506     return $self->suspend();
 507 }
 508
 509
 510 =head3 cancel
 511
 512 my $cancel_hold = $hold->cancel(
 513     {
 514         [ charge_cancel_fee => 1||0, ]
 515         [ cancellation_reason => $cancellation_reason, ]
 516     }
 517 );
 518
 519 Cancel a hold:
 520 - The hold will be moved to the old_reserves table with a priority=0
 521 - The priority of other holds will be updated
 522 - The patron will be charge (see ExpireReservesMaxPickUpDelayCharge) if the charge_cancel_fee parameter is set
 523 - The canceled hold will have the cancellation reason added to old_reserves.cancellation_reason if one is passed in
 524 - a CANCEL HOLDS log will be done if the pref HoldsLog is on
 525
 526 =cut
 527
 528 sub cancel {
 529     my ( $self, $params ) = @_;
 530     $self->_result->result_source->schema->txn_do(
 531         sub {
 532             $self->cancellationdate( dt_from_string->strftime( '%Y-%m-%d %H:%M:%S' ) );
 533             $self->priority(0);
 534             $self->cancellation_reason( $params->{cancellation_reason} );
 535             $self->store();
 536
 537             if ( $params->{cancellation_reason} ) {
 538                 my $letter = C4::Letters::GetPreparedLetter(
 539                     module                 => 'reserves',
 540                     letter_code            => 'HOLD_CANCELLATION',
 541                     message_transport_type => 'email',
 542                     branchcode             => $self->borrower->branchcode,
 543                     lang                   => $self->borrower->lang,
 544                     tables => {
 545                         branches    => $self->borrower->branchcode,
 546                         borrowers   => $self->borrowernumber,
 547                         items       => $self->itemnumber,
 548                         biblio      => $self->biblionumber,
 549                         biblioitems => $self->biblionumber,
 550                         reserves    => $self->unblessed,
 551                     }
 552                 );
 553
 554                 if ($letter) {
 555                     C4::Letters::EnqueueLetter(
 556                         {
 557                             letter                   => $letter,
 558                             borrowernumber         => $self->borrowernumber,
 559                             message_transport_type => 'email',
 560                         }
 561                     );
 562                 }
 563             }
 564
 565             my $old_me = $self->_move_to_old;
 566
 567             Koha::Plugins->call(
 568                 'after_hold_action',
 569                 {
 570                     action  => 'cancel',
 571                     payload => { hold => $old_me->get_from_storage }
 572                 }
 573             );
 574
 575             $self->SUPER::delete(); # Do not add a DELETE log
 576
 577             # now fix the priority on the others....
 578             C4::Reserves::_FixPriority({ biblionumber => $self->biblionumber });
 579
 580             # and, if desired, charge a cancel fee
 581             my $charge = C4::Context->preference("ExpireReservesMaxPickUpDelayCharge");
 582             if ( $charge && $params->{'charge_cancel_fee'} ) {
 583                 my $account =
 584                   Koha::Account->new( { patron_id => $self->borrowernumber } );
 585                 $account->add_debit(
 586                     {
 587                         amount     => $charge,
 588                         user_id    => C4::Context->userenv ? C4::Context->userenv->{'number'} : undef,
 589                         interface  => C4::Context->interface,
 590                         library_id => C4::Context->userenv ? C4::Context->userenv->{'branch'} : undef,
 591                         type       => 'RESERVE_EXPIRED',
 592                         item_id    => $self->itemnumber
 593                     }
 594                 );
 595             }
 596
 597             C4::Log::logaction( 'HOLDS', 'CANCEL', $self->reserve_id, $self )
 598                 if C4::Context->preference('HoldsLog');
 599         }
 600     );
 601     return $self;
 602 }
 603
 604 =head3 store
 605
 606 Override base store method to set default
 607 expirationdate for holds.
 608
 609 =cut
 610
 611 sub store {
 612     my ($self) = @_;
 613
 614     if ( !$self->in_storage ) {
 615         if (
 616             C4::Context->preference('DefaultHoldExpirationdate')
 617             and ( not defined $self->expirationdate
 618                 or $self->expirationdate eq '' )
 619           )
 620         {
 621             $self->_set_default_expirationdate;
 622         }
 623     }
 624     else {
 625
 626         my %updated_columns = $self->_result->get_dirty_columns;
 627         return $self->SUPER::store unless %updated_columns;
 628
 629         if ( exists $updated_columns{reservedate} ) {
 630             if (
 631                 C4::Context->preference('DefaultHoldExpirationdate')
 632                 and ( not exists $updated_columns{expirationdate}
 633                     or exists $updated_columns{expirationdate}
 634                     and $updated_columns{expirationdate} eq '' )
 635               )
 636             {
 637                 $self->_set_default_expirationdate;
 638             }
 639         }
 640     }
 641
 642     $self = $self->SUPER::store;
 643 }
 644
 645 sub _set_default_expirationdate {
 646     my $self = shift;
 647
 648     my $period = C4::Context->preference('DefaultHoldExpirationdatePeriod') || 0;
 649     my $timeunit =
 650       C4::Context->preference('DefaultHoldExpirationdateUnitOfTime') || 'days';
 651
 652     $self->expirationdate(
 653         dt_from_string( $self->reservedate )->add( $timeunit => $period ) );
 654 }
 655
 656 =head3 _move_to_old
 657
 658 my $is_moved = $hold->_move_to_old;
 659
 660 Move a hold to the old_reserve table following the same pattern as Koha::Patron->move_to_deleted
 661
 662 =cut
 663
 664 sub _move_to_old {
 665     my ($self) = @_;
 666     my $hold_infos = $self->unblessed;
 667     return Koha::Old::Hold->new( $hold_infos )->store;
 668 }
 669
 670 =head3 to_api_mapping
 671
 672 This method returns the mapping for representing a Koha::Hold object
 673 on the API.
 674
 675 =cut
 676
 677 sub to_api_mapping {
 678     return {
 679         reserve_id       => 'hold_id',
 680         borrowernumber   => 'patron_id',
 681         reservedate      => 'hold_date',
 682         biblionumber     => 'biblio_id',
 683         branchcode       => 'pickup_library_id',
 684         notificationdate => undef,
 685         reminderdate     => undef,
 686         cancellationdate => 'cancellation_date',
 687         reservenotes     => 'notes',
 688         found            => 'status',
 689         itemnumber       => 'item_id',
 690         waitingdate      => 'waiting_date',
 691         expirationdate   => 'expiration_date',
 692         lowestPriority   => 'lowest_priority',
 693         suspend          => 'suspended',
 694         suspend_until    => 'suspended_until',
 695         itemtype         => 'item_type',
 696         item_level_hold  => 'item_level',
 697     };
 698 }
 699
 700 =head2 Internal methods
 701
 702 =head3 _type
 703
 704 =cut
 705
 706 sub _type {
 707     return 'Reserve';
 708 }
 709
 710 =head1 AUTHORS
 711
 712 Kyle M Hall <kyle@bywatersolutions.com>
 713 Jonathan Druart <jonathan.druart@bugs.koha-community.org>
 714 Martin Renvoize <martin.renvoize@ptfs-europe.com>
 715
 716 =cut
 717
 718 1;