FS/FS/cust_bill.pm

   1 package FS::cust_bill;
   2
   3 use strict;
   4 use vars qw( @ISA $conf $invoice_template $money_char );
   5 use vars qw( $invoice_lines @buf ); #yuck
   6 use Date::Format;
   7 use Text::Template;
   8 use FS::Record qw( qsearch qsearchs );
   9 use FS::cust_main;
  10 use FS::cust_bill_pkg;
  11 use FS::cust_credit;
  12 use FS::cust_pay;
  13 use FS::cust_pkg;
  14 use FS::cust_credit_bill;
  15
  16 @ISA = qw( FS::Record );
  17
  18 #ask FS::UID to run this stuff for us later
  19 $FS::UID::callback{'FS::cust_bill'} = sub {
  20
  21   $conf = new FS::Conf;
  22
  23   $money_char = $conf->config('money_char') || '$';
  24
  25   my @invoice_template = $conf->config('invoice_template')
  26     or die "cannot load config file invoice_template";
  27   $invoice_lines = 0;
  28   foreach ( grep /invoice_lines\(\d+\)/, @invoice_template ) { #kludgy
  29     /invoice_lines\((\d+)\)/;
  30     $invoice_lines += $1;
  31   }
  32   die "no invoice_lines() functions in template?" unless $invoice_lines;
  33   $invoice_template = new Text::Template (
  34     TYPE   => 'ARRAY',
  35     SOURCE => [ map "$_\n", @invoice_template ],
  36   ) or die "can't create new Text::Template object: $Text::Template::ERROR";
  37   $invoice_template->compile()
  38     or die "can't compile template: $Text::Template::ERROR";
  39 };
  40
  41 =head1 NAME
  42
  43 FS::cust_bill - Object methods for cust_bill records
  44
  45 =head1 SYNOPSIS
  46
  47   use FS::cust_bill;
  48
  49   $record = new FS::cust_bill \%hash;
  50   $record = new FS::cust_bill { 'column' => 'value' };
  51
  52   $error = $record->insert;
  53
  54   $error = $new_record->replace($old_record);
  55
  56   $error = $record->delete;
  57
  58   $error = $record->check;
  59
  60   ( $total_previous_balance, @previous_cust_bill ) = $record->previous;
  61
  62   @cust_bill_pkg_objects = $cust_bill->cust_bill_pkg;
  63
  64   ( $total_previous_credits, @previous_cust_credit ) = $record->cust_credit;
  65
  66   @cust_pay_objects = $cust_bill->cust_pay;
  67
  68   $tax_amount = $record->tax;
  69
  70   @lines = $cust_bill->print_text;
  71   @lines = $cust_bill->print_text $time;
  72
  73 =head1 DESCRIPTION
  74
  75 An FS::cust_bill object represents an invoice; a declaration that a customer
  76 owes you money.  The specific charges are itemized as B<cust_bill_pkg> records
  77 (see L<FS::cust_bill_pkg>).  FS::cust_bill inherits from FS::Record.  The
  78 following fields are currently supported:
  79
  80 =over 4
  81
  82 =item invnum - primary key (assigned automatically for new invoices)
  83
  84 =item custnum - customer (see L<FS::cust_main>)
  85
  86 =item _date - specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
  87 L<Time::Local> and L<Date::Parse> for conversion functions.
  88
  89 =item charged - amount of this invoice
  90
  91 =item printed - how many times this invoice has been printed automatically
  92 (see L<FS::cust_main/"collect">).
  93
  94 =back
  95
  96 =head1 METHODS
  97
  98 =over 4
  99
 100 =item new HASHREF
 101
 102 Creates a new invoice.  To add the invoice to the database, see L<"insert">.
 103 Invoices are normally created by calling the bill method of a customer object
 104 (see L<FS::cust_main>).
 105
 106 =cut
 107
 108 sub table { 'cust_bill'; }
 109
 110 =item insert
 111
 112 Adds this invoice to the database ("Posts" the invoice).  If there is an error,
 113 returns the error, otherwise returns false.
 114
 115 =item delete
 116
 117 Currently unimplemented.  I don't remove invoices because there would then be
 118 no record you ever posted this invoice (which is bad, no?)
 119
 120 =cut
 121
 122 sub delete {
 123   return "Can't remove invoice!"
 124 }
 125
 126 =item replace OLD_RECORD
 127
 128 Replaces the OLD_RECORD with this one in the database.  If there is an error,
 129 returns the error, otherwise returns false.
 130
 131 Only printed may be changed.  printed is normally updated by calling the
 132 collect method of a customer object (see L<FS::cust_main>).
 133
 134 =cut
 135
 136 sub replace {
 137   my( $new, $old ) = ( shift, shift );
 138   return "Can't change custnum!" unless $old->custnum == $new->custnum;
 139   #return "Can't change _date!" unless $old->_date eq $new->_date;
 140   return "Can't change _date!" unless $old->_date == $new->_date;
 141   return "Can't change charged!" unless $old->charged == $new->charged;
 142
 143   $new->SUPER::replace($old);
 144 }
 145
 146 =item check
 147
 148 Checks all fields to make sure this is a valid invoice.  If there is an error,
 149 returns the error, otherwise returns false.  Called by the insert and replace
 150 methods.
 151
 152 =cut
 153
 154 sub check {
 155   my $self = shift;
 156
 157   my $error =
 158     $self->ut_numbern('invnum')
 159     || $self->ut_number('custnum')
 160     || $self->ut_numbern('_date')
 161     || $self->ut_money('charged')
 162     || $self->ut_numbern('printed')
 163   ;
 164   return $error if $error;
 165
 166   return "Unknown customer"
 167     unless qsearchs( 'cust_main', { 'custnum' => $self->custnum } );
 168
 169   $self->_date(time) unless $self->_date;
 170
 171   $self->printed(0) if $self->printed eq '';
 172
 173   ''; #no error
 174 }
 175
 176 =item previous
 177
 178 Returns a list consisting of the total previous balance for this customer,
 179 followed by the previous outstanding invoices (as FS::cust_bill objects also).
 180
 181 =cut
 182
 183 sub previous {
 184   my $self = shift;
 185   my $total = 0;
 186   my @cust_bill = sort { $a->_date <=> $b->_date }
 187     grep { $_->owed != 0 && $_->_date < $self->_date }
 188       qsearch( 'cust_bill', { 'custnum' => $self->custnum } )
 189   ;
 190   foreach ( @cust_bill ) { $total += $_->owed; }
 191   $total, @cust_bill;
 192 }
 193
 194 =item cust_bill_pkg
 195
 196 Returns the line items (see L<FS::cust_bill_pkg>) for this invoice.
 197
 198 =cut
 199
 200 sub cust_bill_pkg {
 201   my $self = shift;
 202   qsearch( 'cust_bill_pkg', { 'invnum' => $self->invnum } );
 203 }
 204
 205 =item cust_credit
 206
 207 Depreciated.  See the cust_credited method.
 208
 209  #Returns a list consisting of the total previous credited (see
 210  #L<FS::cust_credit>) and unapplied for this customer, followed by the previous
 211  #outstanding credits (FS::cust_credit objects).
 212
 213 =cut
 214
 215 sub cust_credit {
 216   use Carp;
 217   croak "FS::cust_bill->cust_credit depreciated; see ".
 218         "FS::cust_bill->cust_credit_bill";
 219   #my $self = shift;
 220   #my $total = 0;
 221   #my @cust_credit = sort { $a->_date <=> $b->_date }
 222   #  grep { $_->credited != 0 && $_->_date < $self->_date }
 223   #    qsearch('cust_credit', { 'custnum' => $self->custnum } )
 224   #;
 225   #foreach (@cust_credit) { $total += $_->credited; }
 226   #$total, @cust_credit;
 227 }
 228
 229 =item cust_pay
 230
 231 Depreciated.  See the cust_bill_pay method.
 232
 233 #Returns all payments (see L<FS::cust_pay>) for this invoice.
 234
 235 =cut
 236
 237 sub cust_pay {
 238   use Carp;
 239   croak "FS::cust_bill->cust_pay depreciated; see FS::cust_bill->cust_bill_pay";
 240   #my $self = shift;
 241   #sort { $a->_date <=> $b->_date }
 242   #  qsearch( 'cust_pay', { 'invnum' => $self->invnum } )
 243   #;
 244 }
 245
 246 =item cust_bill_pay
 247
 248 Returns all payment applications (see L<FS::cust_bill_pay>) for this invoice.
 249
 250 =cut
 251
 252 sub cust_bill_pay {
 253   my $self = shift;
 254   sort { $a->_date <=> $b->date }
 255     qsearch( 'cust_bill_pay', { 'invnum' => $self->invnum } );
 256 }
 257
 258 =item cust_credited
 259
 260 Returns all applied credits (see L<FS::cust_credit_bill>) for this invoice.
 261
 262 =cut
 263
 264 sub cust_credited {
 265   my $self = shift;
 266   sort { $a->_date <=> $b->_date }
 267     qsearch( 'cust_credit_bill', { 'invnum' => $self->invnum } )
 268   ;
 269 }
 270
 271 =item tax
 272
 273 Returns the tax amount (see L<FS::cust_bill_pkg>) for this invoice.
 274
 275 =cut
 276
 277 sub tax {
 278   my $self = shift;
 279   my $total = 0;
 280   my @taxlines = qsearch( 'cust_bill_pkg', { 'invnum' => $self->invnum ,
 281                                              'pkgnum' => 0 } );
 282   foreach (@taxlines) { $total += $_->setup; }
 283   $total;
 284 }
 285
 286 =item owed
 287
 288 Returns the amount owed (still outstanding) on this invoice, which is charged
 289 minus all payment applications (see L<FS::cust_bill_pay>) and credit
 290 applications (see L<FS::cust_credit_bill>).
 291
 292 =cut
 293
 294 sub owed {
 295   my $self = shift;
 296   my $balance = $self->charged;
 297   $balance -= $_->amount foreach ( $self->cust_bill_pay );
 298   $balance -= $_->amount foreach ( $self->cust_credited );
 299   $balance = sprintf( "%.2f", $balance);
 300 }
 301
 302 =item print_text [TIME];
 303
 304 Returns an text invoice, as a list of lines.
 305
 306 TIME an optional value used to control the printing of overdue messages.  The
 307 default is now.  It isn't the date of the invoice; that's the `_date' field.
 308 It is specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
 309 L<Time::Local> and L<Date::Parse> for conversion functions.
 310
 311 =cut
 312
 313 sub print_text {
 314
 315   my( $self, $today ) = ( shift, shift );
 316   $today ||= time;
 317 #  my $invnum = $self->invnum;
 318   my $cust_main = qsearchs('cust_main', { 'custnum', $self->custnum } );
 319   $cust_main->payname( $cust_main->first. ' '. $cust_main->getfield('last') )
 320     unless $cust_main->payname;
 321
 322   my( $pr_total, @pr_cust_bill ) = $self->previous; #previous balance
 323 #  my( $cr_total, @cr_cust_credit ) = $self->cust_credit; #credits
 324   #my $balance_due = $self->owed + $pr_total - $cr_total;
 325   my $balance_due = $self->owed + $pr_total;
 326
 327   #my @collect = ();
 328   #my($description,$amount);
 329   @buf = ();
 330
 331   #previous balance
 332   foreach ( @pr_cust_bill ) {
 333     push @buf, [
 334       "Previous Balance, Invoice #". $_->invnum.
 335                  " (". time2str("%x",$_->_date). ")",
 336       $money_char. sprintf("%10.2f",$_->owed)
 337     ];
 338   }
 339   if (@pr_cust_bill) {
 340     push @buf,['','-----------'];
 341     push @buf,[ 'Total Previous Balance',
 342                 $money_char. sprintf("%10.2f",$pr_total ) ];
 343     push @buf,['',''];
 344   }
 345
 346   #new charges
 347   foreach ( $self->cust_bill_pkg ) {
 348
 349     if ( $_->pkgnum ) {
 350
 351       my($cust_pkg)=qsearchs('cust_pkg', { 'pkgnum', $_->pkgnum } );
 352       my($part_pkg)=qsearchs('part_pkg',{'pkgpart'=>$cust_pkg->pkgpart});
 353       my($pkg)=$part_pkg->pkg;
 354
 355       if ( $_->setup != 0 ) {
 356         push @buf, [ "$pkg Setup", $money_char. sprintf("%10.2f",$_->setup) ];
 357         push @buf,
 358           map { [ "  ". $_->[0]. ": ". $_->[1], '' ] } $cust_pkg->labels;
 359       }
 360
 361       if ( $_->recur != 0 ) {
 362         push @buf, [
 363           "$pkg (" . time2str("%x",$_->sdate) . " - " .
 364                                 time2str("%x",$_->edate) . ")",
 365           $money_char. sprintf("%10.2f",$_->recur)
 366         ];
 367         push @buf,
 368           map { [ "  ". $_->[0]. ": ". $_->[1], '' ] } $cust_pkg->labels;
 369       }
 370
 371     } else { #pkgnum Tax
 372       push @buf,["Tax", $money_char. sprintf("%10.2f",$_->setup) ]
 373         if $_->setup != 0;
 374     }
 375   }
 376
 377   push @buf,['','-----------'];
 378   push @buf,['Total New Charges',
 379              $money_char. sprintf("%10.2f",$self->charged) ];
 380   push @buf,['',''];
 381
 382   push @buf,['','-----------'];
 383   push @buf,['Total Charges',
 384              $money_char. sprintf("%10.2f",$self->charged + $pr_total) ];
 385   push @buf,['',''];
 386
 387   #credits
 388   foreach ( $self->cust_credited ) {
 389
 390     #something more elaborate if $_->amount ne $_->cust_credit->credited ?
 391
 392     push @buf,[
 393       "Credit #". $_->crednum. " (". time2str("%x",$_->cust_credit->_date) .")",
 394       $money_char. sprintf("%10.2f",$_->amount)
 395     ];
 396   }
 397   #foreach ( @cr_cust_credit ) {
 398   #  push @buf,[
 399   #    "Credit #". $_->crednum. " (" . time2str("%x",$_->_date) .")",
 400   #    $money_char. sprintf("%10.2f",$_->credited)
 401   #  ];
 402   #}
 403
 404   #get & print payments
 405   foreach ( $self->cust_bill_pay ) {
 406
 407     #something more elaborate if $_->amount ne ->cust_pay->paid ?
 408
 409     push @buf,[
 410       "Payment received ". time2str("%x",$_->cust_pay->_date ),
 411       $money_char. sprintf("%10.2f",$_->amount )
 412     ];
 413   }
 414
 415   #balance due
 416   push @buf,['','-----------'];
 417   push @buf,['Balance Due', $money_char.
 418     sprintf("%10.2f", $balance_due ) ];
 419
 420   #setup template variables
 421
 422   package FS::cust_bill::_template; #!
 423   use vars qw( $invnum $date $page $total_pages @address $overdue @buf );
 424
 425   $invnum = $self->invnum;
 426   $date = $self->_date;
 427   $page = 1;
 428
 429   $total_pages =
 430     int( scalar(@FS::cust_bill::buf) / $FS::cust_bill::invoice_lines );
 431   $total_pages++
 432     if scalar(@FS::cust_bill::buf) % $FS::cust_bill::invoice_lines;
 433
 434
 435   #format address (variable for the template)
 436   my $l = 0;
 437   @address = ( '', '', '', '', '', '' );
 438   package FS::cust_bill; #!
 439   $FS::cust_bill::_template::address[$l++] =
 440     $cust_main->payname.
 441       ( ( $cust_main->payby eq 'BILL' ) && $cust_main->payinfo
 442         ? " (P.O. #". $cust_main->payinfo. ")"
 443         : ''
 444       )
 445   ;
 446   $FS::cust_bill::_template::address[$l++] = $cust_main->company
 447     if $cust_main->company;
 448   $FS::cust_bill::_template::address[$l++] = $cust_main->address1;
 449   $FS::cust_bill::_template::address[$l++] = $cust_main->address2
 450     if $cust_main->address2;
 451   $FS::cust_bill::_template::address[$l++] =
 452     $cust_main->city. ", ". $cust_main->state. "  ".  $cust_main->zip;
 453   $FS::cust_bill::_template::address[$l++] = $cust_main->country
 454     unless $cust_main->country eq 'US';
 455
 456   #overdue? (variable for the template)
 457   $FS::cust_bill::_template::overdue = (
 458     $balance_due > 0
 459     && $today > $self->_date
 460 #    && $self->printed > 1
 461     && $self->printed > 0
 462   );
 463
 464   #and subroutine for the template
 465
 466   sub FS::cust_bill::_template::invoice_lines {
 467     my $lines = shift;
 468     map {
 469       scalar(@buf) ? shift @buf : [ '', '' ];
 470     }
 471     ( 1 .. $lines );
 472   }
 473
 474   $FS::cust_bill::_template::page = 1;
 475   my $lines;
 476   my @collect;
 477   while (@buf) {
 478     push @collect, split("\n",
 479       $invoice_template->fill_in( PACKAGE => 'FS::cust_bill::_template' )
 480     );
 481     $FS::cust_bill::_template::page++;
 482   }
 483
 484   map "$_\n", @collect;
 485
 486 }
 487
 488 =back
 489
 490 =head1 VERSION
 491
 492 $Id: cust_bill.pm,v 1.11 2001-09-03 22:07:38 ivan Exp $
 493
 494 =head1 BUGS
 495
 496 The delete method.
 497
 498 print_text formatting (and some logic :/) is in source, but needs to be
 499 slurped in from a file.  Also number of lines ($=).
 500
 501 missing print_ps for a nice postscript copy (maybe HylaFAX-cover-page-style
 502 or something similar so the look can be completely customized?)
 503
 504 =head1 SEE ALSO
 505
 506 L<FS::Record>, L<FS::cust_main>, L<FS::cust_bill_pay>, L<FS:;cust_pay>,
 507 L<FS::cust_bill_pkg>, L<FS::cust_bill_credit>, schema.html from the base
 508 documentation.
 509
 510 =cut
 511
 512 1;
 513