allow fees to be charged based on batch payment attempts, #27778
[freeside.git] / FS / FS / cust_main_invoice.pm
1 package FS::cust_main_invoice;
2 use base qw( FS::Record );
3
4 use strict;
5 use FS::Record qw( qsearchs );
6 use FS::Conf;
7 use FS::svc_acct;
8 use FS::Msgcat qw(gettext);
9
10 =head1 NAME
11
12 FS::cust_main_invoice - Object methods for cust_main_invoice records
13
14 =head1 SYNOPSIS
15
16   use FS::cust_main_invoice;
17
18   $record = new FS::cust_main_invoice \%hash;
19   $record = new FS::cust_main_invoice { 'column' => 'value' };
20
21   $error = $record->insert;
22
23   $error = $new_record->replace($old_record);
24
25   $error = $record->delete;
26
27   $error = $record->check;
28
29   $email_address = $record->address;
30
31 =head1 DESCRIPTION
32
33 An FS::cust_main_invoice object represents an invoice destination.  FS::cust_main_invoice inherits from
34 FS::Record.  The following fields are currently supported:
35
36 =over 4
37
38 =item destnum - primary key
39
40 =item custnum - customer (see L<FS::cust_main>)
41
42 =item dest - Invoice destination: If numeric, a svcnum (see L<FS::svc_acct>), if string, a literal email address, `POST' to enable mailing (the default if no cust_main_invoice records exist), or `FAX' to enable faxing via a HylaFAX server.
43
44 =back
45
46 =head1 METHODS
47
48 =over 4
49
50 =item new HASHREF
51
52 Creates a new invoice destination.  To add the invoice destination to the database, see L<"insert">.
53
54 Note that this stores the hash reference, not a distinct copy of the hash it
55 points to.  You can ask the object for a copy with the I<hash> method.
56
57 =cut
58
59 sub table { 'cust_main_invoice'; }
60
61 =item insert
62
63 Adds this record to the database.  If there is an error, returns the error,
64 otherwise returns false.
65
66 =item delete
67
68 Delete this record from the database.
69
70 =item replace OLD_RECORD
71
72 Replaces the OLD_RECORD with this one in the database.  If there is an error,
73 returns the error, otherwise returns false.
74
75 =cut
76
77 sub replace {
78   my ( $new, $old ) = ( shift, shift );
79
80   return "Can't change custnum!" unless $old->custnum == $new->custnum;
81
82   $new->SUPER::replace($old);
83 }
84
85
86 =item check
87
88 Checks all fields to make sure this is a valid invoice destination.  If there is
89 an error, returns the error, otherwise returns false.  Called by the insert
90 and replace methods.
91
92 =cut
93
94 sub check {
95   my $self = shift;
96
97   my $error = $self->ut_numbern('destnum')
98            || $self->ut_number('custnum')
99            || $self->checkdest;
100   ;
101   return $error if $error;
102
103   $self->SUPER::check;
104 }
105
106 =item checkdest
107
108 Checks the dest field only.
109
110 #If it finds that the account ends in the
111 #same domain configured as the B<domain> configuration file, it will change the
112 #invoice destination from an email address to a service number (see
113 #L<FS::svc_acct>).
114
115 =cut
116
117 sub checkdest { 
118   my $self = shift;
119
120   my $error = $self->ut_text('dest');
121   return $error if $error;
122
123   my $conf = new FS::Conf;
124
125   if ( $self->dest =~ /^(POST|FAX)$/ ) {
126     #contemplate our navel
127   } elsif ( $self->dest =~ /^(\d+)$/ ) {
128     return "Unknown local account (specified by svcnum: ". $self->dest. ")"
129       unless qsearchs( 'svc_acct', { 'svcnum' => $self->dest } );
130   } elsif ( $conf->exists('emailinvoice-apostrophe')
131               ? $self->dest =~ /^\s*([\w\.\-\&\+\']+)\@(([\w\.\-]+\.)+\w+)\s*$/
132               : $self->dest =~ /^\s*([\w\.\-\&\+]+)\@(([\w\.\-]+\.)+\w+)\s*$/ ){
133     my($user, $domain) = ($1, $2);
134     $self->dest("$1\@$2");
135   } else {
136     return gettext("illegal_email_invoice_address"). ': '. $self->dest;
137   }
138
139   ''; #no error
140 }
141
142 =item address
143
144 Returns the literal email address for this record (or `POST' or `FAX').
145
146 =cut
147
148 sub address {
149   my $self = shift;
150   if ( $self->dest =~ /^(\d+)$/ ) {
151     my $svc_acct = qsearchs( 'svc_acct', { 'svcnum' => $1 } )
152       or return undef;
153     $svc_acct->email;
154   } else {
155     $self->dest;
156   }
157 }
158
159 =item cust_main
160
161 Returns the parent customer object (see L<FS::cust_main>).
162
163 =back
164
165 =head1 BUGS
166
167 =head1 SEE ALSO
168
169 L<FS::Record>, L<FS::cust_main>
170
171 =cut
172
173 1;
174