Merge branch 'master' of git.freeside.biz:/home/git/freeside
[freeside.git] / FS / FS / cust_event_fee.pm
1 package FS::cust_event_fee;
2
3 use strict;
4 use base qw( FS::Record );
5 use FS::Record qw( qsearch qsearchs );
6
7 =head1 NAME
8
9 FS::cust_event_fee - Object methods for cust_event_fee records
10
11 =head1 SYNOPSIS
12
13   use FS::cust_event_fee;
14
15   $record = new FS::cust_event_fee \%hash;
16   $record = new FS::cust_event_fee { 'column' => 'value' };
17
18   $error = $record->insert;
19
20   $error = $new_record->replace($old_record);
21
22   $error = $record->delete;
23
24   $error = $record->check;
25
26 =head1 DESCRIPTION
27
28 An FS::cust_event_fee object links a billing event that charged a fee
29 (an L<FS::cust_event>) to the resulting invoice line item (an 
30 L<FS::cust_bill_pkg> object).  FS::cust_event_fee inherits from FS::Record.  
31 The following fields are currently supported:
32
33 =over 4
34
35 =item eventfeenum - primary key
36
37 =item eventnum - key of the cust_event record that required the fee to be 
38 created.  This is a unique column; there's no reason for a single event 
39 instance to create more than one fee.
40
41 =item billpkgnum - key of the cust_bill_pkg record representing the fee 
42 on an invoice.  This is also a unique column but can be NULL to indicate
43 a fee that hasn't been billed yet.  In that case it will be billed the next
44 time billing runs for the customer.
45
46 =item feepart - key of the fee definition (L<FS::part_fee>).
47
48 =item nextbill - 'Y' if the fee should be charged on the customer's next
49 bill, rather than causing a bill to be produced immediately.
50
51 =back
52
53 =head1 METHODS
54
55 =over 4
56
57 =item new HASHREF
58
59 Creates a new event-fee link.  To add the record to the database, 
60 see L<"insert">.
61
62 =cut
63
64 sub table { 'cust_event_fee'; }
65
66 =item insert
67
68 Adds this record to the database.  If there is an error, returns the error,
69 otherwise returns false.
70
71 =item delete
72
73 Delete this record from the database.
74
75 =item replace OLD_RECORD
76
77 Replaces the OLD_RECORD with this one in the database.  If there is an error,
78 returns the error, otherwise returns false.
79
80 =item check
81
82 Checks all fields to make sure this is a valid example.  If there is
83 an error, returns the error, otherwise returns false.  Called by the insert
84 and replace methods.
85
86 =cut
87
88 # the check method should currently be supplied - FS::Record contains some
89 # data checking routines
90
91 sub check {
92   my $self = shift;
93
94   my $error = 
95     $self->ut_numbern('eventfeenum')
96     || $self->ut_foreign_key('eventnum', 'cust_event', 'eventnum')
97     || $self->ut_foreign_keyn('billpkgnum', 'cust_bill_pkg', 'billpkgnum')
98     || $self->ut_foreign_key('feepart', 'part_fee', 'feepart')
99     || $self->ut_flag('nextbill')
100   ;
101   return $error if $error;
102
103   $self->SUPER::check;
104 }
105
106 =back
107
108 =head1 CLASS METHODS
109
110 =over 4
111
112 =item by_cust CUSTNUM[, PARAMS]
113
114 Finds all cust_event_fee records belonging to the customer CUSTNUM.  Currently
115 fee events can be cust_main, cust_pkg, or cust_bill events; this will return 
116 all of them.
117
118 PARAMS can be additional params to pass to qsearch; this really only works
119 for 'hashref' and 'order_by'.
120
121 =cut
122
123 sub by_cust {
124   my $class = shift;
125   my $custnum = shift or return;
126   my %params = @_;
127   $custnum =~ /^\d+$/ or die "bad custnum $custnum";
128
129   # silliness
130   my $where = ($params{hashref} && keys (%{ $params{hashref} }))
131               ? 'AND'
132               : 'WHERE';
133   qsearch({
134     table     => 'cust_event_fee',
135     addl_from => 'JOIN cust_event USING (eventnum) ' .
136                  'JOIN part_event USING (eventpart) ',
137     extra_sql => "$where eventtable = 'cust_main' ".
138                  "AND cust_event.tablenum = $custnum",
139     %params
140   }),
141   qsearch({
142     table     => 'cust_event_fee',
143     addl_from => 'JOIN cust_event USING (eventnum) ' .
144                  'JOIN part_event USING (eventpart) ' .
145                  'JOIN cust_bill ON (cust_event.tablenum = cust_bill.invnum)',
146     extra_sql => "$where eventtable = 'cust_bill' ".
147                  "AND cust_bill.custnum = $custnum",
148     %params
149   }),
150   qsearch({
151     table     => 'cust_event_fee',
152     addl_from => 'JOIN cust_event USING (eventnum) ' .
153                  'JOIN part_event USING (eventpart) ' .
154                  'JOIN cust_pay_batch ON (cust_event.tablenum = cust_pay_batch.paybatchnum)',
155     extra_sql => "$where eventtable = 'cust_pay_batch' ".
156                  "AND cust_pay_batch.custnum = $custnum",
157     %params
158   }),
159   qsearch({
160     table     => 'cust_event_fee',
161     addl_from => 'JOIN cust_event USING (eventnum) ' .
162                  'JOIN part_event USING (eventpart) ' .
163                  'JOIN cust_pkg ON (cust_event.tablenum = cust_pkg.pkgnum)',
164     extra_sql => "$where eventtable = 'cust_pkg' ".
165                  "AND cust_pkg.custnum = $custnum",
166     %params
167   })
168 }
169
170                   
171
172 =head1 BUGS
173
174 =head1 SEE ALSO
175
176 L<FS::cust_event>, L<FS::part_fee>, L<FS::Record>
177
178 =cut
179
180 1;
181