FS/FS/cust_statement.pm

   1 package FS::cust_statement;
   2
   3 use strict;
   4 use base qw( FS::cust_bill );
   5 use FS::Record qw( dbh qsearch ); #qsearchs );
   6 use FS::cust_main;
   7 use FS::cust_bill;
   8
   9 use List::Util qw( sum );
  10
  11 =head1 NAME
  12
  13 FS::cust_statement - Object methods for cust_statement records
  14
  15 =head1 SYNOPSIS
  16
  17   use FS::cust_statement;
  18
  19   $record = new FS::cust_statement \%hash;
  20   $record = new FS::cust_statement { 'column' => 'value' };
  21
  22   $error = $record->insert;
  23
  24   $error = $new_record->replace($old_record);
  25
  26   $error = $record->delete;
  27
  28   $error = $record->check;
  29
  30 =head1 DESCRIPTION
  31
  32 An FS::cust_statement object represents an informational statement which
  33 aggregates one or more invoices.  FS::cust_statement inherits from
  34 FS::cust_bill.
  35
  36 The following fields are currently supported:
  37
  38 =over 4
  39
  40 =item statementnum
  41
  42 primary key
  43
  44 =item custnum
  45
  46 customer
  47
  48 =item _date
  49
  50 date
  51
  52 =back
  53
  54 =head1 METHODS
  55
  56 =over 4
  57
  58 =item new HASHREF
  59
  60 Creates a new record.  To add the record to the database, see L<"insert">.
  61
  62 Note that this stores the hash reference, not a distinct copy of the hash it
  63 points to.  You can ask the object for a copy with the I<hash> method.
  64
  65 Pass "statementnum => 'ALL'" to create a temporary statement that includes
  66 all of the customer's open invoices.  This statement can't be inserted and
  67 won't set the statementnum field on any invoices.
  68
  69 Pass "invnum => number" to create a temporary statement including only
  70 the specified invoice.  This is functionally the same as the invoice itself,
  71 but will be rendered using the statement template and other
  72 statement-specific options.
  73
  74 =cut
  75
  76 sub new { FS::Record::new(@_); }
  77
  78 sub table { 'cust_statement'; }
  79
  80 =item insert
  81
  82 Adds this record to the database.  If there is an error, returns the error,
  83 otherwise returns false.
  84
  85 =cut
  86
  87 sub insert {
  88   my $self = shift;
  89
  90   local $SIG{HUP} = 'IGNORE';
  91   local $SIG{INT} = 'IGNORE';
  92   local $SIG{QUIT} = 'IGNORE';
  93   local $SIG{TERM} = 'IGNORE';
  94   local $SIG{TSTP} = 'IGNORE';
  95   local $SIG{PIPE} = 'IGNORE';
  96
  97   my $oldAutoCommit = $FS::UID::AutoCommit;
  98   local $FS::UID::AutoCommit = 0;
  99   my $dbh = dbh;
 100
 101   FS::Record::insert($self);
 102
 103   foreach my $cust_bill (
 104                           qsearch({
 105                             'table'     => 'cust_bill',
 106                             'hashref'   => { 'custnum'      => $self->custnum,
 107                                              'statementnum' => '',
 108                                            },
 109                             'extra_sql' => 'FOR UPDATE' ,
 110                           })
 111                         )
 112   {
 113     $cust_bill->statementnum( $self->statementnum );
 114     my $error = $cust_bill->replace;
 115     if ( $error ) {
 116       $dbh->rollback if $oldAutoCommit;
 117       return "Error associating invoice: $error";
 118     }
 119   }
 120
 121   $dbh->commit or die $dbh->errstr if $oldAutoCommit;
 122   ''; #no error
 123
 124 }
 125
 126 =item delete
 127
 128 Delete this record from the database.
 129
 130 =cut
 131
 132 sub delete { FS::Record::delete(@_); }
 133
 134 =item replace OLD_RECORD
 135
 136 Replaces the OLD_RECORD with this one in the database.  If there is an error,
 137 returns the error, otherwise returns false.
 138
 139 =cut
 140
 141 sub replace { FS::Record::replace(@_); }
 142
 143 sub replace_check { ''; }
 144
 145 =item check
 146
 147 Checks all fields to make sure this is a valid record.  If there is
 148 an error, returns the error, otherwise returns false.  Called by the insert
 149 and replace methods.
 150
 151 =cut
 152
 153 sub check {
 154   my $self = shift;
 155
 156   my $error =
 157     $self->ut_numbern('statementnum')
 158     || $self->ut_foreign_key('custnum', 'cust_main', 'custnum' )
 159     || $self->ut_numbern('_date')
 160   ;
 161   return $error if $error;
 162
 163   $self->_date(time) unless $self->_date;
 164
 165   #don't want to call cust_bill, and Record just checks virtual fields
 166   #$self->SUPER::check;
 167   '';
 168
 169 }
 170
 171 =item cust_bill
 172
 173 Returns the associated invoices (cust_bill records) for this statement.
 174
 175 =cut
 176
 177 sub cust_bill {
 178   my $self = shift;
 179   # we use it about a thousand times, let's cache it
 180   if ( !exists($self->{Hash}->{cust_bill}) ) {
 181     my @cust_bill;
 182     if ( $self->invnum && $self->invnum =~ /^\d+$/ ) {
 183       # one specific invoice
 184       @cust_bill = FS::cust_bill->by_key($self->invnum)
 185         or die "unknown invnum '".$self->invnum."'";
 186       $self->set('custnum' => $cust_bill[0]->custnum);
 187     } elsif ( $self->statementnum eq 'ALL' ) {
 188       # all open invoices
 189       @cust_bill = $self->cust_main->open_cust_bill;
 190     } else {
 191       @cust_bill = qsearch('cust_bill',
 192         { statementnum => $self->statementnum }
 193       );
 194     }
 195     $self->{Hash}->{cust_bill} = \@cust_bill;
 196   }
 197
 198   @{ $self->{Hash}->{cust_bill} }
 199 }
 200
 201 sub _aggregate {
 202   my( $self, $method ) = ( shift, shift );
 203
 204   my @agg = ();
 205
 206   foreach my $cust_bill ( $self->cust_bill ) {
 207     push @agg, $cust_bill->$method( @_ );
 208   }
 209
 210   @agg;
 211 }
 212
 213 sub _total {
 214   my( $self, $method ) = ( shift, shift );
 215
 216   my $total = 0;
 217
 218   foreach my $cust_bill ( $self->cust_bill ) {
 219     $total += $cust_bill->$method( @_ );
 220   }
 221
 222   $total;
 223 }
 224
 225 =item cust_bill_pkg
 226
 227 Returns the line items (see L<FS::cust_bill_pkg>) for all associated invoices.
 228
 229 =item cust_bill_pkg_pkgnum PKGNUM
 230
 231 Returns the line items (see L<FS::cust_bill_pkg>) for all associated invoices
 232 and specified pkgnum.
 233
 234 =item cust_bill_pay
 235
 236 Returns all payment applications (see L<FS::cust_bill_pay>) for all associated
 237 invoices.
 238
 239 =item cust_credited
 240
 241 Returns all applied credits (see L<FS::cust_credit_bill>) for all associated
 242 invoices.
 243
 244 =item cust_bill_pay_pkgnum PKGNUM
 245
 246 Returns all payment applications (see L<FS::cust_bill_pay>) for all associated
 247 invoices with matching pkgnum.
 248
 249 =item cust_credited_pkgnum PKGNUM
 250
 251 Returns all applied credits (see L<FS::cust_credit_bill>) for all associated
 252 invoices with matching pkgnum.
 253
 254 =cut
 255
 256 sub cust_bill_pay        { shift->_aggregate('cust_bill_pay',        @_); }
 257 sub cust_credited        { shift->_aggregate('cust_credited',        @_); }
 258 sub cust_bill_pay_pkgnum { shift->_aggregate('cust_bill_pay_pkgnum', @_); }
 259 sub cust_credited_pkgnum { shift->_aggregate('cust_credited_pkgnum', @_); }
 260
 261 sub cust_bill_pkg        { shift->_aggregate('cust_bill_pkg',        @_); }
 262 sub cust_bill_pkg_pkgnum { shift->_aggregate('cust_bill_pkg_pkgnum', @_); }
 263
 264 =item tax
 265
 266 Returns the total tax amount for all assoicated invoices.0
 267
 268 =cut
 269
 270 =item charged
 271
 272 Returns the total amount charged for all associated invoices.
 273
 274 =cut
 275
 276 =item owed
 277
 278 Returns the total amount owed for all associated invoices.
 279
 280 =cut
 281
 282 sub tax     { shift->_total('tax',     @_); }
 283 sub charged { shift->_total('charged', @_); }
 284 sub owed    { shift->_total('owed',    @_); }
 285
 286 sub enable_previous {
 287   my $self = shift;
 288   $self->conf->exists('previous_balance-show_on_statements');
 289 }
 290
 291 sub previous {
 292   my $self = shift;
 293   if ( $self->enable_previous ) {
 294     my @previous = grep { $_->_date < ($self->cust_bill)[0]->_date }
 295       $self->cust_main->open_cust_bill;
 296     return(sum(map {$_->owed} @previous), @previous);
 297   } else {
 298     return 0;
 299   }
 300 }
 301
 302 =back
 303
 304 =head1 BUGS
 305
 306 =head1 SEE ALSO
 307
 308 L<FS::cust_bill>, L<FS::Record>, schema.html from the base documentation.
 309
 310 =cut
 311
 312 1;
 313