4 # Copyright 2000-2002 Katipo Communications
5 # copyright 2010 BibLibre
7 # This file is part of Koha.
9 # Koha is free software; you can redistribute it and/or modify it
10 # under the terms of the GNU General Public License as published by
11 # the Free Software Foundation; either version 3 of the License, or
12 # (at your option) any later version.
14 # Koha is distributed in the hope that it will be useful, but
15 # WITHOUT ANY WARRANTY; without even the implied warranty of
16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 # GNU General Public License for more details.
19 # You should have received a copy of the GNU General Public License
20 # along with Koha; if not, see <http://www.gnu.org/licenses>.
23 use Date::Calc qw/Today Date_to_Days/;
24 use Date::Manip qw/UnixDate/;
25 use List::MoreUtils qw( uniq );
26 use POSIX qw( floor ceil );
27 use Locale::Currency::Format 1.28;
33 use C4::Log; # logaction
36 use Koha::Account::Lines;
37 use Koha::Account::Offsets;
40 use vars qw(@ISA @EXPORT);
46 # subs to rename (and maybe merge some...)
55 &GetOverdueMessageTransportTypes
56 &parse_overdues_letter
59 # subs to move to Circulation.pm
67 C4::Circulation::Fines - Koha module dealing with fines
75 This module contains several functions for dealing with fines for
76 overdue items. It is primarily used by the 'misc/fines2.pl' script.
82 $overdues = Getoverdues( { minimumdays => 1, maximumdays => 30 } );
84 Returns the list of all overdue books, with their itemtype.
86 C<$overdues> is a reference-to-array. Each element is a
87 reference-to-hash whose keys are the fields of the issues table in the
95 my $dbh = C4::Context->dbh;
97 if ( C4::Context->preference('item-level_itypes') ) {
99 SELECT issues.*, items.itype as itemtype, items.homebranch, items.barcode, items.itemlost, items.replacementprice
101 LEFT JOIN items USING (itemnumber)
102 WHERE date_due < NOW()
106 SELECT issues.*, biblioitems.itemtype, items.itype, items.homebranch, items.barcode, items.itemlost, replacementprice
108 LEFT JOIN items USING (itemnumber)
109 LEFT JOIN biblioitems USING (biblioitemnumber)
110 WHERE date_due < NOW()
115 if ( exists $params->{'minimumdays'} and exists $params->{'maximumdays'} ) {
116 $statement .= ' AND TO_DAYS( NOW() )-TO_DAYS( date_due ) BETWEEN ? and ? ';
117 push @bind_parameters, $params->{'minimumdays'}, $params->{'maximumdays'};
118 } elsif ( exists $params->{'minimumdays'} ) {
119 $statement .= ' AND ( TO_DAYS( NOW() )-TO_DAYS( date_due ) ) > ? ';
120 push @bind_parameters, $params->{'minimumdays'};
121 } elsif ( exists $params->{'maximumdays'} ) {
122 $statement .= ' AND ( TO_DAYS( NOW() )-TO_DAYS( date_due ) ) < ? ';
123 push @bind_parameters, $params->{'maximumdays'};
125 $statement .= 'ORDER BY borrowernumber';
126 my $sth = $dbh->prepare( $statement );
127 $sth->execute( @bind_parameters );
128 return $sth->fetchall_arrayref({});
134 ($count, $overdueitems) = checkoverdues($borrowernumber);
136 Returns a count and a list of overdueitems for a given borrowernumber
141 my $borrowernumber = shift or return;
142 my $sth = C4::Context->dbh->prepare(
143 "SELECT biblio.*, items.*, issues.*,
146 biblioitems.itemtype,
149 biblioitems.publicationyear,
150 biblioitems.publishercode,
151 biblioitems.volumedate,
152 biblioitems.volumedesc,
153 biblioitems.collectiontitle,
154 biblioitems.collectionissn,
155 biblioitems.collectionvolume,
156 biblioitems.editionstatement,
157 biblioitems.editionresponsibility,
165 biblioitems.cn_source,
166 biblioitems.cn_class,
168 biblioitems.cn_suffix,
170 biblioitems.totalissues
172 LEFT JOIN items ON issues.itemnumber = items.itemnumber
173 LEFT JOIN biblio ON items.biblionumber = biblio.biblionumber
174 LEFT JOIN biblioitems ON items.biblioitemnumber = biblioitems.biblioitemnumber
175 WHERE issues.borrowernumber = ?
176 AND issues.date_due < NOW()"
178 $sth->execute($borrowernumber);
179 my $results = $sth->fetchall_arrayref({});
180 return ( scalar(@$results), $results); # returning the count and the results is silly
185 ($amount, $units_minus_grace, $chargeable_units) = &CalcFine($item,
186 $categorycode, $branch,
187 $start_dt, $end_dt );
189 Calculates the fine for a book.
191 The issuingrules table in the Koha database is a fine matrix, listing
192 the penalties for each type of patron for each type of item and each branch (e.g., the
193 standard fine for books might be $0.50, but $1.50 for DVDs, or staff
194 members might get a longer grace period between the first and second
195 reminders that a book is overdue).
198 C<$item> is an item object (hashref).
200 C<$categorycode> is the category code (string) of the patron who currently has
203 C<$branchcode> is the library (string) whose issuingrules govern this transaction.
205 C<$start_date> & C<$end_date> are DateTime objects
206 defining the date range over which to determine the fine.
208 Fines scripts should just supply the date range over which to calculate the fine.
210 C<&CalcFine> returns three values:
212 C<$amount> is the fine owed by the patron (see above).
214 C<$units_minus_grace> is the number of chargeable units minus the grace period
216 C<$chargeable_units> is the number of chargeable units (days between start and end dates, Calendar adjusted where needed,
217 minus any applicable grace period, or hours)
219 FIXME: previously attempted to return C<$message> as a text message, either "First Notice", "Second Notice",
220 or "Final Notice". But CalcFine never defined any value.
225 my ( $item, $bortype, $branchcode, $due_dt, $end_date ) = @_;
227 # Skip calculations if item is not overdue
228 return ( 0, 0, 0 ) unless (DateTime->compare( $due_dt, $end_date ) == -1);
230 my $start_date = $due_dt->clone();
231 # get issuingrules (fines part will be used)
232 my $itemtype = $item->{itemtype} || $item->{itype};
233 my $issuing_rule = Koha::CirculationRules->get_effective_rules(
235 categorycode => $bortype,
236 itemtype => $itemtype,
237 branchcode => $branchcode,
242 'chargeperiod_charge_at',
245 'cap_fine_to_replacement_price',
250 $itemtype = Koha::ItemTypes->find($itemtype);
252 return unless $issuing_rule; # If not rule exist, there is no fine
254 my $fine_unit = $issuing_rule->{lengthunit} || 'days';
256 my $chargeable_units = get_chargeable_units($fine_unit, $start_date, $end_date, $branchcode);
257 my $units_minus_grace = $chargeable_units - ($issuing_rule->{firstremind} || 0);
259 if ( $issuing_rule->{chargeperiod} && ( $units_minus_grace > 0 ) ) {
260 my $units = C4::Context->preference('FinesIncludeGracePeriod') ? $chargeable_units : $units_minus_grace;
261 my $charge_periods = $units / $issuing_rule->{chargeperiod};
262 # If chargeperiod_charge_at = 1, we charge a fine at the start of each charge period
263 # if chargeperiod_charge_at = 0, we charge at the end of each charge period
264 $charge_periods = defined $issuing_rule->{chargeperiod_charge_at} && $issuing_rule->{chargeperiod_charge_at} == 1 ? ceil($charge_periods) : floor($charge_periods);
265 $amount = $charge_periods * $issuing_rule->{fine};
266 } # else { # a zero (or null) chargeperiod or negative units_minus_grace value means no charge. }
268 $amount = $issuing_rule->{overduefinescap} if $issuing_rule->{overduefinescap} && $amount > $issuing_rule->{overduefinescap};
270 # This must be moved to Koha::Item (see also similar code in C4::Accounts::chargelostitem
271 $item->{replacementprice} ||= $itemtype->defaultreplacecost
273 && ( ! defined $item->{replacementprice} || $item->{replacementprice} == 0 )
274 && C4::Context->preference("useDefaultReplacementCost");
276 $amount = $item->{replacementprice} if ( $issuing_rule->{cap_fine_to_replacement_price} && $item->{replacementprice} && $amount > $item->{replacementprice} );
278 return ($amount, $units_minus_grace, $chargeable_units);
282 =head2 get_chargeable_units
284 get_chargeable_units($unit, $start_date_ $end_date, $branchcode);
286 return integer value of units between C<$start_date> and C<$end_date>, factoring in holidays for C<$branchcode>.
288 C<$unit> is 'days' or 'hours' (default is 'days').
290 C<$start_date> and C<$end_date> are the two DateTimes to get the number of units between.
292 C<$branchcode> is the branch whose calendar to use for finding holidays.
296 sub get_chargeable_units {
297 my ($unit, $date_due, $date_returned, $branchcode) = @_;
299 # If the due date is later than the return date
300 return 0 unless ( $date_returned > $date_due );
302 my $charge_units = 0;
304 if ($unit eq 'hours') {
305 if(C4::Context->preference('finesCalendar') eq 'noFinesWhenClosed') {
306 my $calendar = Koha::Calendar->new( branchcode => $branchcode );
307 $charge_duration = $calendar->hours_between( $date_due, $date_returned );
309 $charge_duration = $date_returned->delta_ms( $date_due );
311 if($charge_duration->in_units('hours') == 0 && $charge_duration->in_units('seconds') > 0){
314 return $charge_duration->in_units('hours');
317 if(C4::Context->preference('finesCalendar') eq 'noFinesWhenClosed') {
318 my $calendar = Koha::Calendar->new( branchcode => $branchcode );
319 $charge_duration = $calendar->days_between( $date_due, $date_returned );
321 $charge_duration = $date_returned->delta_days( $date_due );
323 return $charge_duration->in_units('days');
328 =head2 GetSpecialHolidays
330 &GetSpecialHolidays($date_dues,$itemnumber);
332 return number of special days between date of the day and date due
334 C<$date_dues> is the envisaged date of book return.
336 C<$itemnumber> is the book's item number.
340 sub GetSpecialHolidays {
341 my ( $date_dues, $itemnumber ) = @_;
343 # calcul the today date
344 my $today = join "-", &Today();
346 # return the holdingbranch
347 my $iteminfo = GetIssuesIteminfo($itemnumber);
349 # use sql request to find all date between date_due and today
350 my $dbh = C4::Context->dbh;
352 qq|SELECT DATE_FORMAT(concat(year,'-',month,'-',day),'%Y-%m-%d') as date
353 FROM `special_holidays`
354 WHERE DATE_FORMAT(concat(year,'-',month,'-',day),'%Y-%m-%d') >= ?
355 AND DATE_FORMAT(concat(year,'-',month,'-',day),'%Y-%m-%d') <= ?
358 my @result = GetWdayFromItemnumber($itemnumber);
362 my $sth = $dbh->prepare($query);
363 $sth->execute( $date_dues, $today, $iteminfo->{'branchcode'} )
364 ; # FIXME: just use NOW() in SQL instead of passing in $today
366 while ( my $special_date = $sth->fetchrow_hashref ) {
367 push( @result_date, $special_date );
370 my $specialdaycount = scalar(@result_date);
372 for ( my $i = 0 ; $i < scalar(@result_date) ; $i++ ) {
373 $dateinsec = UnixDate( $result_date[$i]->{'date'}, "%o" );
374 ( undef, undef, undef, undef, undef, undef, $wday, undef, undef ) =
375 localtime($dateinsec);
376 for ( my $j = 0 ; $j < scalar(@result) ; $j++ ) {
377 if ( $wday == ( $result[$j]->{'weekday'} ) ) {
383 return $specialdaycount;
386 =head2 GetRepeatableHolidays
388 &GetRepeatableHolidays($date_dues, $itemnumber, $difference,);
390 return number of day closed between date of the day and date due
392 C<$date_dues> is the envisaged date of book return.
394 C<$itemnumber> is item number.
396 C<$difference> numbers of between day date of the day and date due
400 sub GetRepeatableHolidays {
401 my ( $date_dues, $itemnumber, $difference ) = @_;
402 my $dateinsec = UnixDate( $date_dues, "%o" );
403 my ( $sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst ) =
404 localtime($dateinsec);
405 my @result = GetWdayFromItemnumber($itemnumber);
409 for ( my $i = 0 ; $i < scalar(@result) ; $i++ ) {
412 for ( $j = 0 ; $j < $difference ; $j++ ) {
413 if ( $result[$i]->{'weekday'} == $k ) {
414 push( @dayclosedcount, $k );
417 ( $k = 0 ) if ( $k eq 7 );
420 return scalar(@dayclosedcount);
424 =head2 GetWayFromItemnumber
426 &Getwdayfromitemnumber($itemnumber);
428 return the different week day from repeatable_holidays table
430 C<$itemnumber> is item number.
434 sub GetWdayFromItemnumber {
435 my ($itemnumber) = @_;
436 my $iteminfo = GetIssuesIteminfo($itemnumber);
438 my $query = qq|SELECT weekday
439 FROM repeatable_holidays
442 my $sth = C4::Context->dbh->prepare($query);
444 $sth->execute( $iteminfo->{'branchcode'} );
445 while ( my $weekday = $sth->fetchrow_hashref ) {
446 push( @result, $weekday );
452 =head2 GetIssuesIteminfo
454 &GetIssuesIteminfo($itemnumber);
456 return all data from issues about item
458 C<$itemnumber> is item number.
462 sub GetIssuesIteminfo {
463 my ($itemnumber) = @_;
464 my $dbh = C4::Context->dbh;
465 my $query = qq|SELECT *
469 my $sth = $dbh->prepare($query);
470 $sth->execute($itemnumber);
471 my ($issuesinfo) = $sth->fetchrow_hashref;
480 issue_id => $issue_id,
481 itemnumber => $itemnumber,
482 borrowernumber => $borrowernumber,
488 (Note: the following is mostly conjecture and guesswork.)
490 Updates the fine owed on an overdue book.
492 C<$itemnumber> is the book's item number.
494 C<$borrowernumber> is the borrower number of the patron who currently
495 has the book on loan.
497 C<$amount> is the current amount owed by the patron.
499 C<$due> is the due date formatted to the currently specified date format
501 C<&UpdateFine> looks up the amount currently owed on the given item
502 and sets it to C<$amount>, creating, if necessary, a new entry in the
503 accountlines table of the Koha database.
508 # Question: Why should the caller have to
509 # specify both the item number and the borrower number? A book can't
510 # be on loan to two different people, so the item number should be
513 # Possible Answer: You might update a fine for a damaged item, *after* it is returned.
518 my $issue_id = $params->{issue_id};
519 my $itemnum = $params->{itemnumber};
520 my $borrowernumber = $params->{borrowernumber};
521 my $amount = $params->{amount};
522 my $due = $params->{due} // q{};
524 unless ( $issue_id ) {
525 carp("No issue_id passed in!");
529 my $dbh = C4::Context->dbh;
530 my $overdues = Koha::Account::Lines->search(
532 borrowernumber => $borrowernumber,
533 debit_type_code => 'OVERDUE'
538 my $total_amount_other = 0.00;
539 my $due_qr = qr/$due/;
540 # Cycle through the fines and
541 # - find line that relates to the requested $itemnum
542 # - accumulate fines for other items
543 # so we can update $itemnum fine taking in account fine caps
544 while (my $overdue = $overdues->next) {
545 if ( defined $overdue->issue_id && $overdue->issue_id == $issue_id && $overdue->status eq 'UNRETURNED' ) {
547 Koha::Logger->get->debug("Not a unique accountlines record for issue_id $issue_id"); # FIXME Do we really need to log that?
548 #FIXME Should we still count this one in total_amount ??
551 $accountline = $overdue;
554 $total_amount_other += $overdue->amountoutstanding;
557 if ( my $maxfine = C4::Context->preference('MaxFine') ) {
558 my $maxIncrease = $maxfine - $total_amount_other;
559 return if Koha::Number::Price->new($maxIncrease)->round <= 0.00;
561 if ( ( $amount - $accountline->amount ) > $maxIncrease ) {
562 my $new_amount = $accountline->amount + $maxIncrease;
563 Koha::Logger->get->debug("Reducing fine for item $itemnum borrower $borrowernumber from $amount to $new_amount - MaxFine reached");
564 $amount = $new_amount;
567 elsif ( $amount > $maxIncrease ) {
568 Koha::Logger->get->debug("Reducing fine for item $itemnum borrower $borrowernumber from $amount to $maxIncrease - MaxFine reached");
569 $amount = $maxIncrease;
573 if ( $accountline ) {
574 if ( Koha::Number::Price->new($accountline->amount)->round != Koha::Number::Price->new($amount)->round ) {
575 $accountline->adjust(
578 type => 'overdue_update',
579 interface => C4::Context->interface
584 if ( $amount ) { # Don't add new fines with an amount of 0
585 my $sth4 = $dbh->prepare(
586 "SELECT title FROM biblio LEFT JOIN items ON biblio.biblionumber=items.biblionumber WHERE items.itemnumber=?"
588 $sth4->execute($itemnum);
589 my $title = $sth4->fetchrow;
590 my $desc = "$title $due";
592 my $account = Koha::Account->new({ patron_id => $borrowernumber });
593 $accountline = $account->add_debit(
596 description => $desc,
599 interface => C4::Context->interface,
600 library_id => undef, #FIXME: Should we grab the checkout or circ-control branch here perhaps?
603 issue_id => $issue_id,
612 $data->{'sum(amountoutstanding)'} = &GetFine($itemnum,$borrowernumber);
614 return the total of fine
616 C<$itemnum> is item number
618 C<$borrowernumber> is the borrowernumber
623 my ( $itemnum, $borrowernumber ) = @_;
624 my $dbh = C4::Context->dbh();
625 my $query = q|SELECT sum(amountoutstanding) as fineamount FROM accountlines
626 WHERE debit_type_code = 'OVERDUE'
627 AND amountoutstanding > 0 AND borrowernumber=?|;
629 push @query_param, $borrowernumber;
630 if (defined $itemnum )
632 $query .= " AND itemnumber=?";
633 push @query_param, $itemnum;
635 my $sth = $dbh->prepare($query);
636 $sth->execute( @query_param );
637 my $fine = $sth->fetchrow_hashref();
638 if ($fine->{fineamount}) {
639 return $fine->{fineamount};
644 =head2 GetBranchcodesWithOverdueRules
646 my @branchcodes = C4::Overdues::GetBranchcodesWithOverdueRules()
648 returns a list of branch codes for branches with overdue rules defined.
652 sub GetBranchcodesWithOverdueRules {
653 my $dbh = C4::Context->dbh;
654 my $branchcodes = $dbh->selectcol_arrayref(q|
655 SELECT DISTINCT(branchcode)
657 WHERE delay1 IS NOT NULL
660 if ( $branchcodes->[0] eq '' ) {
661 # If a default rule exists, all branches should be returned
662 return map { $_->branchcode } Koha::Libraries->search({}, { order_by => 'branchname' });
664 return @$branchcodes;
667 =head2 GetOverduesForBranch
669 Sql request for display all information for branchoverdues.pl
670 2 possibilities : with or without location .
671 display is filtered by branch
673 FIXME: This function should be renamed.
677 sub GetOverduesForBranch {
678 my ( $branch, $location) = @_;
679 my $itype_link = (C4::Context->preference('item-level_itypes')) ? " items.itype " : " biblioitems.itemtype ";
680 my $dbh = C4::Context->dbh;
683 borrowers.cardnumber,
684 borrowers.borrowernumber,
702 items.itemcallnumber,
705 itemtypes.description,
706 accountlines.amountoutstanding
708 LEFT JOIN issues ON issues.itemnumber = accountlines.itemnumber
709 AND issues.borrowernumber = accountlines.borrowernumber
710 LEFT JOIN borrowers ON borrowers.borrowernumber = accountlines.borrowernumber
711 LEFT JOIN items ON items.itemnumber = issues.itemnumber
712 LEFT JOIN biblio ON biblio.biblionumber = items.biblionumber
713 LEFT JOIN biblioitems ON biblioitems.biblioitemnumber = items.biblioitemnumber
714 LEFT JOIN itemtypes ON itemtypes.itemtype = $itype_link
715 LEFT JOIN branches ON branches.branchcode = issues.branchcode
716 WHERE (accountlines.amountoutstanding != '0.000000')
717 AND (accountlines.debit_type_code = 'OVERDUE' )
718 AND (accountlines.status = 'UNRETURNED' )
719 AND (issues.branchcode = ? )
720 AND (issues.date_due < NOW())
723 my $q = "$select AND items.location = ? ORDER BY borrowers.surname, borrowers.firstname";
724 return @{ $dbh->selectall_arrayref($q, { Slice => {} }, $branch, $location ) };
726 my $q = "$select ORDER BY borrowers.surname, borrowers.firstname";
727 return @{ $dbh->selectall_arrayref($q, { Slice => {} }, $branch ) };
731 =head2 GetOverdueMessageTransportTypes
733 my $message_transport_types = GetOverdueMessageTransportTypes( $branchcode, $categorycode, $letternumber);
735 return a arrayref with all message_transport_type for given branchcode, categorycode and letternumber(1,2 or 3)
739 sub GetOverdueMessageTransportTypes {
740 my ( $branchcode, $categorycode, $letternumber ) = @_;
741 return unless $categorycode and $letternumber;
742 my $dbh = C4::Context->dbh;
743 my $sth = $dbh->prepare("
744 SELECT message_transport_type
745 FROM overduerules odr LEFT JOIN overduerules_transport_types ott USING (overduerules_id)
750 $sth->execute( $branchcode, $categorycode, $letternumber );
752 while ( my $mtt = $sth->fetchrow ) {
756 # Put 'print' in first if exists
757 # It avoid to sent a print notice with an email or sms template is no email or sms is defined
758 @mtts = uniq( 'print', @mtts )
759 if grep { $_ eq 'print' } @mtts;
764 =head2 parse_overdues_letter
766 parses the letter template, replacing the placeholders with data
767 specific to this patron, biblio, or item for overdues
770 letter - required hashref
771 borrowernumber - required integer
772 substitute - optional hashref of other key/value pairs that should
773 be substituted in the letter content
775 returns the C<letter> hashref, with the content updated to reflect the
776 substituted keys and values.
780 sub parse_overdues_letter {
782 foreach my $required (qw( letter_code borrowernumber )) {
783 return unless ( exists $params->{$required} && $params->{$required} );
786 my $patron = Koha::Patrons->find( $params->{borrowernumber} );
788 my $substitute = $params->{'substitute'} || {};
790 my %tables = ( 'borrowers' => $params->{'borrowernumber'} );
791 if ( my $p = $params->{'branchcode'} ) {
792 $tables{'branches'} = $p;
795 my $active_currency = Koha::Acquisition::Currencies->get_active;
798 $currency_format = $active_currency->currency if defined($active_currency);
801 if ( my $i = $params->{'items'} ) {
802 foreach my $item (@$i) {
803 my $fine = GetFine($item->{'itemnumber'}, $params->{'borrowernumber'});
804 $item->{'fine'} = currency_format($currency_format, "$fine", FMT_SYMBOL);
805 # if active currency isn't correct ISO code fallback to sprintf
806 $item->{'fine'} = sprintf('%.2f', $fine) unless $item->{'fine'};
809 'biblio' => $item->{'biblionumber'},
810 'biblioitems' => $item->{'biblionumber'},
812 'issues' => $item->{'itemnumber'},
817 return C4::Letters::GetPreparedLetter (
818 module => 'circulation',
819 letter_code => $params->{'letter_code'},
820 branchcode => $params->{'branchcode'},
821 lang => $patron->lang,
824 overdues => [ map { $_->{items}->{itemnumber} } @item_tables ],
826 substitute => $substitute,
827 repeat => { item => \@item_tables },
828 message_transport_type => $params->{message_transport_type},
837 Koha Development Team <http://koha-community.org/>