FS/FS/Template_Mixin.pm

   1 package FS::Template_Mixin;
   2
   3 use strict;
   4 use vars qw( $DEBUG $me
   5              $money_char
   6              $date_format
   7            );
   8              # but NOT $conf
   9 use vars qw( $invoice_lines @buf ); #yuck
  10 use List::Util qw(sum); #can't import first, it conflicts with cust_main.first
  11 use Date::Format;
  12 use Date::Language;
  13 use Time::Local qw( timelocal );
  14 use Text::Template 1.20;
  15 use File::Temp 0.14;
  16 use Archive::Zip qw( :ERROR_CODES :CONSTANTS );
  17 use IO::Scalar;
  18 use HTML::Entities;
  19 use Cwd;
  20 use FS::UID;
  21 use FS::Misc qw( send_email );
  22 use FS::Record qw( qsearch qsearchs dbh );
  23 use FS::Conf;
  24 use FS::Misc qw( generate_ps generate_pdf );
  25 use FS::pkg_category;
  26 use FS::pkg_class;
  27 use FS::invoice_mode;
  28 use FS::L10N;
  29
  30 $DEBUG = 0;
  31 $me = '[FS::Template_Mixin]';
  32 FS::UID->install_callback( sub {
  33   my $conf = new FS::Conf; #global
  34   $money_char  = $conf->config('money_char')  || '$';
  35   $date_format = $conf->config('date_format') || '%x'; #/YY
  36 } );
  37
  38 =item conf [ MODE ]
  39
  40 Returns a configuration handle (L<FS::Conf>) set to the customer's locale.
  41
  42 If the "mode" pseudo-field is set on the object, the configuration handle
  43 will be an L<FS::invoice_conf> for that invoice mode (and the customer's
  44 locale).
  45
  46 =cut
  47
  48 sub conf {
  49   my $self = shift;
  50   my $mode = $self->get('mode');
  51   if ($self->{_conf} and !defined($mode)) {
  52     return $self->{_conf};
  53   }
  54
  55   my $cust_main = $self->cust_main;
  56   my $locale = $cust_main ? $cust_main->locale : '';
  57   my $conf;
  58   if ( $mode ) {
  59     if ( ref $mode and $mode->isa('FS::invoice_mode') ) {
  60       $mode = $mode->modenum;
  61     } elsif ( $mode =~ /\D/ ) {
  62       die "invalid invoice mode $mode";
  63     }
  64     $conf = qsearchs('invoice_conf', { modenum => $mode, locale => $locale });
  65     if (!$conf) {
  66       $conf = qsearchs('invoice_conf', { modenum => $mode, locale => '' });
  67       # it doesn't have a locale, but system conf still might
  68       $conf->set('locale' => $locale) if $conf;
  69     }
  70   }
  71   # if $mode is unspecified, or if there is no invoice_conf matching this mode
  72   # and locale, then use the system config only (but with the locale)
  73   $conf ||= FS::Conf->new({ 'locale' => $locale });
  74   # cache it
  75   return $self->{_conf} = $conf;
  76 }
  77
  78 =item print_text OPTIONS
  79
  80 Returns an text invoice, as a list of lines.
  81
  82 Options can be passed as a hash.
  83
  84 I<time>, if specified, is used to control the printing of overdue messages.  The
  85 default is now.  It isn't the date of the invoice; that's the `_date' field.
  86 It is specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
  87 L<Time::Local> and L<Date::Parse> for conversion functions.
  88
  89 I<template>, if specified, is the name of a suffix for alternate invoices.
  90
  91 I<notice_name>, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
  92
  93 =cut
  94
  95 sub print_text {
  96   my $self = shift;
  97   my %params;
  98   if ( ref($_[0]) ) {
  99     %params = %{ shift() };
 100   } else {
 101     %params = @_;
 102   }
 103
 104   $params{'format'} = 'template'; # for some reason
 105
 106   $self->print_generic( %params );
 107 }
 108
 109 =item print_latex HASHREF
 110
 111 Internal method - returns a filename of a filled-in LaTeX template for this
 112 invoice (Note: add ".tex" to get the actual filename), and a filename of
 113 an associated logo (with the .eps extension included).
 114
 115 See print_ps and print_pdf for methods that return PostScript and PDF output.
 116
 117 Options can be passed as a hash.
 118
 119 I<time>, if specified, is used to control the printing of overdue messages.  The
 120 default is now.  It isn't the date of the invoice; that's the `_date' field.
 121 It is specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
 122 L<Time::Local> and L<Date::Parse> for conversion functions.
 123
 124 I<template>, if specified, is the name of a suffix for alternate invoices.
 125 This is strongly deprecated; see L<FS::invoice_conf> for the right way to
 126 customize invoice templates for different purposes.
 127
 128 I<notice_name>, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
 129
 130 =cut
 131
 132 sub print_latex {
 133   my $self = shift;
 134   my %params;
 135
 136   if ( ref($_[0]) ) {
 137     %params = %{ shift() };
 138   } else {
 139     %params = @_;
 140   }
 141
 142   $params{'format'} = 'latex';
 143   my $conf = $self->conf;
 144
 145   # this needs to go away
 146   my $template = $params{'template'};
 147   # and this especially
 148   $template ||= $self->_agent_template
 149     if $self->can('_agent_template');
 150
 151   #the new way
 152   $self->set('mode', $params{mode})
 153     if $params{mode};
 154
 155   my $pkey = $self->primary_key;
 156   my $tmp_template = $self->table. '.'. $self->$pkey. '.XXXXXXXX';
 157
 158   my $dir = $FS::UID::conf_dir. "/cache.". $FS::UID::datasrc;
 159   my $lh = new File::Temp(
 160     TEMPLATE => $tmp_template,
 161     DIR      => $dir,
 162     SUFFIX   => '.eps',
 163     UNLINK   => 0,
 164   ) or die "can't open temp file: $!\n";
 165
 166   my $agentnum = $self->agentnum;
 167
 168   if ( $template && $conf->exists("logo_${template}.eps", $agentnum) ) {
 169     print $lh $conf->config_binary("logo_${template}.eps", $agentnum)
 170       or die "can't write temp file: $!\n";
 171   } else {
 172     print $lh $conf->config_binary('logo.eps', $agentnum)
 173       or die "can't write temp file: $!\n";
 174   }
 175   close $lh;
 176   $params{'logo_file'} = $lh->filename;
 177
 178   if( $conf->exists('invoice-barcode')
 179         && $self->can('invoice_barcode')
 180         && $self->invnum ) { # don't try to barcode statements
 181       my $png_file = $self->invoice_barcode($dir);
 182       my $eps_file = $png_file;
 183       $eps_file =~ s/\.png$/.eps/g;
 184       $png_file =~ /(barcode.*png)/;
 185       $png_file = $1;
 186       $eps_file =~ /(barcode.*eps)/;
 187       $eps_file = $1;
 188
 189       my $curr_dir = cwd();
 190       chdir($dir);
 191       # after painfuly long experimentation, it was determined that sam2p won't
 192       # accept : and other chars in the path, no matter how hard I tried to
 193       # escape them, hence the chdir (and chdir back, just to be safe)
 194       system('sam2p', '-j:quiet', $png_file, 'EPS:', $eps_file ) == 0
 195         or die "sam2p failed: $!\n";
 196       unlink($png_file);
 197       chdir($curr_dir);
 198
 199       $params{'barcode_file'} = $eps_file;
 200   }
 201
 202   my @filled_in = $self->print_generic( %params );
 203
 204   my $fh = new File::Temp( TEMPLATE => $tmp_template,
 205                            DIR      => $dir,
 206                            SUFFIX   => '.tex',
 207                            UNLINK   => 0,
 208                          ) or die "can't open temp file: $!\n";
 209   binmode($fh, ':utf8'); # language support
 210   print $fh join('', @filled_in );
 211   close $fh;
 212
 213   $fh->filename =~ /^(.*).tex$/ or die "unparsable filename: ". $fh->filename;
 214   return ($1, $params{'logo_file'}, $params{'barcode_file'});
 215
 216 }
 217
 218 sub agentnum {
 219   my $self = shift;
 220   my $cust_main = $self->cust_main;
 221   $cust_main ? $cust_main->agentnum : $self->prospect_main->agentnum;
 222 }
 223
 224 =item print_generic OPTION => VALUE ...
 225
 226 Internal method - returns a filled-in template for this invoice as a scalar.
 227
 228 See print_ps and print_pdf for methods that return PostScript and PDF output.
 229
 230 Required options
 231
 232 =over 4
 233
 234 =item format
 235
 236 The B<format> option is required and should be set to html, latex (print and PDF) or template (plaintext).
 237
 238 =back
 239
 240 Additional options
 241
 242 =over 4
 243
 244 =item notice_name
 245
 246 Overrides "Invoice" as the name of the sent document.
 247
 248 =item today
 249
 250 Used to control the printing of overdue messages.  The
 251 default is now.  It isn't the date of the invoice; that's the `_date' field.
 252 It is specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
 253 L<Time::Local> and L<Date::Parse> for conversion functions.
 254
 255 =item logo_file
 256
 257 Logo file (path to temporary EPS file on the local filesystem)
 258
 259 =item cid
 260
 261 CID for inline (emailed) images (logo)
 262
 263 =item locale
 264
 265 Override customer's locale
 266
 267 =item unsquelch_cdr
 268
 269 Overrides any per customer cdr squelching when true
 270
 271 =item no_number
 272
 273 Supress the (invoice, quotation, statement, etc.) number
 274
 275 =item no_date
 276
 277 Supress the date
 278
 279 =item no_coupon
 280
 281 Supress the payment coupon
 282
 283 =item barcode_file
 284
 285 Barcode file (path to temporary EPS file on the local filesystem)
 286
 287 =item barcode_img
 288
 289 Flag indicating the barcode image should be a link (normal HTML dipaly)
 290
 291 =item barcode_cid
 292
 293 Barcode CID for inline (emailed) images
 294
 295 =item preref_callback
 296
 297 Coderef run for each line item, code should return HTML to be displayed
 298 before that line item (quotations only)
 299
 300 =item template
 301
 302 Deprecated.  Used as a suffix for a configuration template.  Please
 303 don't use this, it deprecated in favor of more flexible alternatives.
 304
 305 =back
 306
 307 =cut
 308
 309 #what's with all the sprintf('%10.2f')'s in here?  will it cause any
 310 # (alignment in text invoice?) problems to change them all to '%.2f' ?
 311 # yes: fixed width/plain text printing will be borked
 312 sub print_generic {
 313   my( $self, %params ) = @_;
 314   my $conf = $self->conf;
 315
 316   my $today = $params{today} ? $params{today} : time;
 317   warn "$me print_generic called on $self with suffix $params{template}\n"
 318     if $DEBUG;
 319
 320   my $format = $params{format};
 321   die "Unknown format: $format"
 322     unless $format =~ /^(latex|html|template)$/;
 323
 324   my $cust_main = $self->cust_main || $self->prospect_main;
 325
 326   my $locale = $params{'locale'} || $cust_main->locale;
 327
 328   my %delimiters = ( 'latex'    => [ '[@--', '--@]' ],
 329                      'html'     => [ '<%=', '%>' ],
 330                      'template' => [ '{', '}' ],
 331                    );
 332
 333   warn "$me print_generic creating template\n"
 334     if $DEBUG > 1;
 335
 336   # set the notice name here, and nowhere else.
 337   my $notice_name =  $params{notice_name}
 338                   || $conf->config('notice_name')
 339                   || $self->notice_name;
 340
 341   #create the template
 342   my $template = $params{template} ? $params{template} : $self->_agent_template;
 343   my $templatefile = $self->template_conf. $format;
 344   $templatefile .= "_$template"
 345     if length($template) && $conf->exists($templatefile."_$template");
 346
 347   $self->set('_template',$template);
 348
 349   # the base template
 350   my @invoice_template = map "$_\n", $conf->config($templatefile)
 351     or die "cannot load config data $templatefile";
 352
 353   if ( $format eq 'latex' && grep { /^%%Detail/ } @invoice_template ) {
 354     #change this to a die when the old code is removed
 355     # it's been almost ten years, changing it to a die
 356     die "old-style invoice template $templatefile; ".
 357          "patch with conf/invoice_latex.diff or use new conf/invoice_latex*\n";
 358          #$old_latex = 'true';
 359          #@invoice_template = _translate_old_latex_format(@invoice_template);
 360   }
 361
 362   warn "$me print_generic creating T:T object\n"
 363     if $DEBUG > 1;
 364
 365   my $text_template = new Text::Template(
 366     TYPE => 'ARRAY',
 367     SOURCE => \@invoice_template,
 368     DELIMITERS => $delimiters{$format},
 369   );
 370
 371   warn "$me print_generic compiling T:T object\n"
 372     if $DEBUG > 1;
 373
 374   $text_template->compile()
 375     or die "Can't compile $templatefile: $Text::Template::ERROR\n";
 376
 377
 378   # additional substitution could possibly cause breakage in existing templates
 379   my %convert_maps = (
 380     'latex' => {
 381                  'notes'         => sub { map "$_", @_ },
 382                  'footer'        => sub { map "$_", @_ },
 383                  'smallfooter'   => sub { map "$_", @_ },
 384                  'returnaddress' => sub { map "$_", @_ },
 385                  'coupon'        => sub { map "$_", @_ },
 386                  'summary'       => sub { map "$_", @_ },
 387                },
 388     'html'  => {
 389                  'notes' =>
 390                    sub {
 391                      map {
 392                        s/%%(.*)$/<!-- $1 -->/g;
 393                        s/\\section\*\{\\textsc\{(.)(.*)\}\}/<p><b><font size="+1">$1<\/font>\U$2<\/b>/g;
 394                        s/\\begin\{enumerate\}/<ol>/g;
 395                        s/\\item /  <li>/g;
 396                        s/\\end\{enumerate\}/<\/ol>/g;
 397                        s/\\textbf\{(.*)\}/<b>$1<\/b>/g;
 398                        s/\\\\\*/<br>/g;
 399                        s/\\dollar ?/\$/g;
 400                        s/\\#/#/g;
 401                        s/~/&nbsp;/g;
 402                        $_;
 403                      }  @_
 404                    },
 405                  'footer' =>
 406                    sub { map { s/~/&nbsp;/g; s/\\\\\*?\s*$/<BR>/; $_; } @_ },
 407                  'smallfooter' =>
 408                    sub { map { s/~/&nbsp;/g; s/\\\\\*?\s*$/<BR>/; $_; } @_ },
 409                  'returnaddress' =>
 410                    sub {
 411                      map {
 412                        s/~/&nbsp;/g;
 413                        s/\\\\\*?\s*$/<BR>/;
 414                        s/\\hyphenation\{[\w\s\-]+}//;
 415                        s/\\([&])/$1/g;
 416                        $_;
 417                      }  @_
 418                    },
 419                  'coupon'        => sub { "" },
 420                  'summary'       => sub { "" },
 421                },
 422     'template' => {
 423                  'notes' =>
 424                    sub {
 425                      map {
 426                        s/%%.*$//g;
 427                        s/\\section\*\{\\textsc\{(.*)\}\}/\U$1/g;
 428                        s/\\begin\{enumerate\}//g;
 429                        s/\\item /  * /g;
 430                        s/\\end\{enumerate\}//g;
 431                        s/\\textbf\{(.*)\}/$1/g;
 432                        s/\\\\\*/ /;
 433                        s/\\dollar ?/\$/g;
 434                        $_;
 435                      }  @_
 436                    },
 437                  'footer' =>
 438                    sub { map { s/~/ /g; s/\\\\\*?\s*$/\n/; $_; } @_ },
 439                  'smallfooter' =>
 440                    sub { map { s/~/ /g; s/\\\\\*?\s*$/\n/; $_; } @_ },
 441                  'returnaddress' =>
 442                    sub {
 443                      map {
 444                        s/~/ /g;
 445                        s/\\\\\*?\s*$/\n/;             # dubious
 446                        s/\\hyphenation\{[\w\s\-]+}//;
 447                        $_;
 448                      }  @_
 449                    },
 450                  'coupon'        => sub { "" },
 451                  'summary'       => sub { "" },
 452                },
 453   );
 454
 455
 456   # hashes for differing output formats
 457   my %nbsps = ( 'latex'    => '~',
 458                 'html'     => '',    # '&nbps;' would be nice
 459                 'template' => '',    # not used
 460               );
 461   my $nbsp = $nbsps{$format};
 462
 463   my %escape_functions = ( 'latex'    => \&_latex_escape,
 464                            'html'     => \&_html_escape_nbsp,#\&encode_entities,
 465                            'template' => sub { shift },
 466                          );
 467   my $escape_function = $escape_functions{$format};
 468   my $escape_function_nonbsp = ($format eq 'html')
 469                                  ? \&_html_escape : $escape_function;
 470
 471   my %newline_tokens = (  'latex'     => '\\\\',
 472                           'html'      => '<br>',
 473                           'template'  => "\n",
 474                         );
 475   my $newline_token = $newline_tokens{$format};
 476
 477   warn "$me generating template variables\n"
 478     if $DEBUG > 1;
 479
 480   # generate template variables
 481   my $returnaddress;
 482
 483   if (
 484          defined( $conf->config_orbase( "invoice_${format}returnaddress",
 485                                         $template
 486                                       )
 487                 )
 488        && length( $conf->config_orbase( "invoice_${format}returnaddress",
 489                                         $template
 490                                       )
 491                 )
 492   ) {
 493
 494     $returnaddress = join("\n",
 495       $conf->config_orbase("invoice_${format}returnaddress", $template)
 496     );
 497
 498   } elsif ( grep /\S/,
 499             $conf->config_orbase('invoice_latexreturnaddress', $template) ) {
 500
 501     my $convert_map = $convert_maps{$format}{'returnaddress'};
 502     $returnaddress =
 503       join( "\n",
 504             &$convert_map( $conf->config_orbase( "invoice_latexreturnaddress",
 505                                                  $template
 506                                                )
 507                          )
 508           );
 509   } elsif ( grep /\S/, $conf->config('company_address', $cust_main->agentnum) ) {
 510
 511     my $convert_map = $convert_maps{$format}{'returnaddress'};
 512     $returnaddress = join( "\n", &$convert_map(
 513                                    map { s/( {2,})/'~' x length($1)/eg;
 514                                          s/$/\\\\\*/;
 515                                          $_
 516                                        }
 517                                      ( $conf->config('company_name', $cust_main->agentnum),
 518                                        $conf->config('company_address', $cust_main->agentnum),
 519                                      )
 520                                  )
 521                      );
 522
 523   } else {
 524
 525     my $warning = "Couldn't find a return address; ".
 526                   "do you need to set the company_address configuration value?";
 527     warn "$warning\n";
 528     $returnaddress = $nbsp;
 529     #$returnaddress = $warning;
 530
 531   }
 532
 533   warn "$me generating invoice data\n"
 534     if $DEBUG > 1;
 535
 536   my $agentnum = $cust_main->agentnum;
 537
 538   my %invoice_data = (
 539
 540     #invoice from info
 541     'company_name'    => scalar( $conf->config('company_name', $agentnum) ),
 542     'company_address' => join("\n", $conf->config('company_address', $agentnum) ). "\n",
 543     'company_phonenum'=> scalar( $conf->config('company_phonenum', $agentnum) ),
 544     'returnaddress'   => $returnaddress,
 545     'agent'           => &$escape_function($cust_main->agent->agent),
 546
 547     #invoice/quotation info
 548     'no_number'       => $params{'no_number'},
 549     'invnum'          => ( $params{'no_number'} ? '' : $self->invnum ),
 550     'quotationnum'    => $self->quotationnum,
 551     'no_date'         => $params{'no_date'},
 552     '_date'           => ( $params{'no_date'} ? '' : $self->_date ),
 553       # workaround for inconsistent behavior in the early plain text
 554       # templates; see RT#28271
 555     'date'            => ( $params{'no_date'}
 556                              ? ''
 557                              : ($format eq 'template'
 558                                ? $self->_date
 559                                : $self->time2str_local('long', $self->_date, $format)
 560                                )
 561                          ),
 562     'today'           => $self->time2str_local('long', $today, $format),
 563     'terms'           => $self->terms,
 564     'template'        => $template, #params{'template'},
 565     'notice_name'     => $notice_name, # escape?
 566     'current_charges' => sprintf("%.2f", $self->charged),
 567     'duedate'         => $self->due_date2str('rdate'), #date_format?
 568     'duedate_long'    => $self->due_date2str('long'),
 569
 570     #customer info
 571     'custnum'         => $cust_main->display_custnum,
 572     'prospectnum'     => $cust_main->prospectnum,
 573     'agent_custid'    => &$escape_function($cust_main->agent_custid),
 574     ( map { $_ => &$escape_function($cust_main->$_()) }
 575         qw( company address1 address2 city state zip fax )
 576     ),
 577     'payname'         => &$escape_function( $cust_main->invoice_attn
 578                                              || $cust_main->contact_firstlast ),
 579
 580     #global config
 581     'ship_enable'     => $cust_main->invoice_ship_address || $conf->exists('invoice-ship_address'),
 582     'unitprices'      => $conf->exists('invoice-unitprice'),
 583     'smallernotes'    => $conf->exists('invoice-smallernotes'),
 584     'smallerfooter'   => $conf->exists('invoice-smallerfooter'),
 585     'balance_due_below_line' => $conf->exists('balance_due_below_line'),
 586
 587     #layout info -- would be fancy to calc some of this and bury the template
 588     #               here in the code
 589     'topmargin'             => scalar($conf->config('invoice_latextopmargin', $agentnum)),
 590     'headsep'               => scalar($conf->config('invoice_latexheadsep', $agentnum)),
 591     'textheight'            => scalar($conf->config('invoice_latextextheight', $agentnum)),
 592     'extracouponspace'      => scalar($conf->config('invoice_latexextracouponspace', $agentnum)),
 593     'couponfootsep'         => scalar($conf->config('invoice_latexcouponfootsep', $agentnum)),
 594     'verticalreturnaddress' => $conf->exists('invoice_latexverticalreturnaddress', $agentnum),
 595     'addresssep'            => scalar($conf->config('invoice_latexaddresssep', $agentnum)),
 596     'amountenclosedsep'     => scalar($conf->config('invoice_latexcouponamountenclosedsep', $agentnum)),
 597     'coupontoaddresssep'    => scalar($conf->config('invoice_latexcoupontoaddresssep', $agentnum)),
 598     'addcompanytoaddress'   => $conf->exists('invoice_latexcouponaddcompanytoaddress', $agentnum),
 599
 600     # better hang on to conf_dir for a while (for old templates)
 601     'conf_dir'        => "$FS::UID::conf_dir/conf.$FS::UID::datasrc",
 602
 603     #these are only used when doing paged plaintext
 604     'page'            => 1,
 605     'total_pages'     => 1,
 606
 607   );
 608
 609   #quotations have $name
 610   $invoice_data{'name'} = $invoice_data{'payname'};
 611
 612   #localization
 613   $invoice_data{'emt'} = sub { &$escape_function($self->mt(@_)) };
 614   # prototype here to silence warnings
 615   $invoice_data{'time2str'} = sub ($;$$) { $self->time2str_local(@_, $format) };
 616
 617   my $min_sdate = 999999999999;
 618   my $max_edate = 0;
 619   foreach my $cust_bill_pkg ( $self->cust_bill_pkg ) {
 620     next unless $cust_bill_pkg->pkgnum > 0;
 621     $min_sdate = $cust_bill_pkg->sdate
 622       if length($cust_bill_pkg->sdate) && $cust_bill_pkg->sdate < $min_sdate;
 623     $max_edate = $cust_bill_pkg->edate
 624       if length($cust_bill_pkg->edate) && $cust_bill_pkg->edate > $max_edate;
 625   }
 626
 627   $invoice_data{'bill_period'} = '';
 628   $invoice_data{'bill_period'} =
 629       $self->time2str_local('%e %h', $min_sdate, $format)
 630       . " to " .
 631       $self->time2str_local('%e %h', $max_edate, $format)
 632     if ($max_edate != 0 && $min_sdate != 999999999999);
 633
 634   $invoice_data{finance_section} = '';
 635   if ( $conf->config('finance_pkgclass') ) {
 636     my $pkg_class =
 637       qsearchs('pkg_class', { classnum => $conf->config('finance_pkgclass') });
 638     $invoice_data{finance_section} = $pkg_class->categoryname;
 639   }
 640   $invoice_data{finance_amount} = '0.00';
 641   $invoice_data{finance_section} ||= 'Finance Charges'; #avoid config confusion
 642
 643   my $countrydefault = $conf->config('countrydefault') || 'US';
 644   foreach ( qw( address1 address2 city state zip country fax) ){
 645     my $method = 'ship_'.$_;
 646     $invoice_data{"ship_$_"} = $escape_function->($cust_main->$method);
 647   }
 648   if ( length($cust_main->ship_company) ) {
 649     $invoice_data{'ship_company'} = $escape_function->($cust_main->ship_company);
 650   } else {
 651     $invoice_data{'ship_company'} = $escape_function->($cust_main->company);
 652   }
 653   $invoice_data{'ship_contact'} = $escape_function->($cust_main->contact);
 654   $invoice_data{'ship_country'} = ''
 655     if ( $invoice_data{'ship_country'} eq $countrydefault );
 656
 657   $invoice_data{'cid'} = $params{'cid'}
 658     if $params{'cid'};
 659
 660   if ( $cust_main->bill_locationnum
 661        && $cust_main->bill_location->country ne $countrydefault ) {
 662     $invoice_data{'country'} = &$escape_function($cust_main->bill_country_full);
 663   } else {
 664     $invoice_data{'country'} = '';
 665   }
 666
 667   my @address = ();
 668   $invoice_data{'address'} = \@address;
 669   push @address,
 670     $invoice_data{'payname'}.
 671       ( $cust_main->po_number
 672           ? " (P.O. #". $cust_main->po_number. ")"
 673           : ''
 674       )
 675   ;
 676   push @address, $cust_main->company
 677     if $cust_main->company;
 678   push @address, $cust_main->address1;
 679   push @address, $cust_main->address2
 680     if $cust_main->address2;
 681   push @address,
 682     $cust_main->city. ", ". $cust_main->state. "  ".  $cust_main->zip;
 683   push @address, $invoice_data{'country'}
 684     if $invoice_data{'country'};
 685   push @address, ''
 686     while (scalar(@address) < 5);
 687
 688   $invoice_data{'logo_file'} = $params{'logo_file'}
 689     if $params{'logo_file'};
 690   $invoice_data{'barcode_file'} = $params{'barcode_file'}
 691     if $params{'barcode_file'};
 692   $invoice_data{'barcode_img'} = $params{'barcode_img'}
 693     if $params{'barcode_img'};
 694   $invoice_data{'barcode_cid'} = $params{'barcode_cid'}
 695     if $params{'barcode_cid'};
 696
 697
 698   # re: rt:78190
 699   #   using owed_on_invoice() instead of owed() here for $balance_due
 700   #   using _items_previous_total() instead of ->previous() for $pr_total
 701   #
 702   #   owed_on_invoice() is aware of configuration flags that affect how an
 703   #     invoice is rendered.  May not return actual current balance. Will
 704   #     return balance appropriate for the invoice being rendered, based
 705   #     on which past due items, current charges, and future payments are
 706   #     displayed.
 707   #
 708   #   Going forward, usage of owed(), or bypassing cust_bill helper methods
 709   #     when generating invoice lines may lead to incorrect or misleading
 710   #     math on invoices.
 711   #
 712   #   Helper methods that are aware of invoicing conf flags:
 713   #   - owed_on_invoice          # use instead of owed()
 714   #   - _items_previous()        # use instead of previous()
 715   #   - _items_credits()         # use instead of cust_credit()
 716   #   - _items_payments()
 717   #   - _items_total()
 718   #   - _items_previous_total()  # use instead of previous()
 719   #   - _items_payments_total()
 720   #   - _items_credits_total()   # use instead of cust_credit()
 721
 722   my $pr_total    = $self->_items_previous_total();
 723
 724   my $balance_due = $self->owed_on_invoice();
 725   $invoice_data{'balance'} = sprintf("%.2f", $balance_due);
 726
 727   # flag telling this invoice to have a first-page summary
 728   my $summarypage = '';
 729
 730   if ( $self->custnum && $self->invnum ) {
 731     # XXX should be an FS::cust_bill method to set the defaults, instead
 732     # of checking the type here
 733
 734     # info from customer's last invoice before this one, for some
 735     # summary formats
 736     $invoice_data{'last_bill'} = {};
 737
 738     #    my $last_bill = $self->previous_bill;
 739     # if ( $last_bill ) {
 740
 741     # Populate template stash for previous balance and payments
 742     if ($pr_total) {
 743       # Used on summary page as "Previous Balance"
 744       $invoice_data{'true_previous_balance'} = sprintf("%.2f", $pr_total);
 745
 746       # Used on summary page as "Payments"
 747       $invoice_data{'balance_adjustments'} = sprintf("%.2f",
 748         $self->_items_payments_total() + $self->_items_credits_total()
 749         );
 750
 751       # Used in invoice template as "Previous Balance"
 752       $invoice_data{'previous_balance'} = sprintf("%.2f", $pr_total);
 753
 754       # $invoice_data{last_bill}{_date}:
 755       # Not used in default templates, but may be in use by someone
 756       #
 757       # ! May be a problem field if they are using it... this field
 758       #   stores the date of the previous invoice... it is possible to
 759       #   carry a balance, but have the immediately previous invoice paid off.
 760       #   In this case, this field might be presenting bad data?  Not
 761       #   altering the problematic behavior, because someone might be
 762       #   expecting this bad behavior in their templates for some other
 763       #   purpose, such as a "your last bill was dated %_date%"
 764       my $last_bill = $self->previous_bill;
 765       $invoice_data{'last_bill'}{'_date'}
 766         = ref $last_bill
 767         ? $last_bill->_date()
 768         : undef;
 769
 770       # $invoice_data{previous_payments}
 771       # Not used in default templates, but may be in use by someone
 772       #
 773       # Returns an array of hrefs representing payments, each with keys:
 774       #  - _date:       epoch timestamp
 775       #  - date:        text formatted date
 776       #  - amount:      money formatted amount string
 777       #  - payinfo:     string from payby_payinfo_pretty()
 778       #  - paynum:      id for cust_pay
 779       #  - description: Text description for bill line item
 780       #
 781       my @payments = $self->_items_payments();
 782       $invoice_data{previous_payments} = \@payments;
 783
 784       # $invoice_data{previous_credits}
 785       # Not used in default templates, but may be in use by someone
 786       #
 787       # Returns an array of hrefs representing credits, each with keys:
 788       #  - _date:        epoch timestamp
 789       #  - date:         text formatted date
 790       #  - amount:       money formatted amount string
 791       #  - crednum:      id for cust_credit
 792       #  - description:  Text description for bill line item
 793       #  - creditreason: reason() from cust_credit
 794       #
 795       my @credits = $self->_items_credits();
 796       $invoice_data{previous_credits} = \@credits;
 797
 798       # Populate formatted date field
 799       for my $pmt_href (@payments, @credits) {
 800         $pmt_href->{date} = $self->time2str_local(
 801           'long',
 802           $pmt_href->{_date},
 803           $format
 804         );
 805       }
 806
 807     } else {
 808       # There are no outstanding invoices    = YAPH
 809       $invoice_data{'true_previous_balance'} =
 810       $invoice_data{'balance_adjustments'}   =
 811       $invoice_data{'previous_balance'}      = '0.00';
 812       $invoice_data{'previous_payments'}     =
 813       $invoice_data{'previous_credits'} = [];
 814     }
 815
 816     # Condencing a lot of debug staements here
 817     if ($DEBUG) {
 818       warn "\$invoice_data{$_}: $invoice_data{$_}"
 819         for qw(
 820           true_previous_balance
 821           balance_adjustments
 822           previous_balance
 823           previous_payments
 824           previous_credits
 825         );
 826     }
 827
 828     if ( $conf->exists('invoice_usesummary', $agentnum) ) {
 829       $invoice_data{'summarypage'} = $summarypage = 1;
 830     }
 831
 832   } # if this is an invoice
 833
 834   warn "$me substituting variables in notes, footer, smallfooter\n"
 835     if $DEBUG > 1;
 836
 837   my $tc = $self->template_conf;
 838   my @include = ( [ $tc,        'notes' ],
 839                   [ 'invoice_', 'footer' ],
 840                   [ 'invoice_', 'smallfooter', ],
 841                   [ 'invoice_', 'watermark' ],
 842                 );
 843   push @include, [ $tc,        'coupon', ]
 844     unless $params{'no_coupon'};
 845
 846   foreach my $i (@include) {
 847
 848     # load the configuration for this sub-template
 849
 850     my($base, $include) = @$i;
 851
 852     my $inc_file = $conf->key_orbase("$base$format$include", $template);
 853
 854     my @inc_src = $conf->config($inc_file, $agentnum);
 855     if (!@inc_src) {
 856       my $converter = $convert_maps{$format}{$include};
 857       if ( $converter ) {
 858         # then attempt to convert LaTeX to the requested format
 859         $inc_file = $conf->key_orbase($base.'latex'.$include, $template);
 860         @inc_src = &$converter( $conf->config($inc_file, $agentnum) );
 861         foreach (@inc_src) {
 862           # this isn't included in the convert_maps
 863           my ($open, $close) = @{ $delimiters{$format} };
 864           s/\[\@--/$open/g;
 865           s/--\@\]/$close/g;
 866         }
 867       }
 868     } # else @inc_src is empty and that's fine
 869
 870     # make a Text::Template out of it
 871
 872     my $inc_tt = new Text::Template (
 873       TYPE       => 'ARRAY',
 874       SOURCE     => [ map "$_\n", @inc_src ],
 875       DELIMITERS => $delimiters{$format},
 876     ) or die "Can't create new Text::Template object: $Text::Template::ERROR";
 877
 878     unless ( $inc_tt->compile() ) {
 879       my $error = "Can't compile $inc_file template: $Text::Template::ERROR\n";
 880       warn $error. "Template:\n". join('', map "$_\n", @inc_src);
 881       die $error;
 882     }
 883
 884     # fill in variables
 885
 886     $invoice_data{$include} = $inc_tt->fill_in( HASH => \%invoice_data );
 887
 888     $invoice_data{$include} =~ s/\n+$//
 889       if ($format eq 'latex');
 890   }
 891
 892 # if (well, probably when) we still need PO numbers in the brave new world of
 893 # 4.x, then we'll have to add them back as their own customer fields
 894 #  # let invoices use either of these as needed
 895 #  $invoice_data{'po_num'} = ($cust_main->payby eq 'BILL')
 896 #    ? $cust_main->payinfo : '';
 897 #  $invoice_data{'po_line'} =
 898 #    (  $cust_main->payby eq 'BILL' && $cust_main->payinfo )
 899 #      ? &$escape_function($self->mt("Purchase Order #").$cust_main->payinfo)
 900 #      : $nbsp;
 901
 902   my %money_chars = ( 'latex'    => '',
 903                       'html'     => $conf->config('money_char') || '$',
 904                       'template' => '',
 905                     );
 906   my $money_char = $money_chars{$format};
 907
 908   # extremely dubious
 909   my %other_money_chars = ( 'latex'    => '\dollar ',#XXX should be a config too
 910                             'html'     => $conf->config('money_char') || '$',
 911                             'template' => '',
 912                           );
 913   my $other_money_char = $other_money_chars{$format};
 914   $invoice_data{'dollar'} = $other_money_char;
 915
 916   my %minus_signs = ( 'latex'    => '$-$',
 917                       'html'     => '&minus;',
 918                       'template' => '- ' );
 919   my $minus = $minus_signs{$format};
 920
 921   my @detail_items = ();
 922   my @total_items = ();
 923   my @buf = ();
 924   my @sections = ();
 925
 926   $invoice_data{'detail_items'} = \@detail_items;
 927   $invoice_data{'total_items'} = \@total_items;
 928   $invoice_data{'buf'} = \@buf;
 929   $invoice_data{'sections'} = \@sections;
 930
 931   warn "$me generating sections\n"
 932     if $DEBUG > 1;
 933
 934   my $unsquelched = $params{unsquelch_cdr} || $cust_main->squelch_cdr ne 'Y';
 935   my $multisection = $self->has_sections;
 936   if ( $multisection ) {
 937     $invoice_data{multisection} = $conf->config($tc.'sections_method') || 1;
 938   }
 939   my $late_sections;
 940   my $extra_sections = [];
 941   my $extra_lines = ();
 942
 943   # default section ('Charges')
 944   my $default_section = { 'description' => '',
 945                           'subtotal'    => '',
 946                           'no_subtotal' => 1,
 947                         };
 948
 949   # Previous Charges section
 950   # subtotal is the first return value from $self->previous
 951   my $previous_section;
 952   # if the invoice has major sections, or if we're summarizing previous
 953   # charges with a single line, or if we've been specifically told to put them
 954   # in a section, create a section for previous charges:
 955   if ( $multisection or
 956        $conf->exists('previous_balance-summary_only') or
 957        $conf->exists('previous_balance-section') ) {
 958
 959     $previous_section =  { 'description' => $self->mt('Previous Charges'),
 960                            'subtotal'    => $other_money_char.
 961                                             sprintf('%.2f', $pr_total),
 962                            'summarized'  => '', #why? $summarypage ? 'Y' : '',
 963                          };
 964
 965     # Include balance aging line and template variables
 966     my @aged_balances = $self->_items_aging_balances();
 967     ( $invoice_data{aged_balance_current},
 968       $invoice_data{aged_balance_30d},
 969       $invoice_data{aged_balance_60d},
 970       $invoice_data{aged_balance_90d}
 971     ) = @aged_balances;
 972
 973     if ($conf->exists('invoice_include_aging')) {
 974       $previous_section->{posttotal} = sprintf(
 975         '0 / 30 / 60 / 90 days overdue %.2f / %.2f / %.2f / %.2f',
 976         @aged_balances,
 977       );
 978     }
 979
 980   } else {
 981     # otherwise put them in the main section
 982     $previous_section = $default_section;
 983   }
 984
 985   my $adjust_section = {
 986     'description'    => $self->mt('Credits, Payments, and Adjustments'),
 987     'adjust_section' => 1,
 988     'subtotal'       => 0,   # adjusted below
 989   };
 990   my $adjust_weight = _pkg_category($adjust_section->{description})
 991                         ? _pkg_category($adjust_section->{description})->weight
 992                         : 0;
 993   $adjust_section->{'summarized'} = ''; #why? $summarypage && !$adjust_weight ? 'Y' : '';
 994   # Note: 'sort_weight' here is actually a flag telling whether there is an
 995   # explicit package category for the adjust section. If so, certain behavior
 996   # happens.
 997   $adjust_section->{'sort_weight'} = $adjust_weight;
 998
 999
1000   if ( $multisection ) {
1001     ($extra_sections, $extra_lines) =
1002       $self->_items_extra_usage_sections($escape_function_nonbsp, $format)
1003       if $conf->exists('usage_class_as_a_section', $cust_main->agentnum)
1004       && $self->can('_items_extra_usage_sections');
1005
1006     push @$extra_sections, $adjust_section if $adjust_section->{sort_weight};
1007
1008     push @detail_items, @$extra_lines if $extra_lines;
1009
1010     # the code is written so that both methods can be used together, but
1011     # we haven't yet changed the template to take advantage of that, so for
1012     # now, treat them as mutually exclusive.
1013     my %section_method = ( by_category => 1 );
1014     if ( $conf->config($tc.'sections_method') eq 'location' ) {
1015       %section_method = ( by_location => 1 );
1016     }
1017     my ($early, $late) =
1018       $self->_items_sections( 'summary' => $summarypage,
1019                               'escape'  => $escape_function_nonbsp,
1020                               'extra_sections' => $extra_sections,
1021                               'format'  => $format,
1022                               %section_method
1023                             );
1024     push @sections, @$early;
1025     $late_sections = $late;
1026
1027     if (    $conf->exists('svc_phone_sections')
1028          && $self->can('_items_svc_phone_sections')
1029        )
1030     {
1031       my ($phone_sections, $phone_lines) =
1032         $self->_items_svc_phone_sections($escape_function_nonbsp, $format);
1033       push @{$late_sections}, @$phone_sections;
1034       push @detail_items, @$phone_lines;
1035     }
1036     if ( $conf->exists('voip-cust_accountcode_cdr')
1037          && $cust_main->accountcode_cdr
1038          && $self->can('_items_accountcode_cdr')
1039        )
1040     {
1041       my ($accountcode_section, $accountcode_lines) =
1042         $self->_items_accountcode_cdr($escape_function_nonbsp,$format);
1043       if ( scalar(@$accountcode_lines) ) {
1044           push @{$late_sections}, $accountcode_section;
1045           push @detail_items, @$accountcode_lines;
1046       }
1047     }
1048   } else {# not multisection
1049     # make a default section
1050     push @sections, $default_section;
1051     # and calculate the finance charge total, since it won't get done otherwise.
1052     # and the default section total
1053     # XXX possibly finance_pkgclass should not be used in this manner?
1054     my @finance_charges;
1055     my @charges;
1056     foreach my $cust_bill_pkg ( $self->cust_bill_pkg ) {
1057       if ( $invoice_data{finance_section} and
1058         grep { $_->section eq $invoice_data{finance_section} }
1059            $cust_bill_pkg->cust_bill_pkg_display ) {
1060         # I think these are always setup fees, but just to be sure...
1061         push @finance_charges, $cust_bill_pkg->recur + $cust_bill_pkg->setup;
1062       } else {
1063         push @charges, $cust_bill_pkg->recur + $cust_bill_pkg->setup;
1064       }
1065     }
1066     $invoice_data{finance_amount} =
1067       sprintf('%.2f', sum( @finance_charges ) || 0);
1068     $default_section->{subtotal} = $other_money_char.
1069                                     sprintf('%.2f', sum( @charges ) || 0);
1070   }
1071
1072   # start setting up summary subtotals
1073   my @summary_subtotals;
1074   my $method = $conf->config('summary_subtotals_method');
1075   if ( $method and $method ne $conf->config($tc.'sections_method') ) {
1076     # then re-section them by the correct method
1077     my %section_method = ( by_category => 1 );
1078     if ( $conf->config('summary_subtotals_method') eq 'location' ) {
1079       %section_method = ( by_location => 1 );
1080     }
1081     my ($early, $late) =
1082       $self->_items_sections( 'summary' => $summarypage,
1083                               'escape'  => $escape_function_nonbsp,
1084                               'extra_sections' => $extra_sections,
1085                               'format'  => $format,
1086                               %section_method
1087                             );
1088     foreach ( @$early ) {
1089       next if $_->{subtotal} == 0;
1090       $_->{subtotal} = $other_money_char.sprintf('%.2f', $_->{subtotal});
1091       push @summary_subtotals, $_;
1092     }
1093   } else {
1094     # subtotal sectioning is the same as for the actual invoice sections
1095     @summary_subtotals = grep $_->{subtotal}, @sections;
1096   }
1097
1098   # Hereafter, push sections to both @sections and @summary_subtotals
1099   # if they belong in both places (e.g. tax section).  Late sections are
1100   # never in @summary_subtotals.
1101
1102   # previous invoice balances in the Previous Charges section if there
1103   # is one, otherwise in the main detail section
1104   # (except if summary_only is enabled, don't show them at all)
1105   if ( $self->can('_items_previous') &&
1106        $self->enable_previous &&
1107        ! $conf->exists('previous_balance-summary_only') ) {
1108
1109     warn "$me adding previous balances\n"
1110       if $DEBUG > 1;
1111
1112     foreach my $line_item ( $self->_items_previous ) {
1113
1114       my $detail = {
1115         ref             => $line_item->{'pkgnum'},
1116         pkgpart         => $line_item->{'pkgpart'},
1117         #quantity        => 1, # not really correct
1118         section         => $previous_section, # which might be $default_section
1119         description     => &$escape_function($line_item->{'description'}),
1120         ext_description => [ map { &$escape_function($_) }
1121                              @{ $line_item->{'ext_description'} || [] }
1122                            ],
1123         amount          => $money_char . $line_item->{'amount'},
1124         product_code    => $line_item->{'pkgpart'} || 'N/A',
1125       };
1126
1127       push @detail_items, $detail;
1128       push @buf, [ $detail->{'description'},
1129                    $money_char. sprintf("%10.2f", $line_item->{'amount'}),
1130                  ];
1131     }
1132
1133   }
1134
1135   if ( $pr_total && $self->enable_previous ) {
1136     push @buf, ['','-----------'];
1137     push @buf, [ $self->mt('Total Previous Balance'),
1138                  $money_char. sprintf("%10.2f", $pr_total) ];
1139     push @buf, ['',''];
1140   }
1141
1142   if ( $conf->exists('svc_phone-did-summary') && $self->can('_did_summary') ) {
1143       warn "$me adding DID summary\n"
1144         if $DEBUG > 1;
1145
1146       my ($didsummary,$minutes) = $self->_did_summary;
1147       my $didsummary_desc = 'DID Activity Summary (since last invoice)';
1148       push @detail_items,
1149        { 'description' => $didsummary_desc,
1150            'ext_description' => [ $didsummary, $minutes ],
1151        };
1152   }
1153
1154   foreach my $section (@sections, @$late_sections) {
1155
1156     # begin some normalization
1157     $section->{'subtotal'} = $section->{'amount'}
1158       if $multisection
1159          && !exists($section->{subtotal})
1160          && exists($section->{amount});
1161
1162     $invoice_data{finance_amount} = sprintf('%.2f', $section->{'subtotal'} )
1163       if ( $invoice_data{finance_section} &&
1164            $section->{'description'} eq $invoice_data{finance_section} );
1165
1166     if ( $multisection ) {
1167
1168       if ( ref($section->{'subtotal'}) ) {
1169
1170         $section->{'subtotal'} =
1171           sprintf("$other_money_char%.2f to $other_money_char%.2f",
1172                     $section->{'subtotal'}[0],
1173                     $section->{'subtotal'}[1]
1174                  );
1175
1176       } else {
1177
1178         $section->{'subtotal'} = $other_money_char.
1179                                  sprintf('%.2f', $section->{'subtotal'})
1180
1181       }
1182
1183       # continue some normalization
1184       $section->{'amount'}   = $section->{'subtotal'}
1185
1186     }
1187
1188     if ( $section->{'description'} ) {
1189       push @buf, ( [ &$escape_function($section->{'description'}), '' ],
1190                    [ '', '' ],
1191                  );
1192     }
1193
1194     warn "$me   setting options\n"
1195       if $DEBUG > 1;
1196
1197     my %options = ();
1198     $options{'section'} = $section if $multisection;
1199     $options{'section_with_taxes'} = 1
1200       if $multisection
1201       && $conf->config_bool('invoice_sections_with_taxes', $cust_main->agentnum);
1202     $options{'format'} = $format;
1203     $options{'escape_function'} = $escape_function;
1204     $options{'no_usage'} = 1 unless $unsquelched;
1205     $options{'unsquelched'} = $unsquelched;
1206     $options{'summary_page'} = $summarypage;
1207     $options{'skip_usage'} =
1208       scalar(@$extra_sections) && !grep{$section == $_} @$extra_sections;
1209     $options{'preref_callback'} = $params{'preref_callback'};
1210     $options{'disable_line_item_date_ranges'} =
1211       $conf->exists('disable_line_item_date_ranges');
1212
1213     warn "$me   searching for line items\n"
1214       if $DEBUG > 1;
1215
1216     my %section_tax_lines;
1217     my %seen_tax_lines;
1218
1219     foreach my $line_item ( $self->_items_pkg(%options),
1220                             $self->_items_fee(%options) ) {
1221
1222       # When bill is sectioned by location, fees may be displayed within the
1223       # appropriate location section.  Suppress this fee from the taxes/fees
1224       # end section, so it doesn't appear to be charged twice and make the
1225       # subtotals seem incorrect
1226       next
1227         if $line_item->{locationnum}
1228         && ref $options{section}
1229         && !exists $options{section}->{locationnum}
1230         && $self->has_sections
1231         && $conf->config($tc.'sections_method') eq 'location';
1232
1233       warn "$me     adding line item ".
1234            join(', ', map "$_=>".$line_item->{$_}, keys %$line_item). "\n"
1235         if $DEBUG > 1;
1236
1237       push @buf, ( [ $line_item->{'description'},
1238                      $money_char. sprintf("%10.2f", $line_item->{'amount'}),
1239                    ],
1240                    map { [ " ". $_, '' ] } @{$line_item->{'ext_description'}},
1241                  );
1242
1243       $line_item->{'ref'} = $line_item->{'pkgnum'};
1244       $line_item->{'product_code'} = $line_item->{'pkgpart'} || 'N/A'; # mt()?
1245       $line_item->{'section'} = $section;
1246       $line_item->{'description'} = &$escape_function($line_item->{'description'});
1247       $line_item->{'amount'} = $money_char.$line_item->{'amount'};
1248
1249       if ( length($line_item->{'unit_amount'}) ) {
1250         $line_item->{'unit_amount'} = $money_char.$line_item->{'unit_amount'};
1251       }
1252       $line_item->{'ext_description'} ||= [];
1253
1254       if ( $options{section_with_taxes} && ref $line_item->{pkg_tax} ) {
1255         for my $line_tax ( @{$ line_item->{pkg_tax} } ) {
1256
1257           # It is rarely possible for the same tax record to be presented here
1258           # multiple times.  See cust_bill_pkg::_pkg_tax_list for more info
1259           next if $seen_tax_lines{ $line_tax->{billpkgtaxlocationnum} };
1260           $seen_tax_lines{ $line_tax->{billpkgtaxlocationnum} } = 1;
1261
1262           $section_tax_lines{ $line_tax->{taxname} } += $line_tax->{amount};
1263         }
1264       }
1265
1266       push @detail_items, $line_item;
1267     }
1268
1269     # If conf flag invoice_sections_with_taxes:
1270     # - Add @detail_items for taxes into each section
1271     # - Update section subtotal to include taxes
1272     if ( $options{section_with_taxes} && %section_tax_lines ) {
1273       for my $taxname ( keys %section_tax_lines ) {
1274
1275         push @detail_items, {
1276           section => $section,
1277           amount  => sprintf($money_char."%.2f",$section_tax_lines{$taxname}),
1278           description => &$escape_function($taxname),
1279         };
1280
1281         # Append taxes to total.  If line format resembles "$5.00 to $12.00"
1282         # append to the second value.
1283
1284         if ($section->{subtotal} =~ /to/) {
1285           my @subtotal = split /\s/, $section->{subtotal};
1286           $subtotal[2] =~ s/[^\d\.]//g;
1287           $subtotal[2] = sprintf(
1288             $money_char."%.2f",
1289             ( $subtotal[2] + $section_tax_lines{$taxname} )
1290           );
1291           $section->{subtotal} = join ' ', @subtotal;
1292         } else {
1293           $section->{subtotal} =~ s/[^\d\.]//g;
1294           $section->{subtotal} = sprintf(
1295             $money_char . "%.2f",
1296             ( $section->{subtotal} + $section_tax_lines{$taxname} )
1297           );
1298         }
1299
1300       }
1301     }
1302
1303     if ( $section->{'description'} ) {
1304       push @buf, ( ['','-----------'],
1305                    [ $section->{'description'}. ' sub-total',
1306                       $section->{'subtotal'} # already formatted this
1307                    ],
1308                    [ '', '' ],
1309                    [ '', '' ],
1310                  );
1311     }
1312
1313   }
1314
1315   $invoice_data{current_less_finance} =
1316     sprintf('%.2f', $self->charged - $invoice_data{finance_amount} );
1317
1318   # if there's anything in the Previous Charges section, prepend it to the list
1319   if ( $pr_total and $previous_section ne $default_section ) {
1320     unshift @sections, $previous_section;
1321     # but not @summary_subtotals
1322   }
1323
1324   warn "$me adding taxes\n"
1325     if $DEBUG > 1;
1326
1327   # create a tax section if we don't yet have one
1328   my @items_tax = $self->_items_tax;
1329   my $tax_description = 'Taxes, Surcharges, and Fees';
1330   my $tax_section =
1331     List::Util::first { $_->{description} eq $tax_description } @sections;
1332   if (!$tax_section) {
1333     $tax_section = { 'description' => $tax_description };
1334     push @sections, $tax_section if $multisection and @items_tax > 0;
1335   }
1336   $tax_section->{tax_section} = 1; # mark this section as containing taxes
1337   # if this is an existing tax section, we're merging the tax items into it.
1338   # grab the taxtotal that's already there, strip the money symbol if any
1339   my $taxtotal = $tax_section->{'subtotal'} || 0;
1340   $taxtotal =~ s/^\Q$other_money_char\E//;
1341
1342   # this does nothing
1343   #my $tax_weight = _pkg_category($tax_section->{description})
1344   #                      ? _pkg_category($tax_section->{description})->weight
1345   #                      : 0;
1346   #$tax_section->{'summarized'} = ''; #why? $summarypage && !$tax_weight ? 'Y' : '';
1347   #$tax_section->{'sort_weight'} = $tax_weight;
1348
1349   my $invoice_sections_with_taxes = $conf->config_bool(
1350     'invoice_sections_with_taxes', $cust_main->agentnum
1351   );
1352
1353   foreach my $tax ( @items_tax ) {
1354
1355
1356     my $description = &$escape_function( $tax->{'description'} );
1357     my $amount      = sprintf( '%.2f', $tax->{'amount'} );
1358
1359     if ( $multisection ) {
1360       if ( !$invoice_sections_with_taxes ) {
1361
1362         $taxtotal += $tax->{'amount'};
1363
1364         push @detail_items, {
1365           ext_description => [],
1366           ref          => '',
1367           quantity     => '',
1368           description  => $description,
1369           amount       => $money_char. $amount,
1370           product_code => '',
1371           section      => $tax_section,
1372         };
1373
1374       }
1375     } else {
1376
1377       $taxtotal += $tax->{'amount'};
1378
1379       push @total_items, {
1380         'total_item'   => $description,
1381         'total_amount' => $other_money_char. $amount,
1382       };
1383
1384     }
1385
1386     push @buf,[ $description,
1387                 $money_char. $amount,
1388               ];
1389
1390   }
1391
1392   if ( @items_tax ) {
1393     my $total = {};
1394     $total->{'total_item'} = $self->mt('Sub-total');
1395     $total->{'total_amount'} =
1396       $other_money_char. sprintf('%.2f', $self->charged - $taxtotal );
1397
1398     if ( $multisection ) {
1399
1400       if ( $conf->config_bool('invoice_sections_with_taxes', $cust_main->agentnum) ) {
1401         # If all tax items are displayed in location/category sections,
1402         # remove the empty tax section
1403         @sections = grep{ $_ ne $tax_section } @sections
1404           unless grep{ $_->{section} eq $tax_section } @detail_items;
1405       }
1406
1407       if ( $taxtotal > 0 ) {
1408         # there are taxes, so prepare the section to be displayed.
1409         # $taxtotal already includes any line items that were already in the
1410         # section (fees, taxes that are charged as packages for some reason).
1411         # also set 'summarized' to false so that this isn't a summary-only
1412         # section.
1413         $tax_section->{'subtotal'} = $other_money_char.
1414                                      sprintf('%.2f', $taxtotal);
1415         $tax_section->{'pretotal'} = 'New charges sub-total '.
1416                                      $total->{'total_amount'};
1417         $tax_section->{'description'} = $self->mt($tax_description);
1418         $tax_section->{'summarized'} = '';
1419
1420         if ( !grep $tax_section, @sections ) {
1421
1422           # append it if it's not already there
1423           push @sections, $tax_section;
1424           push @summary_subtotals, $tax_section;
1425
1426         }
1427
1428       }
1429
1430     } else {
1431       unshift @total_items, $total;
1432     }
1433   }
1434   $invoice_data{'taxtotal'} = sprintf('%.2f', $taxtotal);
1435
1436   ###
1437   # Totals
1438   ###
1439
1440   my %embolden_functions = (
1441     'latex'    => sub { return '\textbf{'. shift(). '}' },
1442     'html'     => sub { return '<b>'. shift(). '</b>' },
1443     'template' => sub { shift },
1444   );
1445   my $embolden_function = $embolden_functions{$format};
1446
1447   if ( $multisection ) {
1448
1449     if ( $adjust_section->{'sort_weight'} ) {
1450       $adjust_section->{'posttotal'} = $self->mt('Balance Forward').' '.
1451         $other_money_char.  sprintf("%.2f", ($self->billing_balance || 0) );
1452     } else{
1453       $adjust_section->{'pretotal'} = $self->mt('New charges total').' '.
1454         $other_money_char.  sprintf('%.2f', $self->charged );
1455     }
1456
1457   }
1458
1459   if ( $self->can('_items_total') ) { # should always be true now
1460
1461     # even for multisection, need plain text version
1462
1463     my @new_total_items = $self->_items_total;
1464
1465     push @buf,['','-----------'];
1466
1467     foreach ( @new_total_items ) {
1468       my ($item, $amount) = ($_->{'total_item'}, $_->{'total_amount'});
1469       $_->{'total_item'}   = &$embolden_function( $item );
1470
1471       if ( ref($amount) ) {
1472         $_->{'total_amount'} = &$embolden_function(
1473                                  $other_money_char.$amount->[0]. ' to '.
1474                                  $other_money_char.$amount->[1]
1475                                );
1476       } else {
1477       $_->{'total_amount'} = &$embolden_function( $other_money_char.$amount );
1478       }
1479
1480       # but if it's multisection, don't append to @total_items. the adjust
1481       # section has all this stuff
1482       push @total_items, $_ if !$multisection;
1483       push @buf, [ $item, $money_char.sprintf('%10.2f',$amount) ];
1484     }
1485
1486     push @buf, [ '', '' ];
1487
1488     # if we're showing previous invoices, also show previous
1489     # credits and payments
1490     if ( $self->enable_previous
1491           and $self->can('_items_credits')
1492           and $self->can('_items_payments') )
1493       {
1494
1495       # credits
1496       my $credittotal = 0;
1497       foreach my $credit (
1498         $self->_items_credits( 'template' => $template, 'trim_len' => 40 )
1499       ) {
1500
1501         my $total;
1502         $total->{'total_item'} = &$escape_function($credit->{'description'});
1503         $credittotal += $credit->{'amount'};
1504         $total->{'total_amount'} = $minus.$other_money_char.$credit->{'amount'};
1505         if ( $multisection ) {
1506           push @detail_items, {
1507             ext_description => [],
1508             ref          => '',
1509             quantity     => '',
1510             description  => &$escape_function($credit->{'description'}),
1511             amount       => $money_char . $credit->{'amount'},
1512             product_code => '',
1513             section      => $adjust_section,
1514           };
1515         } else {
1516           push @total_items, $total;
1517         }
1518
1519       }
1520       $invoice_data{'credittotal'} = sprintf('%.2f', $credittotal);
1521
1522       #credits (again)
1523       foreach my $credit (
1524         $self->_items_credits( 'template' => $template, 'trim_len'=>32 )
1525       ) {
1526         push @buf, [ $credit->{'description'}, $money_char.$credit->{'amount'} ];
1527       }
1528
1529       # payments
1530       my $paymenttotal = 0;
1531       foreach my $payment (
1532         $self->_items_payments( 'template' => $template )
1533       ) {
1534         my $total = {};
1535         $total->{'total_item'} = &$escape_function($payment->{'description'});
1536         $paymenttotal += $payment->{'amount'};
1537         $total->{'total_amount'} = $minus.$other_money_char.$payment->{'amount'};
1538         if ( $multisection ) {
1539           push @detail_items, {
1540             ext_description => [],
1541             ref          => '',
1542             quantity     => '',
1543             description  => &$escape_function($payment->{'description'}),
1544             amount       => $money_char . $payment->{'amount'},
1545             product_code => '',
1546             section      => $adjust_section,
1547           };
1548         }else{
1549           push @total_items, $total;
1550         }
1551         push @buf, [ $payment->{'description'},
1552                      $money_char. sprintf("%10.2f", $payment->{'amount'}),
1553                    ];
1554       }
1555       $invoice_data{'paymenttotal'} = sprintf('%.2f', $paymenttotal);
1556
1557       if ( $multisection ) {
1558         $adjust_section->{'subtotal'} = $other_money_char.
1559                                         sprintf('%.2f', $credittotal + $paymenttotal);
1560
1561         #why this? because {sort_weight} forces the adjust_section to appear
1562         #in @extra_sections instead of @sections. obviously.
1563         push @sections, $adjust_section
1564           unless $adjust_section->{sort_weight};
1565         # do not summarize; adjustments there are shown according to
1566         # different rules
1567       }
1568
1569       # create Balance Due message
1570       {
1571         my $total;
1572         $total->{'total_item'} = &$embolden_function($self->balance_due_msg);
1573         $total->{'total_amount'} =
1574           &$embolden_function(
1575             $other_money_char. sprintf('%.2f', #why? $summarypage
1576                                                #  ? $self->charged +
1577                                                #    $self->billing_balance
1578                                                #  :
1579                                                    $balance_due
1580                                       )
1581           );
1582         if ( $multisection && !$adjust_section->{sort_weight} ) {
1583           $adjust_section->{'posttotal'} = $total->{'total_item'}. ' '.
1584                                            $total->{'total_amount'};
1585         } else {
1586           push @total_items, $total;
1587         }
1588         push @buf,['','-----------'];
1589         push @buf,[$self->balance_due_msg, $money_char.
1590           sprintf("%10.2f", $balance_due ) ];
1591       }
1592
1593       if ( $conf->exists('previous_balance-show_credit')
1594           and $cust_main->balance < 0 ) {
1595         my $credit_total = {
1596           'total_item'    => &$embolden_function($self->credit_balance_msg),
1597           'total_amount'  => &$embolden_function(
1598             $other_money_char. sprintf('%.2f', -$cust_main->balance)
1599           ),
1600         };
1601         if ( $multisection ) {
1602           $adjust_section->{'posttotal'} .= $newline_token .
1603             $credit_total->{'total_item'} . ' ' . $credit_total->{'total_amount'};
1604         }
1605         else {
1606           push @total_items, $credit_total;
1607         }
1608         push @buf,['','-----------'];
1609         push @buf,[$self->credit_balance_msg, $money_char.
1610           sprintf("%10.2f", -$cust_main->balance ) ];
1611       }
1612     }
1613
1614   } #end of default total adding ! can('_items_total')
1615
1616   if ( $multisection ) {
1617     if (    $conf->exists('svc_phone_sections')
1618          && $self->can('_items_svc_phone_sections')
1619        )
1620     {
1621       my $total;
1622       $total->{'total_item'} = &$embolden_function($self->balance_due_msg);
1623       $total->{'total_amount'} =
1624         &$embolden_function(
1625           $other_money_char. sprintf('%.2f', $balance_due)
1626         );
1627       my $last_section = pop @sections;
1628       $last_section->{'posttotal'} = $total->{'total_item'}. ' '.
1629                                      $total->{'total_amount'};
1630       push @sections, $last_section;
1631     }
1632     push @sections, @$late_sections
1633       if $unsquelched;
1634   }
1635
1636   # make a discounts-available section, even without multisection
1637   if ( $conf->exists('discount-show_available')
1638        and my @discounts_avail = $self->_items_discounts_avail ) {
1639     my $discount_section = {
1640       'description' => $self->mt('Discounts Available'),
1641       'subtotal'    => '',
1642       'no_subtotal' => 1,
1643     };
1644
1645     push @sections, $discount_section; # do not summarize
1646     push @detail_items, map { +{
1647         'ref'         => '', #should this be something else?
1648         'section'     => $discount_section,
1649         'description' => &$escape_function( $_->{description} ),
1650         'amount'      => $money_char . &$escape_function( $_->{amount} ),
1651         'ext_description' => [ &$escape_function($_->{ext_description}) || () ],
1652     } } @discounts_avail;
1653   }
1654
1655   # not adding any more sections after this
1656   $invoice_data{summary_subtotals} = \@summary_subtotals;
1657
1658   # usage subtotals
1659   if ( $conf->exists('usage_class_summary')
1660        and $self->can('_items_usage_class_summary') ) {
1661     my @usage_subtotals = $self->_items_usage_class_summary(escape => $escape_function, 'money_char' => $other_money_char);
1662     if ( @usage_subtotals ) {
1663       unshift @sections, $usage_subtotals[0]->{section}; # do not summarize
1664       unshift @detail_items, @usage_subtotals;
1665     }
1666   }
1667
1668   # invoice history "section" (not really a section)
1669   # not to be included in any subtotals, completely independent of
1670   # everything...
1671   if ( $conf->exists('previous_invoice_history') and $cust_main->isa('FS::cust_main') ) {
1672     my %history;
1673     my %monthorder;
1674     foreach my $cust_bill ( $cust_main->cust_bill ) {
1675       # XXX hardcoded format, and currently only 'charged'; add other fields
1676       # if they become necessary
1677       my $date = $self->time2str_local('%b %Y', $cust_bill->_date);
1678       $history{$date} ||= 0;
1679       $history{$date} += $cust_bill->charged;
1680       # just so we have a numeric sort key
1681       $monthorder{$date} ||= $cust_bill->_date;
1682     }
1683     my @sorted_months = sort { $monthorder{$a} <=> $monthorder{$b} }
1684                         keys %history;
1685     my @sorted_amounts = map { sprintf('%.2f', $history{$_}) } @sorted_months;
1686     $invoice_data{monthly_history} = [ \@sorted_months, \@sorted_amounts ];
1687   }
1688
1689   # service locations: another option for template customization
1690   my %location_info;
1691   foreach my $item (@detail_items) {
1692     if ( $item->{locationnum} ) {
1693       $location_info{ $item->{locationnum} } ||= {
1694         FS::cust_location->by_key( $item->{locationnum} )->location_hash
1695       };
1696     }
1697   }
1698   $invoice_data{location_info} = \%location_info;
1699
1700   # debugging hook: call this with 'diag' => 1 to just get a hash of
1701   # the invoice variables
1702   return \%invoice_data if ( $params{'diag'} );
1703
1704   # All sections and items are built; now fill in templates.
1705   my @includelist = ();
1706   push @includelist, 'summary' if $summarypage;
1707   foreach my $include ( @includelist ) {
1708
1709     my $inc_file = $conf->key_orbase("invoice_${format}$include", $template);
1710     my @inc_src;
1711
1712     if ( length( $conf->config($inc_file, $agentnum) ) ) {
1713
1714       @inc_src = $conf->config($inc_file, $agentnum);
1715
1716     } else {
1717
1718       $inc_file = $conf->key_orbase("invoice_latex$include", $template);
1719
1720       my $convert_map = $convert_maps{$format}{$include};
1721
1722       @inc_src = map { s/\[\@--/$delimiters{$format}[0]/g;
1723                        s/--\@\]/$delimiters{$format}[1]/g;
1724                        $_;
1725                      }
1726                  &$convert_map( $conf->config($inc_file, $agentnum) );
1727
1728     }
1729
1730     my $inc_tt = new Text::Template (
1731       TYPE       => 'ARRAY',
1732       SOURCE     => [ map "$_\n", @inc_src ],
1733       DELIMITERS => $delimiters{$format},
1734     ) or die "Can't create new Text::Template object: $Text::Template::ERROR";
1735
1736     unless ( $inc_tt->compile() ) {
1737       my $error = "Can't compile $inc_file template: $Text::Template::ERROR\n";
1738       warn $error. "Template:\n". join('', map "$_\n", @inc_src);
1739       die $error;
1740     }
1741
1742     $invoice_data{$include} = $inc_tt->fill_in( HASH => \%invoice_data );
1743
1744     $invoice_data{$include} =~ s/\n+$//
1745       if ($format eq 'latex');
1746   }
1747
1748   $invoice_lines = 0;
1749   my $wasfunc = 0;
1750   foreach ( grep /invoice_lines\(\d*\)/, @invoice_template ) { #kludgy
1751     /invoice_lines\((\d*)\)/;
1752     $invoice_lines += $1 || scalar(@buf);
1753     $wasfunc=1;
1754   }
1755   die "no invoice_lines() functions in template?"
1756     if ( $format eq 'template' && !$wasfunc );
1757
1758   if ( $invoice_lines ) {
1759     $invoice_data{'total_pages'} = int( scalar(@buf) / $invoice_lines );
1760     $invoice_data{'total_pages'}++
1761       if scalar(@buf) % $invoice_lines;
1762   }
1763
1764   #setup subroutine for the template
1765   $invoice_data{invoice_lines} = sub {
1766     my $lines = shift || scalar(@buf);
1767     map {
1768       scalar(@buf)
1769         ? shift @buf
1770         : [ '', '' ];
1771     }
1772     ( 1 .. $lines );
1773   };
1774
1775   if ($format eq 'template') {
1776
1777     my $lines;
1778     my @collect;
1779     while (@buf) {
1780       push @collect, split("\n",
1781         $text_template->fill_in( HASH => \%invoice_data )
1782       );
1783       $invoice_data{'page'}++;
1784     }
1785     map "$_\n", @collect;
1786
1787   } else { # this is where we actually create the invoice
1788
1789     if ( $params{no_addresses} ) {
1790       delete $invoice_data{$_} foreach qw(
1791         payname company address1 address2 city state zip country
1792       );
1793       $invoice_data{returnaddress} = '~';
1794     }
1795
1796     warn "filling in template for invoice ". $self->invnum. "\n"
1797       if $DEBUG;
1798     warn join("\n", map " $_ => ". $invoice_data{$_}, keys %invoice_data). "\n"
1799       if $DEBUG > 1;
1800
1801     $text_template->fill_in(HASH => \%invoice_data);
1802   }
1803 }
1804
1805 sub notice_name { '('.shift->table.')'; }
1806
1807 # this is not supposed to happen
1808 sub template_conf { warn "bare FS::Template_Mixin::template_conf";
1809   'invoice_';
1810 }
1811
1812 =item print_ps HASHREF | [ TIME [ , TEMPLATE ] ]
1813
1814 Returns an postscript invoice, as a scalar.
1815
1816 Options can be passed as a hashref (recommended) or as a list of time, template
1817 and then any key/value pairs for any other options.
1818
1819 I<time> an optional value used to control the printing of overdue messages.  The
1820 default is now.  It isn't the date of the invoice; that's the `_date' field.
1821 It is specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
1822 L<Time::Local> and L<Date::Parse> for conversion functions.
1823
1824 I<notice_name>, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
1825
1826 =cut
1827
1828 sub print_ps {
1829   my $self = shift;
1830
1831   my ($file, $logofile, $barcodefile) = $self->print_latex(@_);
1832   my $ps = generate_ps($file);
1833   unlink($logofile);
1834   unlink($barcodefile) if $barcodefile;
1835
1836   $ps;
1837 }
1838
1839 =item print_pdf HASHREF | [ TIME [ , TEMPLATE ] ]
1840
1841 Returns an PDF invoice, as a scalar.
1842
1843 Options can be passed as a hashref (recommended) or as a list of time, template
1844 and then any key/value pairs for any other options.
1845
1846 I<time> an optional value used to control the printing of overdue messages.  The
1847 default is now.  It isn't the date of the invoice; that's the `_date' field.
1848 It is specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
1849 L<Time::Local> and L<Date::Parse> for conversion functions.
1850
1851 I<template>, if specified, is the name of a suffix for alternate invoices.
1852
1853 I<notice_name>, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
1854
1855 =cut
1856
1857 sub print_pdf {
1858   my $self = shift;
1859
1860   my ($file, $logofile, $barcodefile) = $self->print_latex(@_);
1861   my $pdf = generate_pdf($file);
1862   unlink($logofile);
1863   unlink($barcodefile) if $barcodefile;
1864
1865   $pdf;
1866 }
1867
1868 =item print_html HASHREF | [ TIME [ , TEMPLATE [ , CID ] ] ]
1869
1870 Returns an HTML invoice, as a scalar.
1871
1872 I<time> an optional value used to control the printing of overdue messages.  The
1873 default is now.  It isn't the date of the invoice; that's the `_date' field.
1874 It is specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
1875 L<Time::Local> and L<Date::Parse> for conversion functions.
1876
1877 I<template>, if specified, is the name of a suffix for alternate invoices.
1878
1879 I<notice_name>, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
1880
1881 I<cid> is a MIME Content-ID used to create a "cid:" URL for the logo image, used
1882 when emailing the invoice as part of a multipart/related MIME email.
1883
1884 =cut
1885
1886 sub print_html {
1887   my $self = shift;
1888   my %params;
1889   if ( ref($_[0]) ) {
1890     %params = %{ shift() };
1891   } else {
1892     %params = @_;
1893   }
1894   $params{'format'} = 'html';
1895
1896   $self->print_generic( %params );
1897 }
1898
1899 # quick subroutine for print_latex
1900 #
1901 # There are ten characters that LaTeX treats as special characters, which
1902 # means that they do not simply typeset themselves:
1903 #      # $ % & ~ _ ^ \ { }
1904 #
1905 # TeX ignores blanks following an escaped character; if you want a blank (as
1906 # in "10% of ..."), you have to "escape" the blank as well ("10\%\ of ...").
1907
1908 sub _latex_escape {
1909   my $value = shift;
1910   $value =~ s/([#\$%&~_\^{}])( )?/"\\$1". ( ( defined($2) && length($2) ) ? "\\$2" : '' )/ge;
1911   $value =~ s/([<>])/\$$1\$/g;
1912   $value;
1913 }
1914
1915 sub _html_escape {
1916   my $value = shift;
1917   encode_entities($value);
1918   $value;
1919 }
1920
1921 sub _html_escape_nbsp {
1922   my $value = _html_escape(shift);
1923   $value =~ s/ +/&nbsp;/g;
1924   $value;
1925 }
1926
1927 #utility methods for print_*
1928
1929 sub _translate_old_latex_format {
1930   warn "_translate_old_latex_format called\n"
1931     if $DEBUG;
1932
1933   my @template = ();
1934   while ( @_ ) {
1935     my $line = shift;
1936
1937     if ( $line =~ /^%%Detail\s*$/ ) {
1938
1939       push @template, q![@--!,
1940                       q!  foreach my $_tr_line (@detail_items) {!,
1941                       q!    if ( scalar ($_tr_item->{'ext_description'} ) ) {!,
1942                       q!      $_tr_line->{'description'} .= !,
1943                       q!        "\\tabularnewline\n~~".!,
1944                       q!        join( "\\tabularnewline\n~~",!,
1945                       q!          @{$_tr_line->{'ext_description'}}!,
1946                       q!        );!,
1947                       q!    }!;
1948
1949       while ( ( my $line_item_line = shift )
1950               !~ /^%%EndDetail\s*$/                            ) {
1951         $line_item_line =~ s/'/\\'/g;    # nice LTS
1952         $line_item_line =~ s/\\/\\\\/g;  # escape quotes and backslashes
1953         $line_item_line =~ s/\$(\w+)/'. \$_tr_line->{$1}. '/g;
1954         push @template, "    \$OUT .= '$line_item_line';";
1955       }
1956
1957       push @template, '}',
1958                       '--@]';
1959       #' doh, gvim
1960     } elsif ( $line =~ /^%%TotalDetails\s*$/ ) {
1961
1962       push @template, '[@--',
1963                       '  foreach my $_tr_line (@total_items) {';
1964
1965       while ( ( my $total_item_line = shift )
1966               !~ /^%%EndTotalDetails\s*$/                      ) {
1967         $total_item_line =~ s/'/\\'/g;    # nice LTS
1968         $total_item_line =~ s/\\/\\\\/g;  # escape quotes and backslashes
1969         $total_item_line =~ s/\$(\w+)/'. \$_tr_line->{$1}. '/g;
1970         push @template, "    \$OUT .= '$total_item_line';";
1971       }
1972
1973       push @template, '}',
1974                       '--@]';
1975
1976     } else {
1977       $line =~ s/\$(\w+)/[\@-- \$$1 --\@]/g;
1978       push @template, $line;
1979     }
1980
1981   }
1982
1983   if ($DEBUG) {
1984     warn "$_\n" foreach @template;
1985   }
1986
1987   (@template);
1988 }
1989
1990 =item terms
1991
1992 =cut
1993
1994 sub terms {
1995   my $self = shift;
1996   my $conf = $self->conf;
1997
1998   #check for an invoice-specific override
1999   return $self->invoice_terms if $self->invoice_terms;
2000
2001   #check for a customer- specific override
2002   my $cust_main = $self->cust_main;
2003   return $cust_main->invoice_terms if $cust_main && $cust_main->invoice_terms;
2004
2005   my $agentnum = '';
2006   if ( $cust_main ) {
2007     $agentnum = $cust_main->agentnum;
2008   } elsif ( my $prospect_main = $self->prospect_main ) {
2009     $agentnum = $prospect_main->agentnum;
2010   }
2011
2012   #use configured default
2013   $conf->config('invoice_default_terms', $agentnum) || '';
2014 }
2015
2016 =item due_date
2017
2018 =cut
2019
2020 sub due_date {
2021   my $self = shift;
2022   my $duedate = '';
2023   if ( $self->terms =~ /^\s*Net\s*(\d+)\s*$/ ) {
2024     $duedate = $self->_date() + ( $1 * 86400 );
2025   } elsif ( $self->terms =~ /^End of Month$/ ) {
2026     my ($mon,$year) = (localtime($self->_date) )[4,5];
2027     $mon++;
2028     until ( $mon < 12 ) { $mon -= 12; $year++; }
2029     my $nextmonth_first = timelocal(0,0,0,1,$mon,$year);
2030     $duedate = $nextmonth_first - 86400;
2031   }
2032   $duedate;
2033 }
2034
2035 =item due_date2str
2036
2037 =cut
2038
2039 sub due_date2str {
2040   my $self = shift;
2041   $self->due_date ? $self->time2str_local(shift, $self->due_date) : '';
2042 }
2043
2044 =item balance_due_msg
2045
2046 =cut
2047
2048 sub balance_due_msg {
2049   my $self = shift;
2050   my $msg = $self->mt('Balance Due');
2051   return $msg unless $self->terms; # huh?
2052   if ( !$self->conf->exists('invoice_show_prior_due_date')
2053        || $self->has_sections ) {
2054     # if enabled, the due date is shown with Total New Charges (see
2055     # _items_total) and not here
2056     # (yes, or if invoice_sections is enabled; this is just for compatibility)
2057     if ( $self->due_date ) {
2058       my $please_pay_by =
2059         $self->conf->config('invoice_pay_by_msg', $self->agentnum)
2060         || 'Please pay by [_1]';
2061       $msg .= ' - ' . $self->mt($please_pay_by, $self->due_date2str('short')).
2062               ' '
2063        unless $self->conf->config_bool('invoice_omit_due_date',$self->agentnum);
2064     } elsif ( $self->terms ) {
2065       $msg .= ' - '. $self->mt($self->terms);
2066     }
2067   }
2068   $msg;
2069 }
2070
2071 =item balance_due_date
2072
2073 =cut
2074
2075 sub balance_due_date {
2076   my $self = shift;
2077   my $conf = $self->conf;
2078   my $duedate = '';
2079   my $terms = $self->terms;
2080   if ( $terms =~ /^\s*Net\s*(\d+)\s*$/ ) {
2081     $duedate = $self->time2str_local('rdate', $self->_date + ($1*86400) );
2082   }
2083   $duedate;
2084 }
2085
2086 sub credit_balance_msg {
2087   my $self = shift;
2088   $self->mt('Credit Balance Remaining')
2089 }
2090
2091 =item _date_pretty
2092
2093 Returns a string with the date, for example: "3/20/2008", localized for the
2094 customer.  Use _date_pretty_unlocalized for non-end-customer display use.
2095
2096 =cut
2097
2098 sub _date_pretty {
2099   my $self = shift;
2100   $self->time2str_local('short', $self->_date);
2101 }
2102
2103 =item _date_pretty_unlocalized
2104
2105 Returns a string with the date, for example: "3/20/2008", in the format
2106 configured for the back-office.  Use _date_pretty for end-customer display use.
2107
2108 =cut
2109
2110 sub _date_pretty_unlocalized {
2111   my $self = shift;
2112   time2str($date_format, $self->_date);
2113 }
2114
2115 =item email HASHREF
2116
2117 Emails this template.
2118
2119 Options are passed as a hashref.  Available options:
2120
2121 =over 4
2122
2123 =item from
2124
2125 If specified, overrides the default From: address.
2126
2127 =item notice_name
2128
2129 If specified, overrides the name of the sent document ("Invoice" or "Quotation")
2130
2131 =item template
2132
2133 (Deprecated) If specified, is the name of a suffix for alternate template files.
2134
2135 =back
2136
2137 Options accepted by generate_email can also be used.
2138
2139 =cut
2140
2141 sub email {
2142   my $self = shift;
2143   my $opt = shift || {};
2144   if ($opt and !ref($opt)) {
2145     die ref($self). '->email called with positional parameters';
2146   }
2147
2148   return if $self->hide;
2149
2150   my $error = send_email(
2151     $self->generate_email(
2152       'subject'     => $self->email_subject($opt->{template}),
2153       %$opt, # template, etc.
2154     )
2155   );
2156
2157   die "can't email: $error\n" if $error;
2158 }
2159
2160 =item generate_email OPTION => VALUE ...
2161
2162 Options:
2163
2164 =over 4
2165
2166 =item from
2167
2168 sender address, required
2169
2170 =item template
2171
2172 alternate template name, optional
2173
2174 =item subject
2175
2176 email subject, optional
2177
2178 =item notice_name
2179
2180 notice name instead of "Invoice", optional
2181
2182 =back
2183
2184 Returns an argument list to be passed to L<FS::Misc::send_email>.
2185
2186 =cut
2187
2188 use MIME::Entity;
2189 use Encode;
2190
2191 sub generate_email {
2192
2193   my $self = shift;
2194   my %args = @_;
2195   my $conf = $self->conf;
2196
2197   my $me = '[FS::Template_Mixin::generate_email]';
2198
2199   my %return = (
2200     'from'      => $args{'from'},
2201     'subject'   => ($args{'subject'} || $self->email_subject),
2202     'custnum'   => $self->custnum,
2203     'msgtype'   => 'invoice',
2204   );
2205
2206   $args{'unsquelch_cdr'} = $conf->exists('voip-cdr_email');
2207
2208   my $cust_main = $self->cust_main;
2209
2210   if (ref($args{'to'}) eq 'ARRAY') {
2211     $return{'to'} = $args{'to'};
2212   } elsif ( $cust_main ) {
2213     $return{'to'} = [ $cust_main->invoicing_list_emailonly ];
2214   }
2215
2216   my $tc = $self->template_conf;
2217
2218   my @text; # array of lines
2219   my $html; # a big string
2220   my @related_parts; # will contain the text/HTML alternative, and images
2221   my $related; # will contain the multipart/related object
2222
2223   if ( $conf->exists($tc. 'email_pdf') ) {
2224     if ( my $msgnum = $conf->config($tc.'email_pdf_msgnum') ) {
2225
2226       warn "$me using '${tc}email_pdf_msgnum' in multipart message"
2227         if $DEBUG;
2228
2229       my $msg_template = FS::msg_template->by_key($msgnum)
2230         or die "${tc}email_pdf_msgnum $msgnum not found\n";
2231       my $cust_msg = $msg_template->prepare(
2232         cust_main => $self->cust_main,
2233         object    => $self,
2234         msgtype   => 'invoice',
2235       );
2236
2237       # XXX hack to make this work in the new cust_msg era; consider replacing
2238       # with cust_bill_send_with_notice events.
2239       my @parts = $cust_msg->parts;
2240       foreach my $part (@parts) { # will only have two parts, normally
2241         if ( $part->mime_type eq 'text/plain' ) {
2242           @text = @{ $part->body };
2243         } elsif ( $part->mime_type eq 'text/html' ) {
2244           $html = $part->bodyhandle->as_string;
2245         }
2246       }
2247
2248     } elsif ( my @note = $conf->config($tc.'email_pdf_note') ) {
2249
2250       warn "$me using '${tc}email_pdf_note' in multipart message"
2251         if $DEBUG;
2252       @text = $conf->config($tc.'email_pdf_note');
2253       $html = join('<BR>', @text);
2254
2255     } # else use the plain text invoice
2256   }
2257
2258   if (!@text) {
2259
2260     if ( $conf->config($tc.'template') ) {
2261
2262       warn "$me generating plain text invoice"
2263         if $DEBUG;
2264
2265       # 'print_text' argument is no longer used
2266       @text = map Encode::encode_utf8($_), $self->print_text(\%args);
2267
2268     } else {
2269
2270       warn "$me no plain text version exists; sending empty message body"
2271         if $DEBUG;
2272
2273     }
2274
2275   }
2276
2277   my $text_part = build MIME::Entity (
2278     'Type'        => 'text/plain',
2279     'Encoding'    => 'quoted-printable',
2280     'Charset'     => 'UTF-8',
2281     #'Encoding'    => '7bit',
2282     'Data'        => \@text,
2283     'Disposition' => 'inline',
2284   );
2285
2286   if (!$html) {
2287
2288     if ( $conf->exists($tc.'html') ) {
2289       warn "$me generating HTML invoice"
2290         if $DEBUG;
2291
2292       $args{'from'} =~ /\@([\w\.\-]+)/;
2293       my $from = $1 || 'example.com';
2294       my $content_id = join('.', rand()*(2**32), $$, time). "\@$from";
2295
2296       my $logo;
2297       my $agentnum = $cust_main ? $cust_main->agentnum
2298                                 : $self->prospect_main->agentnum;
2299       if ( defined($args{'template'}) && length($args{'template'})
2300            && $conf->exists( 'logo_'. $args{'template'}. '.png', $agentnum )
2301          )
2302       {
2303         $logo = 'logo_'. $args{'template'}. '.png';
2304       } else {
2305         $logo = "logo.png";
2306       }
2307       my $image_data = $conf->config_binary( $logo, $agentnum);
2308
2309       push @related_parts, build MIME::Entity
2310         'Type'       => 'image/png',
2311         'Encoding'   => 'base64',
2312         'Data'       => $image_data,
2313         'Filename'   => 'logo.png',
2314         'Content-ID' => "<$content_id>",
2315       ;
2316
2317       if ( ref($self) eq 'FS::cust_bill' && $conf->exists('invoice-barcode') ) {
2318         my $barcode_content_id = join('.', rand()*(2**32), $$, time). "\@$from";
2319         push @related_parts, build MIME::Entity
2320           'Type'       => 'image/png',
2321           'Encoding'   => 'base64',
2322           'Data'       => $self->invoice_barcode(0),
2323           'Filename'   => 'barcode.png',
2324           'Content-ID' => "<$barcode_content_id>",
2325         ;
2326         $args{'barcode_cid'} = $barcode_content_id;
2327       }
2328
2329       $html = $self->print_html({ 'cid'=>$content_id, %args });
2330     }
2331
2332   }
2333
2334   if ( $html ) {
2335
2336     warn "$me creating HTML/text multipart message"
2337       if $DEBUG;
2338
2339     $return{'nobody'} = 1;
2340
2341     my $alternative = build MIME::Entity
2342       'Type'        => 'multipart/alternative',
2343       #'Encoding'    => '7bit',
2344       'Disposition' => 'inline'
2345     ;
2346
2347     if ( @text ) {
2348       $alternative->add_part($text_part);
2349     }
2350
2351     $alternative->attach(
2352       'Type'        => 'text/html',
2353       'Encoding'    => 'quoted-printable',
2354       'Data'        => [ '<html>',
2355                          '  <head>',
2356                          '    <title>',
2357                          '      '. encode_entities($return{'subject'}),
2358                          '    </title>',
2359                          '  </head>',
2360                          '  <body bgcolor="#e8e8e8">',
2361                          Encode::encode_utf8($html),
2362                          '  </body>',
2363                          '</html>',
2364                        ],
2365       'Disposition' => 'inline',
2366       #'Filename'    => 'invoice.pdf',
2367     );
2368
2369     unshift @related_parts, $alternative;
2370
2371     $related = build MIME::Entity 'Type'     => 'multipart/related',
2372                                   'Encoding' => '7bit';
2373
2374     #false laziness w/Misc::send_email
2375     $related->head->replace('Content-type',
2376       $related->mime_type.
2377       '; boundary="'. $related->head->multipart_boundary. '"'.
2378       '; type=multipart/alternative'
2379     );
2380
2381     $related->add_part($_) foreach @related_parts;
2382
2383   }
2384
2385   my @otherparts = ();
2386   if ( ref($self) eq 'FS::cust_bill' && $cust_main->email_csv_cdr ) {
2387
2388     if ( $conf->config('voip-cdr_email_attach') eq 'zip' ) {
2389
2390       my $data = join('', map "$_\n",
2391                    $self->call_details(prepend_billed_number=>1)
2392                  );
2393
2394       my $zip = new Archive::Zip;
2395       my $file = $zip->addString( $data, 'usage-'.$self->invnum.'.csv' );
2396       $file->desiredCompressionMethod( COMPRESSION_DEFLATED );
2397
2398       my $zipdata = '';
2399       my $SH = IO::Scalar->new(\$zipdata);
2400       my $status = $zip->writeToFileHandle($SH);
2401       die "Error zipping CDR attachment: $!" unless $status == AZ_OK;
2402
2403       push @otherparts, build MIME::Entity
2404         'Type'        => 'application/zip',
2405         'Encoding'    => 'base64',
2406         'Data'        => $zipdata,
2407         'Disposition' => 'attachment',
2408         'Filename'    => 'usage-'. $self->invnum. '.zip',
2409       ;
2410
2411     } else { # } elsif ( $conf->config('voip-cdr_email_attach') eq 'csv' ) {
2412
2413       push @otherparts, build MIME::Entity
2414         'Type'        => 'text/csv',
2415         'Encoding'    => '7bit',
2416         'Data'        => [ map { "$_\n" }
2417                              $self->call_details('prepend_billed_number' => 1)
2418                          ],
2419         'Disposition' => 'attachment',
2420         'Filename'    => 'usage-'. $self->invnum. '.csv',
2421       ;
2422
2423     }
2424
2425   }
2426
2427   if ( $conf->exists($tc.'email_pdf') ) {
2428
2429     #attaching pdf too:
2430     # multipart/mixed
2431     #   multipart/related
2432     #     multipart/alternative
2433     #       text/plain
2434     #       text/html
2435     #     image/png
2436     #   application/pdf
2437
2438     my $pdf = build MIME::Entity $self->mimebuild_pdf(\%args);
2439     push @otherparts, $pdf;
2440   }
2441
2442   if (@otherparts) {
2443     $return{'content-type'} = 'multipart/mixed'; # of the outer container
2444     if ( $html ) {
2445       $return{'mimeparts'} = [ $related, @otherparts ];
2446       $return{'type'} = 'multipart/related'; # of the first part
2447     } else {
2448       $return{'mimeparts'} = [ $text_part, @otherparts ];
2449       $return{'type'} = 'text/plain';
2450     }
2451   } elsif ( $html ) { # no PDF or CSV, strip the outer container
2452     $return{'mimeparts'} = \@related_parts;
2453     $return{'content-type'} = 'multipart/related';
2454     $return{'type'} = 'multipart/alternative';
2455   } else { # no HTML either
2456     $return{'body'} = \@text;
2457     $return{'content-type'} = 'text/plain';
2458   }
2459
2460   %return;
2461
2462 }
2463
2464 =item mimebuild_pdf
2465
2466 Returns a list suitable for passing to MIME::Entity->build(), representing
2467 this quotation or invoice as PDF attachment.
2468
2469 =cut
2470
2471 sub mimebuild_pdf {
2472   my $self = shift;
2473   (
2474     'Type'        => 'application/pdf',
2475     'Encoding'    => 'base64',
2476     'Data'        => [ $self->print_pdf(@_) ],
2477     'Disposition' => 'attachment',
2478     'Filename'    => $self->pdf_filename,
2479   );
2480 }
2481
2482 =item postal_mail_fsinc
2483
2484 Sends this invoice to the Freeside Internet Services, Inc. print and mail
2485 service.
2486
2487 =cut
2488
2489 use CAM::PDF;
2490 use IO::Socket::SSL;
2491 use LWP::UserAgent;
2492 use HTTP::Request::Common qw( POST );
2493 use Cpanel::JSON::XS;
2494 use MIME::Base64;
2495 sub postal_mail_fsinc {
2496   my ( $self, %opt ) = @_;
2497
2498   my $url = 'https://ws.freeside.biz/print';
2499
2500   my $cust_main = $self->cust_main;
2501   my $agentnum = $cust_main->agentnum;
2502   my $bill_location = $cust_main->bill_location;
2503
2504   die "Extra charges for international mailing; contact support\@freeside.biz to enable\n"
2505     if $bill_location->country ne 'US';
2506
2507   my $conf = new FS::Conf;
2508
2509   my @company_address = $conf->config('company_address', $agentnum);
2510   my ( $company_address1, $company_address2, $company_city, $company_state, $company_zip );
2511   if ( $company_address[2] =~ /^\s*(\S.*\S)\s*[\s,](\w\w),?\s*(\d{5}(-\d{4})?)\s*$/ ) {
2512     $company_address1 = $company_address[0];
2513     $company_address2 = $company_address[1];
2514     $company_city  = $1;
2515     $company_state = $2;
2516     $company_zip   = $3;
2517   } elsif ( $company_address[1] =~ /^\s*(\S.*\S)\s*[\s,](\w\w),?\s*(\d{5}(-\d{4})?)\s*$/ ) {
2518     $company_address1 = $company_address[0];
2519     $company_address2 = '';
2520     $company_city  = $1;
2521     $company_state = $2;
2522     $company_zip   = $3;
2523   } else {
2524     die "Unparsable company_address; contact support\@freeside.biz\n";
2525   }
2526   $company_city =~ s/,$//;
2527
2528   my $file = $self->print_pdf(%opt, 'no_addresses' => 1);
2529   my $pages = CAM::PDF->new($file)->numPages;
2530
2531   my $ua = LWP::UserAgent->new(
2532     'ssl_opts' => {
2533       verify_hostname => 0,
2534       SSL_verify_mode => IO::Socket::SSL::SSL_VERIFY_NONE,
2535       SSL_version     => 'SSLv3',
2536     }
2537   );
2538   my $response = $ua->request( POST $url, [
2539     'support-key'      => scalar($conf->config('support-key')),
2540     'file'             => encode_base64($file),
2541     'pages'            => $pages,
2542
2543     #from:
2544     'company_name'     => scalar( $conf->config('company_name', $agentnum) ),
2545     'company_address1' => $company_address1,
2546     'company_address2' => $company_address2,
2547     'company_city'     => $company_city,
2548     'company_state'    => $company_state,
2549     'company_zip'      => $company_zip,
2550     'company_country'  => 'US',
2551     'company_phonenum' => scalar($conf->config('company_phonenum', $agentnum)),
2552     'company_email'    => scalar($conf->config('invoice_from', $agentnum)),
2553
2554     #to:
2555     'name'             => $cust_main->invoice_attn
2556                             || $cust_main->contact_firstlast,
2557     'company'          => $cust_main->company,
2558     'address1'         => $bill_location->address1,
2559     'address2'         => $bill_location->address2,
2560     'city'             => $bill_location->city,
2561     'state'            => $bill_location->state,
2562     'zip'              => $bill_location->zip,
2563     'country'          => $bill_location->country,
2564   ]);
2565
2566   die "Print connection error: ". $response->message.
2567       ' ('. $response->as_string. ")\n"
2568     unless $response->is_success;
2569
2570   local $@;
2571   my $content = eval { decode_json($response->content) };
2572   die "Print JSON error : $@\n" if $@;
2573
2574   die $content->{error}."\n"
2575     if $content->{error};
2576
2577   #TODO: store this so we can query for a status later
2578   warn "Invoice printed, ID ". $content->{id}. "\n";
2579
2580   $content->{id};
2581
2582 }
2583
2584 =item _items_sections OPTIONS
2585
2586 Generate section information for all items appearing on this invoice.
2587 This will only be called for multi-section invoices.
2588
2589 For each line item (L<FS::cust_bill_pkg> record), this will fetch all
2590 related display records (L<FS::cust_bill_pkg_display>) and organize
2591 them into two groups ("early" and "late" according to whether they come
2592 before or after the total), then into sections.  A subtotal is calculated
2593 for each section.
2594
2595 Section descriptions are returned in sort weight order.  Each consists
2596 of a hash containing:
2597
2598 description: the package category name, escaped
2599 subtotal: the total charges in that section
2600 tax_section: a flag indicating that the section contains only tax charges
2601 summarized: same as tax_section, for some reason
2602 sort_weight: the package category's sort weight
2603
2604 If 'condense' is set on the display record, it also contains everything
2605 returned from C<_condense_section()>, i.e. C<_condensed_foo_generator>
2606 coderefs to generate parts of the invoice.  This is not advised.
2607
2608 The method returns two arrayrefs, one of "early" sections and one of "late"
2609 sections.
2610
2611 OPTIONS may include:
2612
2613 by_location: a flag to divide the invoice into sections by location.
2614 Each section hash will have a 'location' element containing a hashref of
2615 the location fields (see L<FS::cust_location>).  The section description
2616 will be the location label, but the template can use any of the location
2617 fields to create a suitable label.
2618
2619 by_category: a flag to divide the invoice into sections using display
2620 records (see L<FS::cust_bill_pkg_display>).  This is the "traditional"
2621 behavior.  Each section hash will have a 'category' element containing
2622 the section name from the display record (which probably equals the
2623 category name of the package, but may not in some cases).
2624
2625 summary: a flag indicating that this is a summary-format invoice.
2626 Turning this on has the following effects:
2627 - Ignores display items with the 'summary' flag.
2628 - Places all sections in the "early" group even if they have post_total.
2629 - Creates sections for all non-disabled package categories, even if they
2630 have no charges on this invoice, as well as a section with no name.
2631
2632 escape: an escape function to use for section titles.
2633
2634 extra_sections: an arrayref of additional sections to return after the
2635 sorted list.  If there are any of these, section subtotals exclude
2636 usage charges.
2637
2638 format: 'latex', 'html', or 'template' (i.e. text).  Not used, but
2639 passed through to C<_condense_section()>.
2640
2641 =cut
2642
2643 use vars qw(%pkg_category_cache);
2644 sub _items_sections {
2645   my $self = shift;
2646   my %opt = @_;
2647
2648   my $escape = $opt{escape};
2649   my @extra_sections = @{ $opt{extra_sections} || [] };
2650
2651   # $subtotal{$locationnum}{$categoryname} = amount.
2652   # if we're not using by_location, $locationnum is undef.
2653   # if we're not using by_category, you guessed it, $categoryname is undef.
2654   # if we're not using either one, we shouldn't be here in the first place...
2655   my %subtotal = ();
2656   my %late_subtotal = ();
2657   my %not_tax = ();
2658
2659   # About tax items + multisection invoices:
2660   # If either invoice_*summary option is enabled, AND there is a
2661   # package category with the name of the tax, then there will be
2662   # a display record assigning the tax item to that category.
2663   #
2664   # However, the taxes are always placed in the "Taxes, Surcharges,
2665   # and Fees" section regardless of that.  The only effect of the
2666   # display record is to create a subtotal for the summary page.
2667
2668   # cache these
2669   my $pkg_hash = $self->cust_pkg_hash;
2670
2671   foreach my $cust_bill_pkg ( $self->cust_bill_pkg )
2672   {
2673
2674       my $usage = $cust_bill_pkg->usage;
2675
2676       my $locationnum;
2677       if ( $opt{by_location} ) {
2678         if ( $cust_bill_pkg->pkgnum ) {
2679           $locationnum = $pkg_hash->{ $cust_bill_pkg->pkgnum }->locationnum;
2680         } else {
2681           $locationnum = '';
2682         }
2683       } else {
2684         $locationnum = undef;
2685       }
2686
2687       # as in _items_cust_pkg, if a line item has no display records,
2688       # cust_bill_pkg_display() returns a default record for it
2689
2690       foreach my $display ($cust_bill_pkg->cust_bill_pkg_display) {
2691         next if ( $display->summary && $opt{summary} );
2692
2693         #my $section = $display->section;
2694         #false laziness with the method, but for efficiency inside this loop
2695         my $section = $display->get('section');
2696         if ( !$section && !$cust_bill_pkg->hidden ) {
2697           $section = $cust_bill_pkg->get('categoryname'); #cust_bill->cust_bill_pkg added it (XXX quotations / quotation_section)
2698         }
2699
2700         my $type    = $display->type;
2701         # Set $section = undef if we're sectioning by location and this
2702         # line item _has_ a location (i.e. isn't a fee).
2703         $section = undef if $locationnum;
2704
2705         # set this flag if the section is not tax-only
2706         $not_tax{$locationnum}{$section} = 1
2707           if $cust_bill_pkg->pkgnum  or $cust_bill_pkg->feepart;
2708
2709         # there's actually a very important piece of logic buried in here:
2710         # incrementing $late_subtotal{$section} CREATES
2711         # $late_subtotal{$section}.  keys(%late_subtotal) is later used
2712         # to define the list of late sections, and likewise keys(%subtotal).
2713         # When _items_cust_bill_pkg is called to generate line items for
2714         # real, it will be called with 'section' => $section for each
2715         # of these.
2716         if ( $display->post_total && !$opt{summary} ) {
2717           if (! $type || $type eq 'S') {
2718             $late_subtotal{$locationnum}{$section} += $cust_bill_pkg->setup
2719               if $cust_bill_pkg->setup != 0
2720               || $cust_bill_pkg->setup_show_zero;
2721           }
2722
2723           if (! $type) {
2724             $late_subtotal{$locationnum}{$section} += $cust_bill_pkg->recur
2725               if $cust_bill_pkg->recur != 0
2726               || $cust_bill_pkg->recur_show_zero;
2727           }
2728
2729           if ($type && $type eq 'R') {
2730             $late_subtotal{$locationnum}{$section} += $cust_bill_pkg->recur - $usage
2731               if $cust_bill_pkg->recur != 0
2732               || $cust_bill_pkg->recur_show_zero;
2733           }
2734
2735           if ($type && $type eq 'U') {
2736             $late_subtotal{$locationnum}{$section} += $usage
2737               unless scalar(@extra_sections);
2738           }
2739
2740         } else { # it's a pre-total (normal) section
2741
2742           # skip tax items unless they're explicitly included in a section
2743           next if $cust_bill_pkg->pkgnum == 0 and
2744                   ! $cust_bill_pkg->feepart   and
2745                   ! $section;
2746
2747           if ( $type eq 'S' ) {
2748             $subtotal{$locationnum}{$section} += $cust_bill_pkg->setup
2749               if $cust_bill_pkg->setup != 0
2750               || $cust_bill_pkg->setup_show_zero;
2751           } elsif ( $type eq 'R' ) {
2752             $subtotal{$locationnum}{$section} += $cust_bill_pkg->recur - $usage
2753               if $cust_bill_pkg->recur != 0
2754               || $cust_bill_pkg->recur_show_zero;
2755           } elsif ( $type eq 'U' ) {
2756             $subtotal{$locationnum}{$section} += $usage
2757               unless scalar(@extra_sections);
2758           } elsif ( !$type ) {
2759             $subtotal{$locationnum}{$section} += $cust_bill_pkg->setup
2760                                                + $cust_bill_pkg->recur;
2761           }
2762
2763         }
2764
2765       }
2766
2767   }
2768
2769   %pkg_category_cache = ();
2770
2771   # summary invoices need subtotals for all non-disabled package categories,
2772   # even if they're zero
2773   # but currently assume that there are no location sections, or at least
2774   # that the summary page doesn't care about them
2775   if ( $opt{summary} ) {
2776     foreach my $category (qsearch('pkg_category', {disabled => ''})) {
2777       $subtotal{''}{$category->categoryname} ||= 0;
2778     }
2779     $subtotal{''}{''} ||= 0;
2780   }
2781
2782   my @sections;
2783   foreach my $post_total (0,1) {
2784     my @these;
2785     my $s = $post_total ? \%late_subtotal : \%subtotal;
2786     foreach my $locationnum (keys %$s) {
2787       foreach my $sectionname (keys %{ $s->{$locationnum} }) {
2788         my $section = {
2789                         'subtotal'    => $s->{$locationnum}{$sectionname},
2790                         'sort_weight' => 0,
2791                       };
2792         if ( $locationnum ) {
2793           $section->{'locationnum'} = $locationnum;
2794           my $location = FS::cust_location->by_key($locationnum);
2795           $section->{'description'} = &{ $escape }($location->location_label);
2796           # Better ideas? This will roughly group them by proximity,
2797           # which alpha sorting on any of the address fields won't.
2798           # Sorting by locationnum is meaningless.
2799           # We have to sort on _something_ or the order may change
2800           # randomly from one invoice to the next, which will confuse
2801           # people.
2802           $section->{'sort_weight'} = sprintf('%012s',$location->zip) .
2803                                       $locationnum;
2804           $section->{'location'} = {
2805             label_prefix => &{ $escape }($location->label_prefix),
2806             map { $_ => &{ $escape }($location->get($_)) }
2807               $location->fields
2808           };
2809         } else {
2810           $section->{'category'} = $sectionname;
2811           $section->{'description'} = &{ $escape }($sectionname);
2812           if ( _pkg_category($sectionname) ) {
2813             $section->{'sort_weight'} = _pkg_category($sectionname)->weight;
2814             if ( _pkg_category($sectionname)->condense ) {
2815               $section = { %$section, $self->_condense_section($opt{format}) };
2816             }
2817           }
2818         }
2819         if ( !$post_total and !$not_tax{$locationnum}{$sectionname} ) {
2820           # then it's a tax-only section
2821           $section->{'summarized'} = 'Y';
2822           $section->{'tax_section'} = 'Y';
2823         }
2824         push @these, $section;
2825       } # foreach $sectionname
2826     } #foreach $locationnum
2827     push @these, @extra_sections if $post_total == 0;
2828     # need an alpha sort for location sections, because postal codes can
2829     # be non-numeric
2830     $sections[ $post_total ] = [ sort {
2831       $opt{'by_location'} ?
2832         ($a->{sort_weight} cmp $b->{sort_weight}) :
2833         ($a->{sort_weight} <=> $b->{sort_weight})
2834       } @these ];
2835   } #foreach $post_total
2836
2837   return @sections; # early, late
2838 }
2839
2840 #helper subs for above
2841
2842 sub cust_pkg_hash {
2843   my $self = shift;
2844   $self->{cust_pkg} ||= { map { $_->pkgnum => $_ } $self->cust_pkg };
2845 }
2846
2847 sub _pkg_category {
2848   my $categoryname = shift;
2849   $pkg_category_cache{$categoryname} ||=
2850     qsearchs( 'pkg_category', { 'categoryname' => $categoryname } );
2851 }
2852
2853 my %condensed_format = (
2854   'label' => [ qw( Description Qty Amount ) ],
2855   'fields' => [
2856                 sub { shift->{description} },
2857                 sub { shift->{quantity} },
2858                 sub { my($href, %opt) = @_;
2859                       ($opt{dollar} || ''). $href->{amount};
2860                     },
2861               ],
2862   'align'  => [ qw( l r r ) ],
2863   'span'   => [ qw( 5 1 1 ) ],            # unitprices?
2864   'width'  => [ qw( 10.7cm 1.4cm 1.6cm ) ],   # don't like this
2865 );
2866
2867 sub _condense_section {
2868   my ( $self, $format ) = ( shift, shift );
2869   ( 'condensed' => 1,
2870     map { my $method = "_condensed_$_"; $_ => $self->$method($format) }
2871       qw( description_generator
2872           header_generator
2873           total_generator
2874           total_line_generator
2875         )
2876   );
2877 }
2878
2879 sub _condensed_generator_defaults {
2880   my ( $self, $format ) = ( shift, shift );
2881   return ( \%condensed_format, ' ', ' ', ' ', sub { shift } );
2882 }
2883
2884 my %html_align = (
2885   'c' => 'center',
2886   'l' => 'left',
2887   'r' => 'right',
2888 );
2889
2890 sub _condensed_header_generator {
2891   my ( $self, $format ) = ( shift, shift );
2892
2893   my ( $f, $prefix, $suffix, $separator, $column ) =
2894     _condensed_generator_defaults($format);
2895
2896   if ($format eq 'latex') {
2897     $prefix = "\\hline\n\\rule{0pt}{2.5ex}\n\\makebox[1.4cm]{}&\n";
2898     $suffix = "\\\\\n\\hline";
2899     $separator = "&\n";
2900     $column =
2901       sub { my ($d,$a,$s,$w) = @_;
2902             return "\\multicolumn{$s}{$a}{\\makebox[$w][$a]{\\textbf{$d}}}";
2903           };
2904   } elsif ( $format eq 'html' ) {
2905     $prefix = '<th></th>';
2906     $suffix = '';
2907     $separator = '';
2908     $column =
2909       sub { my ($d,$a,$s,$w) = @_;
2910             return qq!<th align="$html_align{$a}">$d</th>!;
2911       };
2912   }
2913
2914   sub {
2915     my @args = @_;
2916     my @result = ();
2917
2918     foreach  (my $i = 0; $f->{label}->[$i]; $i++) {
2919       push @result,
2920         &{$column}( map { $f->{$_}->[$i] } qw(label align span width) );
2921     }
2922
2923     $prefix. join($separator, @result). $suffix;
2924   };
2925
2926 }
2927
2928 sub _condensed_description_generator {
2929   my ( $self, $format ) = ( shift, shift );
2930
2931   my ( $f, $prefix, $suffix, $separator, $column ) =
2932     _condensed_generator_defaults($format);
2933
2934   my $money_char = '$';
2935   if ($format eq 'latex') {
2936     $prefix = "\\hline\n\\multicolumn{1}{c}{\\rule{0pt}{2.5ex}~} &\n";
2937     $suffix = '\\\\';
2938     $separator = " & \n";
2939     $column =
2940       sub { my ($d,$a,$s,$w) = @_;
2941             return "\\multicolumn{$s}{$a}{\\makebox[$w][$a]{\\textbf{$d}}}";
2942           };
2943     $money_char = '\\dollar';
2944   }elsif ( $format eq 'html' ) {
2945     $prefix = '"><td align="center"></td>';
2946     $suffix = '';
2947     $separator = '';
2948     $column =
2949       sub { my ($d,$a,$s,$w) = @_;
2950             return qq!<td align="$html_align{$a}">$d</td>!;
2951       };
2952     #$money_char = $conf->config('money_char') || '$';
2953     $money_char = '';  # this is madness
2954   }
2955
2956   sub {
2957     #my @args = @_;
2958     my $href = shift;
2959     my @result = ();
2960
2961     foreach  (my $i = 0; $f->{label}->[$i]; $i++) {
2962       my $dollar = '';
2963       $dollar = $money_char if $i == scalar(@{$f->{label}})-1;
2964       push @result,
2965         &{$column}( &{$f->{fields}->[$i]}($href, 'dollar' => $dollar),
2966                     map { $f->{$_}->[$i] } qw(align span width)
2967                   );
2968     }
2969
2970     $prefix. join( $separator, @result ). $suffix;
2971   };
2972
2973 }
2974
2975 sub _condensed_total_generator {
2976   my ( $self, $format ) = ( shift, shift );
2977
2978   my ( $f, $prefix, $suffix, $separator, $column ) =
2979     _condensed_generator_defaults($format);
2980   my $style = '';
2981
2982   if ($format eq 'latex') {
2983     $prefix = "& ";
2984     $suffix = "\\\\\n";
2985     $separator = " & \n";
2986     $column =
2987       sub { my ($d,$a,$s,$w) = @_;
2988             return "\\multicolumn{$s}{$a}{\\makebox[$w][$a]{$d}}";
2989           };
2990   }elsif ( $format eq 'html' ) {
2991     $prefix = '';
2992     $suffix = '';
2993     $separator = '';
2994     $style = 'border-top: 3px solid #000000;border-bottom: 3px solid #000000;';
2995     $column =
2996       sub { my ($d,$a,$s,$w) = @_;
2997             return qq!<td align="$html_align{$a}" style="$style">$d</td>!;
2998       };
2999   }
3000
3001
3002   sub {
3003     my @args = @_;
3004     my @result = ();
3005
3006     #  my $r = &{$f->{fields}->[$i]}(@args);
3007     #  $r .= ' Total' unless $i;
3008
3009     foreach  (my $i = 0; $f->{label}->[$i]; $i++) {
3010       push @result,
3011         &{$column}( &{$f->{fields}->[$i]}(@args). ($i ? '' : ' Total'),
3012                     map { $f->{$_}->[$i] } qw(align span width)
3013                   );
3014     }
3015
3016     $prefix. join( $separator, @result ). $suffix;
3017   };
3018
3019 }
3020
3021 =item total_line_generator FORMAT
3022
3023 Returns a coderef used for generation of invoice total line items for this
3024 usage_class.  FORMAT is either html or latex
3025
3026 =cut
3027
3028 # should not be used: will have issues with hash element names (description vs
3029 # total_item and amount vs total_amount -- another array of functions?
3030
3031 sub _condensed_total_line_generator {
3032   my ( $self, $format ) = ( shift, shift );
3033
3034   my ( $f, $prefix, $suffix, $separator, $column ) =
3035     _condensed_generator_defaults($format);
3036   my $style = '';
3037
3038   if ($format eq 'latex') {
3039     $prefix = "& ";
3040     $suffix = "\\\\\n";
3041     $separator = " & \n";
3042     $column =
3043       sub { my ($d,$a,$s,$w) = @_;
3044             return "\\multicolumn{$s}{$a}{\\makebox[$w][$a]{$d}}";
3045           };
3046   }elsif ( $format eq 'html' ) {
3047     $prefix = '';
3048     $suffix = '';
3049     $separator = '';
3050     $style = 'border-top: 3px solid #000000;border-bottom: 3px solid #000000;';
3051     $column =
3052       sub { my ($d,$a,$s,$w) = @_;
3053             return qq!<td align="$html_align{$a}" style="$style">$d</td>!;
3054       };
3055   }
3056
3057
3058   sub {
3059     my @args = @_;
3060     my @result = ();
3061
3062     foreach  (my $i = 0; $f->{label}->[$i]; $i++) {
3063       push @result,
3064         &{$column}( &{$f->{fields}->[$i]}(@args),
3065                     map { $f->{$_}->[$i] } qw(align span width)
3066                   );
3067     }
3068
3069     $prefix. join( $separator, @result ). $suffix;
3070   };
3071
3072 }
3073
3074 =item _items_pkg [ OPTIONS ]
3075
3076 Return line item hashes for each package item on this invoice. Nearly
3077 equivalent to
3078
3079 $self->_items_cust_bill_pkg([ $self->cust_bill_pkg ])
3080
3081 OPTIONS are passed through to _items_cust_bill_pkg, and should include
3082 'format' and 'escape_function' at minimum.
3083
3084 To produce items for a specific invoice section, OPTIONS should include
3085 'section', a hashref containing 'category' and/or 'locationnum' keys.
3086
3087 'section' may also contain a key named 'condensed'. If this is present
3088 and has a true value, _items_pkg will try to merge identical items into items
3089 with 'quantity' equal to the number of items (not the sum of their separate
3090 quantities, for some reason).
3091
3092 =cut
3093
3094 sub _items_nontax {
3095   my $self = shift;
3096   # The order of these is important.  Bundled line items will be merged into
3097   # the most recent non-hidden item, so it needs to be the one with:
3098   # - the same pkgnum
3099   # - the same start date
3100   # - no pkgpart_override
3101   #
3102   # So: sort by pkgnum,
3103   # then by sdate
3104   # then sort the base line item before any overrides
3105   # then sort hidden before non-hidden add-ons
3106   # then sort by override pkgpart (for consistency)
3107   sort { $a->pkgnum <=> $b->pkgnum        or
3108          $a->sdate  <=> $b->sdate         or
3109          ($a->pkgpart_override ? 0 : -1)  or
3110          ($b->pkgpart_override ? 0 : 1)   or
3111          $b->hidden cmp $a->hidden        or
3112          $a->pkgpart_override <=> $b->pkgpart_override
3113        }
3114   # and of course exclude taxes and fees
3115   grep { $_->pkgnum > 0 } $self->cust_bill_pkg;
3116 }
3117
3118 sub _items_fee {
3119   my $self = shift;
3120   my %options = @_;
3121   my @cust_bill_pkg = grep { $_->feepart } $self->cust_bill_pkg;
3122   my $escape_function = $options{escape_function};
3123
3124   my $locale = $self->cust_main->locale;
3125
3126   my @items;
3127   foreach my $cust_bill_pkg (@cust_bill_pkg) {
3128     # cache this, so we don't look it up again in every section
3129     my $part_fee = $cust_bill_pkg->get('part_fee')
3130        || $cust_bill_pkg->part_fee;
3131     $cust_bill_pkg->set('part_fee', $part_fee);
3132     if (!$part_fee) {
3133       #die "fee definition not found for line item #".$cust_bill_pkg->billpkgnum."\n"; # might make more sense
3134       warn "fee definition not found for line item #".$cust_bill_pkg->billpkgnum."\n";
3135       next;
3136     }
3137
3138     # If _items_fee is called while building a sectioned invoice,
3139     #   - invoice_sections_method: category
3140     #     Skip fee records that do not match the section category.
3141     #   - invoice_sections_method: location
3142     #     Skip fee records always for location sections.
3143     #     The fee records will be presented in the tax/fee section instead.
3144     if (
3145       exists( $options{section} )
3146       and
3147       (
3148         (
3149           exists( $options{section}{category} )
3150           and
3151           $part_fee->categoryname ne $options{section}{category}
3152         )
3153         or
3154         exists( $options{section}{location})
3155       )
3156     ) {
3157       warn "skipping fee '".$part_fee->itemdesc.
3158            "'--not in section $options{section}{category}\n" if $DEBUG;
3159       next;
3160     }
3161
3162     my @ext_desc;
3163     my %base_invnums; # invnum => invoice date
3164     foreach ($cust_bill_pkg->cust_bill_pkg_fee) {
3165       if ($_->base_invnum) {
3166         my $base_bill = FS::cust_bill->by_key($_->base_invnum);
3167         my $base_date = $self->time2str_local('short', $base_bill->_date)
3168           if $base_bill;
3169         $base_invnums{$_->base_invnum} = $base_date || '';
3170       }
3171     }
3172     foreach (sort keys(%base_invnums)) {
3173       next if $_ == $self->invnum;
3174       # per convention, we must escape ext_description lines
3175       push @ext_desc,
3176         &{$escape_function}(
3177           $self->mt('from invoice #[_1] on [_2]', $_, $base_invnums{$_})
3178         );
3179     }
3180     my $desc = $part_fee->itemdesc_locale($locale);
3181     # but not escape the base description line
3182
3183     my @pkg_tax = $cust_bill_pkg->_pkg_tax_list
3184       if $options{section_with_taxes};
3185
3186     push @items,
3187       { feepart     => $cust_bill_pkg->feepart,
3188         billpkgnum  => $cust_bill_pkg->billpkgnum,
3189         amount      => sprintf('%.2f', $cust_bill_pkg->setup + $cust_bill_pkg->recur),
3190         description => $desc,
3191         pkg_tax     => \@pkg_tax,
3192         ext_description => \@ext_desc
3193         # sdate/edate?
3194       };
3195   }
3196   @items;
3197 }
3198
3199 sub _items_pkg {
3200   my $self = shift;
3201   my %options = @_;
3202
3203   warn "$me _items_pkg searching for all package line items\n"
3204     if $DEBUG > 1;
3205
3206   my @cust_bill_pkg = $self->_items_nontax;
3207
3208   warn "$me _items_pkg filtering line items\n"
3209     if $DEBUG > 1;
3210   my @items = $self->_items_cust_bill_pkg(\@cust_bill_pkg, @_);
3211
3212   if ($options{section} && $options{section}->{condensed}) {
3213
3214     warn "$me _items_pkg condensing section\n"
3215       if $DEBUG > 1;
3216
3217     my %itemshash = ();
3218     local $Storable::canonical = 1;
3219     foreach ( @items ) {
3220       my $item = { %$_ };
3221       delete $item->{ref};
3222       delete $item->{ext_description};
3223       my $key = freeze($item);
3224       $itemshash{$key} ||= 0;
3225       $itemshash{$key} ++; # += $item->{quantity};
3226     }
3227     @items = sort { $a->{description} cmp $b->{description} }
3228              map { my $i = thaw($_);
3229                    $i->{quantity} = $itemshash{$_};
3230                    $i->{amount} =
3231                      sprintf( "%.2f", $i->{quantity} * $i->{amount} );#unit_amount
3232                    $i;
3233                  }
3234              keys %itemshash;
3235   }
3236
3237   warn "$me _items_pkg returning ". scalar(@items). " items\n"
3238     if $DEBUG > 1;
3239
3240   @items;
3241 }
3242
3243 sub _taxsort {
3244   return 0 unless $a->itemdesc cmp $b->itemdesc;
3245   return -1 if $b->itemdesc eq 'Tax';
3246   return 1 if $a->itemdesc eq 'Tax';
3247   return -1 if $b->itemdesc eq 'Other surcharges';
3248   return 1 if $a->itemdesc eq 'Other surcharges';
3249   $a->itemdesc cmp $b->itemdesc;
3250 }
3251
3252 sub _items_tax {
3253   my $self = shift;
3254   my @cust_bill_pkg = sort _taxsort grep { ! $_->pkgnum and ! $_->feepart }
3255     $self->cust_bill_pkg;
3256   my @items = $self->_items_cust_bill_pkg(\@cust_bill_pkg, @_);
3257
3258   if ( $self->conf->exists('always_show_tax') ) {
3259     my $itemdesc = $self->conf->config('always_show_tax') || 'Tax';
3260     if (0 == grep { $_->{description} eq $itemdesc } @items) {
3261       push @items,
3262         { 'description' => $itemdesc,
3263           'amount'      => 0.00 };
3264     }
3265   }
3266   @items;
3267 }
3268
3269 =item _items_cust_bill_pkg CUST_BILL_PKGS OPTIONS
3270
3271 Takes an arrayref of L<FS::cust_bill_pkg> objects, and returns a
3272 list of hashrefs describing the line items they generate on the invoice.
3273
3274 OPTIONS may include:
3275
3276 format: the invoice format.
3277
3278 escape_function: the function used to escape strings.
3279
3280 DEPRECATED? (expensive, mostly unused?)
3281 format_function: the function used to format CDRs.
3282
3283 section: a hashref containing 'category' and/or 'locationnum'; if this
3284 is present, only returns line items that belong to that category and/or
3285 location (whichever is defined).
3286
3287 multisection: a flag indicating that this is a multisection invoice,
3288 which does something complicated.
3289
3290 section_with_taxes:  Look up and include applied taxes for each record
3291
3292 Returns a list of hashrefs, each of which may contain:
3293
3294 pkgnum, description, amount, unit_amount, quantity, pkgpart, _is_setup, and
3295 ext_description, which is an arrayref of detail lines to show below
3296 the package line.
3297
3298 =cut
3299
3300 sub _items_cust_bill_pkg {
3301   my $self = shift;
3302   my $conf = $self->conf;
3303   my $cust_bill_pkgs = shift;
3304   my %opt = @_;
3305
3306   my $format = $opt{format} || '';
3307   my $escape_function = $opt{escape_function} || sub { shift };
3308   my $format_function = $opt{format_function} || '';
3309   my $no_usage = $opt{no_usage} || '';
3310   my $unsquelched = $opt{unsquelched} || ''; #unused
3311   my ($section, $locationnum, $category);
3312   if ( $opt{section} ) {
3313     $category = $opt{section}->{category};
3314     $locationnum = $opt{section}->{locationnum};
3315   }
3316   my $summary_page = $opt{summary_page} || ''; #unused
3317   my $multisection = defined($category) || defined($locationnum);
3318   # this variable is the value of the config setting, not whether it applies
3319   # to this particular line item.
3320   my $discount_show_always = $conf->exists('discount-show-always');
3321
3322   my $maxlength = $conf->config('cust_bill-latex_lineitem_maxlength') || 40;
3323
3324   my $cust_main = $self->cust_main;#for per-agent cust_bill-line_item-ate_style
3325
3326   my $agentnum = $self->agentnum;
3327
3328   # for location labels: use default location on the invoice date
3329   my $default_locationnum;
3330   if ( $conf->exists('invoice-all_pkg_addresses') ) {
3331     $default_locationnum = 0; # treat them all as non-default
3332   } elsif ( $self->custnum ) {
3333     my $h_cust_main;
3334     my @h_search = FS::h_cust_main->sql_h_search($self->_date);
3335     $h_cust_main = qsearchs({
3336         'table'     => 'h_cust_main',
3337         'hashref'   => { custnum => $self->custnum },
3338         'extra_sql' => $h_search[1],
3339         'addl_from' => $h_search[3],
3340     }) || $cust_main;
3341     $default_locationnum = $h_cust_main->ship_locationnum;
3342   } elsif ( $self->prospectnum ) {
3343     my $cust_location = qsearchs('cust_location',
3344       { prospectnum => $self->prospectnum,
3345         disabled => '' });
3346     $default_locationnum = $cust_location->locationnum if $cust_location;
3347   }
3348
3349   my @b = (); # accumulator for the line item hashes that we'll return
3350   my ($s, $r, $u, $d) = ( undef, undef, undef, undef );
3351             # the 'current' line item hashes for setup, recur, usage, discount
3352   foreach my $cust_bill_pkg ( @$cust_bill_pkgs )
3353   {
3354     # if the current line item is waiting to go out, and the one we're about
3355     # to start is not bundled, then push out the current one and start a new
3356     # one.
3357     if ( $d ) {
3358       $d->{amount} = $d->{setup_amount} + $d->{recur_amount};
3359     }
3360     foreach ( $s, $r, ($opt{skip_usage} ? () : $u ), $d ) {
3361       if ( $_ && !$cust_bill_pkg->hidden ) {
3362         $_->{amount}      = sprintf( "%.2f", $_->{amount} );
3363         $_->{amount}      =~ s/^\-0\.00$/0.00/;
3364         if (exists($_->{unit_amount})) {
3365           $_->{unit_amount} = sprintf( "%.2f", $_->{unit_amount} );
3366         }
3367         push @b, { %$_ };
3368         # we already decided to create this display line; don't reconsider it
3369         # now.
3370         #  if $_->{amount} != 0
3371         #  || $discount_show_always
3372         #  || ( ! $_->{_is_setup} && $_->{recur_show_zero} )
3373         #  || (   $_->{_is_setup} && $_->{setup_show_zero} )
3374         ;
3375         $_ = undef;
3376       }
3377     }
3378
3379     if ( $locationnum ) {
3380       # this is a location section; skip packages that aren't at this
3381       # service location.
3382       next if $cust_bill_pkg->pkgnum == 0; # skips fees...
3383       next if $self->cust_pkg_hash->{ $cust_bill_pkg->pkgnum }->locationnum
3384               != $locationnum;
3385     }
3386
3387     # Consider display records for this item to determine if it belongs
3388     # in this section.  Note that if there are no display records, there
3389     # will be a default pseudo-record that includes all charge types
3390     # and has no section name.
3391     my @cust_bill_pkg_display = $cust_bill_pkg->can('cust_bill_pkg_display')
3392                                   ? $cust_bill_pkg->cust_bill_pkg_display
3393                                   : ( $cust_bill_pkg );
3394
3395     warn "$me _items_cust_bill_pkg considering cust_bill_pkg ".
3396          $cust_bill_pkg->billpkgnum. ", pkgnum ". $cust_bill_pkg->pkgnum. "\n"
3397       if $DEBUG > 1;
3398
3399     if ( defined($category) ) {
3400       # then this is a package category section; process all display records
3401       # that belong to this section.
3402       @cust_bill_pkg_display = grep { $_->section eq $category }
3403                                 @cust_bill_pkg_display;
3404     } else {
3405       # otherwise, process all display records that aren't usage summaries
3406       # (I don't think there should be usage summaries if you aren't using
3407       # category sections, but this is the historical behavior)
3408       @cust_bill_pkg_display = grep { !$_->summary }
3409                                 @cust_bill_pkg_display;
3410     }
3411
3412     my $classname = ''; # package class name, will fill in later
3413
3414     foreach my $display (@cust_bill_pkg_display) {
3415
3416       warn "$me _items_cust_bill_pkg considering cust_bill_pkg_display ".
3417            $display->billpkgdisplaynum. "\n"
3418         if $DEBUG > 1;
3419
3420       my $type = $display->type;
3421
3422       my $desc = $cust_bill_pkg->desc( $cust_main ? $cust_main->locale : '' );
3423       $desc = substr($desc, 0, $maxlength). '...'
3424         if $format eq 'latex' && length($desc) > $maxlength;
3425
3426       my %details_opt = ( 'format'          => $format,
3427                           'escape_function' => $escape_function,
3428                           'format_function' => $format_function,
3429                           'no_usage'        => $opt{'no_usage'},
3430                         );
3431
3432       if ( $cust_bill_pkg->pkgnum > 0 ) {
3433         # a "normal" package line item (not a quotation, not a fee, not a tax)
3434
3435         warn "$me _items_cust_bill_pkg cust_bill_pkg is non-tax\n"
3436           if $DEBUG > 1;
3437
3438         my $cust_pkg = $cust_bill_pkg->cust_pkg;
3439         my $part_pkg = $cust_pkg->part_pkg;
3440
3441         # which pkgpart to show for display purposes?
3442         my $pkgpart = $cust_bill_pkg->pkgpart_override || $cust_pkg->pkgpart;
3443
3444         # start/end dates for invoice formats that do nonstandard
3445         # things with them
3446         my %item_dates = ();
3447         %item_dates = map { $_ => $cust_bill_pkg->$_ } ('sdate', 'edate')
3448           unless $part_pkg->option('disable_line_item_date_ranges',1);
3449
3450         # not normally used, but pass this to the template anyway
3451         $classname = $part_pkg->classname;
3452
3453         my @pkg_tax = $cust_bill_pkg->_pkg_tax_list
3454           if $self->conf->exists('invoice_sections_with_taxes');
3455
3456         if (    (!$type || $type eq 'S')
3457              && (    $cust_bill_pkg->setup != 0
3458                   || $cust_bill_pkg->setup_show_zero
3459                   || ($discount_show_always and $cust_bill_pkg->unitsetup > 0)
3460                 )
3461            )
3462          {
3463
3464           warn "$me _items_cust_bill_pkg adding setup\n"
3465             if $DEBUG > 1;
3466
3467           # append the word 'Setup' to the setup line if there's going to be
3468           # a recur line for the same package (i.e. not a one-time charge)
3469           # XXX localization
3470           my $description = $desc;
3471           $description .= ' Setup'
3472             if $cust_bill_pkg->recur != 0
3473             || ($discount_show_always and $cust_bill_pkg->unitrecur > 0)
3474             || $cust_bill_pkg->recur_show_zero;
3475
3476           my $disable_date_ranges =
3477                $opt{disable_line_item_date_ranges}
3478             || $part_pkg->option('disable_line_item_date_ranges', 1);
3479
3480           $description .= $cust_bill_pkg->time_period_pretty(
3481                             $part_pkg,
3482                             $agentnum,
3483                             disable_date_ranges => $disable_date_ranges,
3484                           )
3485             if $part_pkg->is_prepaid #for prepaid, "display the validity period
3486                                      # triggered by the recurring charge freq
3487                                      # (RT#26274)
3488             && $cust_bill_pkg->recur == 0
3489             && ! $cust_bill_pkg->recur_show_zero;
3490
3491           my @d = ();
3492           my $svc_label;
3493
3494           # always pass the svc_label through to the template, even if
3495           # not displaying it as an ext_description
3496           my @svc_labels = map &{$escape_function}($_),
3497             $cust_pkg->h_labels_short($self->_date,
3498                                       undef,
3499                                       'I',
3500                                       $self->conf->{locale},
3501                                      );
3502           $svc_label = $svc_labels[0];
3503
3504           unless ( $cust_pkg->part_pkg->hide_svc_detail
3505                 || $cust_bill_pkg->hidden )
3506           {
3507
3508             push @d, @svc_labels
3509               unless $cust_bill_pkg->pkgpart_override; #don't redisplay services
3510             # show the location label if it's not the customer's default
3511             # location, and we're not grouping items by location already
3512             if ( $cust_pkg->locationnum != $default_locationnum
3513                   and !defined($locationnum) ) {
3514               my $loc = $cust_pkg->location_label;
3515               $loc = substr($loc, 0, $maxlength). '...'
3516                 if $format eq 'latex' && length($loc) > $maxlength;
3517               push @d, &{$escape_function}($loc);
3518             }
3519
3520           } #unless hiding service details
3521
3522           push @d, $cust_bill_pkg->details(%details_opt)
3523             if $cust_bill_pkg->recur == 0;
3524
3525           if ( $cust_bill_pkg->hidden ) {
3526             $s->{amount}      += $cust_bill_pkg->setup;
3527             $s->{unit_amount} += $cust_bill_pkg->unitsetup;
3528             push @{ $s->{ext_description} }, @d;
3529           } else {
3530             $s = {
3531               billpkgnum      => $cust_bill_pkg->billpkgnum,
3532               _is_setup       => 1,
3533               description     => $description,
3534               pkgpart         => $pkgpart,
3535               pkgnum          => $cust_bill_pkg->pkgnum,
3536               amount          => $cust_bill_pkg->setup,
3537               setup_show_zero => $cust_bill_pkg->setup_show_zero,
3538               unit_amount     => $cust_bill_pkg->unitsetup,
3539               quantity        => $cust_bill_pkg->quantity,
3540               ext_description => \@d,
3541               svc_label       => ($svc_label || ''),
3542               locationnum     => $cust_pkg->locationnum, # sure, why not?
3543               pkg_tax         => \@pkg_tax,
3544             };
3545           };
3546
3547         }
3548
3549         # should we show a recur line?
3550         # if type eq 'S', then NO, because we've been told not to.
3551         # otherwise, show the recur line if:
3552         # - there's a recurring charge
3553         # - or recur_show_zero is on
3554         # - or there's a positive unitrecur (so it's been discounted to zero)
3555         #   and discount-show-always is on
3556         if (    ( !$type || $type eq 'R' || $type eq 'U' )
3557              && (
3558                      $cust_bill_pkg->recur != 0
3559                   || !defined($s)
3560                   || ($discount_show_always and $cust_bill_pkg->unitrecur > 0)
3561                   || $cust_bill_pkg->recur_show_zero
3562                 )
3563            )
3564         {
3565
3566           warn "$me _items_cust_bill_pkg adding recur/usage\n"
3567             if $DEBUG > 1;
3568
3569           my $is_summary = $display->summary;
3570           my $description = $desc;
3571           if ( $type eq 'U' and defined($r) ) {
3572             # don't just show the same description as the recur line
3573             $description = $self->mt('Usage charges');
3574           }
3575
3576           my $disable_date_ranges =
3577                $opt{disable_line_item_date_ranges}
3578             || $part_pkg->option('disable_line_item_date_ranges', 1);
3579
3580           $description .= $cust_bill_pkg->time_period_pretty(
3581                                     $part_pkg,
3582                                     $agentnum,
3583                                     disable_date_ranges => $disable_date_ranges,
3584                           );
3585
3586           my @d = ();
3587           my @seconds = (); # for display of usage info
3588           my $svc_label = '';
3589
3590           #at least until cust_bill_pkg has "past" ranges in addition to
3591           #the "future" sdate/edate ones... see #3032
3592           my @dates = ( $self->_date );
3593           my $prev = $cust_bill_pkg->previous_cust_bill_pkg;
3594           push @dates, $prev->sdate if $prev;
3595           push @dates, undef if !$prev;
3596
3597           my @svc_labels = map &{$escape_function}($_),
3598             $cust_pkg->h_labels_short(@dates,
3599                                       'I',
3600                                       $self->conf->{locale});
3601           $svc_label = $svc_labels[0];
3602
3603           # show service labels, unless...
3604                     # the package is set not to display them
3605           unless ( $part_pkg->hide_svc_detail
3606                     # or this is a tax-like line item
3607                 || $cust_bill_pkg->itemdesc
3608                     # or this is a hidden (bundled) line item
3609                 || $cust_bill_pkg->hidden
3610                     # or this is a usage summary line
3611                 || $is_summary && $type && $type eq 'U'
3612                     # or this is a usage line and there's a recurring line
3613                     # for the package in the same section (which will
3614                     # have service labels already)
3615                 || ($type eq 'U' and defined($r))
3616               )
3617           {
3618
3619             warn "$me _items_cust_bill_pkg adding service details\n"
3620               if $DEBUG > 1;
3621
3622             push @d, @svc_labels
3623               unless $cust_bill_pkg->pkgpart_override; #don't redisplay services
3624             warn "$me _items_cust_bill_pkg done adding service details\n"
3625               if $DEBUG > 1;
3626
3627             # show the location label if it's not the customer's default
3628             # location, and we're not grouping items by location already
3629             if ( $cust_pkg->locationnum != $default_locationnum
3630                   and !defined($locationnum) ) {
3631               my $loc = $cust_pkg->location_label;
3632               $loc = substr($loc, 0, $maxlength). '...'
3633                 if $format eq 'latex' && length($loc) > $maxlength;
3634               push @d, &{$escape_function}($loc);
3635             }
3636
3637             # Display of seconds_since_sqlradacct:
3638             # On the invoice, when processing @detail_items, look for a field
3639             # named 'seconds'.  This will contain total seconds for each
3640             # service, in the same order as @ext_description.  For services
3641             # that don't support this it will show undef.
3642             if ( $conf->exists('svc_acct-usage_seconds')
3643                  and ! $cust_bill_pkg->pkgpart_override ) {
3644               foreach my $cust_svc (
3645                   $cust_pkg->h_cust_svc(@dates, 'I')
3646                 ) {
3647
3648                 # eval because not having any part_export_usage exports
3649                 # is a fatal error, last_bill/_date because that's how
3650                 # sqlradius_hour billing does it
3651                 my $sec = eval {
3652                   $cust_svc->seconds_since_sqlradacct($dates[1] || 0, $dates[0]);
3653                 };
3654                 push @seconds, $sec;
3655               }
3656             } #if svc_acct-usage_seconds
3657
3658           } # if we are showing service labels
3659
3660           unless ( $is_summary ) {
3661             warn "$me _items_cust_bill_pkg adding details\n"
3662               if $DEBUG > 1;
3663
3664             #instead of omitting details entirely in this case (unwanted side
3665             # effects), just omit CDRs
3666             $details_opt{'no_usage'} = 1
3667               if $type && $type eq 'R';
3668
3669             push @d, $cust_bill_pkg->details(%details_opt);
3670           }
3671
3672           warn "$me _items_cust_bill_pkg calculating amount\n"
3673             if $DEBUG > 1;
3674
3675           my $amount = 0;
3676           if (!$type) {
3677             $amount = $cust_bill_pkg->recur;
3678           } elsif ($type eq 'R') {
3679             $amount = $cust_bill_pkg->recur - $cust_bill_pkg->usage;
3680           } elsif ($type eq 'U') {
3681             $amount = $cust_bill_pkg->usage;
3682           }
3683
3684           if ( !$type || $type eq 'R' ) {
3685
3686             warn "$me _items_cust_bill_pkg adding recur\n"
3687               if $DEBUG > 1;
3688
3689             my $unit_amount =
3690               ( $cust_bill_pkg->unitrecur > 0 ) ? $cust_bill_pkg->unitrecur
3691                                                 : $amount;
3692
3693             if ( $cust_bill_pkg->hidden ) {
3694               $r->{amount}      += $amount;
3695               $r->{unit_amount} += $unit_amount;
3696               push @{ $r->{ext_description} }, @d;
3697             } else {
3698               $r = {
3699                 billpkgnum      => $cust_bill_pkg->billpkgnum,
3700                 description     => $description,
3701                 pkgpart         => $pkgpart,
3702                 pkgnum          => $cust_bill_pkg->pkgnum,
3703                 amount          => $amount,
3704                 recur_show_zero => $cust_bill_pkg->recur_show_zero,
3705                 unit_amount     => $unit_amount,
3706                 quantity        => $cust_bill_pkg->quantity,
3707                 %item_dates,
3708                 ext_description => \@d,
3709                 svc_label       => ($svc_label || ''),
3710                 locationnum     => $cust_pkg->locationnum,
3711                 pkg_tax         => \@pkg_tax,
3712               };
3713               $r->{'seconds'} = \@seconds if grep {defined $_} @seconds;
3714             }
3715
3716           } else {  # $type eq 'U'
3717
3718             warn "$me _items_cust_bill_pkg adding usage\n"
3719               if $DEBUG > 1;
3720
3721             if ( $cust_bill_pkg->hidden and defined($u) ) {
3722               # if this is a hidden package and there's already a usage
3723               # line for the bundle, add this package's total amount and
3724               # usage details to it
3725               $u->{amount}      += $amount;
3726               push @{ $u->{ext_description} }, @d;
3727             } elsif ( $amount ) {
3728               # create a new usage line
3729               $u = {
3730                 billpkgnum      => $cust_bill_pkg->billpkgnum,
3731                 description     => $description,
3732                 pkgpart         => $pkgpart,
3733                 pkgnum          => $cust_bill_pkg->pkgnum,
3734                 amount          => $amount,
3735                 usage_item      => 1,
3736                 recur_show_zero => $cust_bill_pkg->recur_show_zero,
3737                 %item_dates,
3738                 ext_description => \@d,
3739                 locationnum     => $cust_pkg->locationnum,
3740                 pkg_tax         => \@pkg_tax,
3741               };
3742             } # else this has no usage, so don't create a usage section
3743           }
3744
3745         } # recurring or usage with recurring charge
3746
3747       } else { # taxes and fees
3748
3749         warn "$me _items_cust_bill_pkg cust_bill_pkg is tax\n"
3750           if $DEBUG > 1;
3751
3752         # items of this kind should normally not have sdate/edate.
3753         push @b, {
3754           'description' => $desc,
3755           'amount'      => sprintf('%.2f', $cust_bill_pkg->setup
3756                                            + $cust_bill_pkg->recur)
3757         };
3758
3759       } # if package line item / other line item
3760
3761       # decide whether to show active discounts here
3762       if (
3763           # case 1: we are showing a single line for the package
3764           ( !$type )
3765           # case 2: we are showing a setup line for a package that has
3766           # no base recurring fee
3767           or ( $type eq 'S' and $cust_bill_pkg->unitrecur == 0 )
3768           # case 3: we are showing a recur line for a package that has
3769           # a base recurring fee
3770           or ( $type eq 'R' and $cust_bill_pkg->unitrecur > 0 )
3771       ) {
3772
3773         my $item_discount = $cust_bill_pkg->_item_discount;
3774         if ( $item_discount ) {
3775           # $item_discount->{amount} is negative
3776
3777           if ( $d and $cust_bill_pkg->hidden ) {
3778             $d->{setup_amount} += $item_discount->{setup_amount};
3779             $d->{recur_amount} += $item_discount->{recur_amount};
3780           } else {
3781             $d = $item_discount;
3782             $_ = &{$escape_function}($_) foreach @{ $d->{ext_description} };
3783           }
3784
3785           # update the active line (before the discount) to show the
3786           # original price (whether this is a hidden line or not)
3787
3788           $s->{amount} -= $item_discount->{setup_amount} if $s;
3789           $r->{amount} -= $item_discount->{recur_amount} if $r;
3790
3791         } # if there are any discounts
3792       } # if this is an appropriate place to show discounts
3793
3794     } # foreach $display
3795
3796   }
3797
3798   # discount amount is internally split up
3799   if ( $d ) {
3800     $d->{amount} = $d->{setup_amount} + $d->{recur_amount};
3801   }
3802
3803   foreach ( $s, $r, ($opt{skip_usage} ? () : $u ), $d ) {
3804     if ( $_  ) {
3805       $_->{amount}      = sprintf( "%.2f", $_->{amount} ),
3806         if exists($_->{amount});
3807       $_->{amount}      =~ s/^\-0\.00$/0.00/;
3808       if (exists($_->{unit_amount})) {
3809         $_->{unit_amount} = sprintf( "%.2f", $_->{unit_amount} );
3810       }
3811
3812       push @b, { %$_ };
3813       #if $_->{amount} != 0
3814       #  || $discount_show_always
3815       #  || ( ! $_->{_is_setup} && $_->{recur_show_zero} )
3816       #  || (   $_->{_is_setup} && $_->{setup_show_zero} )
3817     }
3818   }
3819
3820   warn "$me _items_cust_bill_pkg done considering cust_bill_pkgs\n"
3821     if $DEBUG > 1;
3822
3823   @b;
3824
3825 }
3826
3827 =item _items_discounts_avail
3828
3829 Returns an array of line item hashrefs representing available term discounts
3830 for this invoice.  This makes the same assumptions that apply to term
3831 discounts in general: that the package is billed monthly, at a flat rate,
3832 with no usage charges.  A prorated first month will be handled, as will
3833 a setup fee if the discount is allowed to apply to setup fees.
3834
3835 =cut
3836
3837 sub _items_discounts_avail {
3838   my $self = shift;
3839
3840   #maybe move this method from cust_bill when quotations support discount_plans
3841   return () unless $self->can('discount_plans');
3842   my %plans = $self->discount_plans;
3843
3844   my $list_pkgnums = 0; # if any packages are not eligible for all discounts
3845   $list_pkgnums = grep { $_->list_pkgnums } values %plans;
3846
3847   map {
3848     my $months = $_;
3849     my $plan = $plans{$months};
3850
3851     my $term_total = sprintf('%.2f', $plan->discounted_total);
3852     my $percent = sprintf('%.0f',
3853                           100 * (1 - $term_total / $plan->base_total) );
3854     my $permonth = sprintf('%.2f', $term_total / $months);
3855     my $detail = $self->mt('discount on item'). ' '.
3856                  join(', ', map { "#$_" } $plan->pkgnums)
3857       if $list_pkgnums;
3858
3859     # discounts for non-integer months don't work anyway
3860     $months = sprintf("%d", $months);
3861
3862     +{
3863       description => $self->mt('Save [_1]% by paying for [_2] months',
3864                                 $percent, $months),
3865       amount      => $self->mt('[_1] ([_2] per month)',
3866                                 $term_total, $money_char.$permonth),
3867       ext_description => ($detail || ''),
3868     }
3869   } #map
3870   sort { $b <=> $a } keys %plans;
3871
3872 }
3873
3874 =item has_sections AGENTNUM
3875
3876 Return true if invoice_sections should be enabled for this bill.
3877  (Inherited by both cust_bill and cust_bill_void)
3878
3879 Determination:
3880 * False if not an invoice
3881 * True always if conf invoice_sections is enabled
3882 * True always if sections_by_location is enabled
3883 * True if conf invoice_sections_multilocation > 1,
3884   and location_count >= invoice_sections_multilocation
3885 * Else, False
3886
3887 =cut
3888
3889 sub has_sections {
3890   my ($self, $agentnum) = @_;
3891
3892   return 0 unless $self->invnum > 0;
3893
3894   $agentnum ||= $self->agentnum;
3895   return 1 if $self->conf->config_bool('invoice_sections', $agentnum);
3896   return 1 if $self->conf->exists('sections_by_location', $agentnum);
3897
3898   my $location_min = $self->conf->config(
3899     'invoice_sections_multilocation', $agentnum,
3900   );
3901
3902   return 1
3903     if $location_min
3904     && $self->location_count >= $location_min;
3905
3906   0;
3907 }
3908
3909
3910 =item location_count
3911
3912 Return the number of locations billed on this invoice
3913
3914 =cut
3915
3916 sub location_count {
3917   my ($self) = @_;
3918   return 0 unless $self->invnum;
3919
3920   # SELECT COUNT( DISTINCT cust_pkg.locationnum )
3921   # FROM cust_bill_pkg
3922   # LEFT JOIN cust_pkg USING (pkgnum)
3923   # WHERE invnum = 278
3924   #   AND cust_bill_pkg.pkgnum > 0
3925
3926   my $result = qsearchs({
3927     select    => 'COUNT(DISTINCT cust_pkg.locationnum) as location_count',
3928     table     => 'cust_bill_pkg',
3929     addl_from => 'LEFT JOIN cust_pkg USING (pkgnum)',
3930     extra_sql => 'WHERE invnum = '.dbh->quote( $self->invnum )
3931                . '  AND cust_bill_pkg.pkgnum > 0'
3932   });
3933   ref $result ? $result->location_count : 0;
3934 }
3935
3936 1;