Expand/fortify the handling of attributes
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / InflateColumn.pm
CommitLineData
0e5c2582 1package DBIx::Class::InflateColumn;
2
3use strict;
4use warnings;
aa562407 5
3705e3b2 6use base 'DBIx::Class::Row';
b5ce6748 7use SQL::Abstract 'is_literal_value';
3705e3b2 8use namespace::clean;
0e5c2582 9
75d07914 10=head1 NAME
bcae85db 11
e81a6241 12DBIx::Class::InflateColumn - Automatically create references from column data
bcae85db 13
14=head1 SYNOPSIS
15
1b23a127 16 # In your table classes
17 __PACKAGE__->inflate_column('column_name', {
18 inflate => sub {
19 my ($raw_value_from_db, $result_object) = @_;
20 ...
21 },
22 deflate => sub {
23 my ($inflated_value_from_user, $result_object) = @_;
24 ...
25 },
26 });
bcae85db 27
28=head1 DESCRIPTION
29
e81a6241 30This component translates column data into references, i.e. "inflating"
31the column data. It also "deflates" references into an appropriate format
bcae85db 32for the database.
33
34It can be used, for example, to automatically convert to and from
ef7a8b67 35L<DateTime> objects for your date and time fields. There's a
48580715 36convenience component to actually do that though, try
ef7a8b67 37L<DBIx::Class::InflateColumn::DateTime>.
bcae85db 38
ef7a8b67 39It will handle all types of references except scalar references. It
40will not handle scalar values, these are ignored and thus passed
41through to L<SQL::Abstract>. This is to allow setting raw values to
42"just work". Scalar references are passed through to the database to
43deal with, to allow such settings as C< \'year + 1'> and C< \'DEFAULT' >
44to work.
45
46If you want to filter plain scalar values and replace them with
9b2c0de6 47something else, see L<DBIx::Class::FilterColumn>.
e81a6241 48
bcae85db 49=head1 METHODS
50
51=head2 inflate_column
52
75d07914 53Instruct L<DBIx::Class> to inflate the given column.
bcae85db 54
55In addition to the column name, you must provide C<inflate> and
56C<deflate> methods. The C<inflate> method is called when you access
57the field, while the C<deflate> method is called when the field needs
58to used by the database.
59
60For example, if you have a table C<events> with a timestamp field
61named C<insert_time>, you could inflate the column in the
62corresponding table class using something like:
63
64 __PACKAGE__->inflate_column('insert_time', {
1b23a127 65 inflate => sub {
66 my ($insert_time_raw_value, $event_result_object) = @_;
67 DateTime->from_epoch( epoch => $insert_time_raw_value );
68 },
69 deflate => sub {
70 my ($insert_time_dt_object, $event_result_object) = @_;
71 $insert_time_dt_object->epoch;
72 },
bcae85db 73 });
74
06fc5fc9 75The coderefs you set for inflate and deflate are called with two parameters,
1b23a127 76the first is the value of the column to be inflated/deflated, the second is
77the result object itself.
06fc5fc9 78
bcae85db 79In this example, calls to an event's C<insert_time> accessor return a
1b23a127 80L<DateTime> object. This L<DateTime> object is later "deflated" back
81to the integer epoch representation when used in the database layer.
82For a much more thorough handling of the above example, please see
83L<DBIx::Class::DateTime::Epoch>
bcae85db 84
85=cut
86
0e5c2582 87sub inflate_column {
88 my ($self, $col, $attrs) = @_;
c227b295 89
e5053694 90 my $colinfo = $self->result_source_instance->column_info($col);
52416317 91
85aee309 92 $self->throw_exception("InflateColumn can not be used on a column with a declared FilterColumn filter")
93 if defined $colinfo->{_filter_info} and $self->isa('DBIx::Class::FilterColumn');
c227b295 94
bc0c9800 95 $self->throw_exception("No such column $col to inflate")
e5053694 96 unless $self->result_source_instance->has_column($col);
bc0c9800 97 $self->throw_exception("inflate_column needs attr hashref")
98 unless ref $attrs eq 'HASH';
52416317 99 $colinfo->{_inflate_info} = $attrs;
100 my $acc = $colinfo->{accessor};
b82c8a28 101 $self->mk_group_accessors('inflated_column' => [ (defined $acc ? $acc : $col), $col]);
0e5c2582 102 return 1;
103}
104
4a07648a 105sub _inflated_column {
0e5c2582 106 my ($self, $col, $value) = @_;
b342451e 107
108 return $value if (
109 ! defined $value # NULL is NULL is NULL
110 or
111 is_literal_value($value) #that would be a not-yet-reloaded literal update
112 );
3705e3b2 113
4006691d 114 my $info = $self->result_source->column_info($col)
bc0c9800 115 or $self->throw_exception("No column info for $col");
3705e3b2 116
103647d5 117 return $value unless exists $info->{_inflate_info};
3705e3b2 118
5ae153d7 119 return (
120 $info->{_inflate_info}{inflate}
121 ||
122 $self->throw_exception("No inflator found for '$col'")
123 )->($value, $self);
0e5c2582 124}
125
89279e9d 126sub _deflated_column {
127 my ($self, $col, $value) = @_;
3705e3b2 128
129 ## Deflate any refs except for literals, pass through plain values
130 return $value if (
131 ! length ref $value
132 or
133 is_literal_value($value)
134 );
135
4006691d 136 my $info = $self->result_source->column_info($col) or
89279e9d 137 $self->throw_exception("No column info for $col");
3705e3b2 138
89279e9d 139 return $value unless exists $info->{_inflate_info};
3705e3b2 140
5ae153d7 141 return (
142 $info->{_inflate_info}{deflate}
143 ||
144 $self->throw_exception("No deflator found for '$col'")
145 )->($value, $self);
0e5c2582 146}
147
7eb4ecc8 148=head2 get_inflated_column
149
150 my $val = $obj->get_inflated_column($col);
151
152Fetch a column value in its inflated state. This is directly
153analogous to L<DBIx::Class::Row/get_column> in that it only fetches a
48580715 154column already retrieved from the database, and then inflates it.
7eb4ecc8 155Throws an exception if the column requested is not an inflated column.
156
157=cut
158
0e5c2582 159sub get_inflated_column {
160 my ($self, $col) = @_;
5ae153d7 161
bc0c9800 162 $self->throw_exception("$col is not an inflated column")
4006691d 163 unless exists $self->result_source->column_info($col)->{_inflate_info};
5ae153d7 164
165 # we take care of keeping things in sync
0e5c2582 166 return $self->{_inflated_column}{$col}
167 if exists $self->{_inflated_column}{$col};
f92b166e 168
169 my $val = $self->get_column($col);
3705e3b2 170
f92b166e 171 return $self->{_inflated_column}{$col} = $self->_inflated_column($col, $val);
0e5c2582 172}
173
7eb4ecc8 174=head2 set_inflated_column
175
176 my $copy = $obj->set_inflated_column($col => $val);
177
178Sets a column value from an inflated value. This is directly
179analogous to L<DBIx::Class::Row/set_column>.
180
181=cut
182
0e5c2582 183sub set_inflated_column {
5ae153d7 184 my ($self, $col, $value) = @_;
185
b342451e 186 # pass through deflated stuff
187 if (! length ref $value or is_literal_value($value)) {
188 $self->set_column($col, $value);
9b2c0de6 189 delete $self->{_inflated_column}{$col};
9f471067 190 }
b342451e 191 # need to call set_column with the deflate cycle so that
192 # relationship caches are nuked if any
193 # also does the compare-for-dirtyness and change tracking dance
194 else {
195 $self->set_column($col, $self->_deflated_column($col, $value));
196 $self->{_inflated_column}{$col} = $value;
197 }
198
5ae153d7 199 return $value;
0e5c2582 200}
201
7eb4ecc8 202=head2 store_inflated_column
203
204 my $copy = $obj->store_inflated_column($col => $val);
205
206Sets a column value from an inflated value without marking the column
47c56124 207as dirty. This is directly analogous to L<DBIx::Class::Row/store_column>.
7eb4ecc8 208
209=cut
210
0e5c2582 211sub store_inflated_column {
5ae153d7 212 my ($self, $col, $value) = @_;
3705e3b2 213
b342451e 214 if (! length ref $value or is_literal_value($value)) {
3705e3b2 215 delete $self->{_inflated_column}{$col};
5ae153d7 216 $self->store_column($col => $value);
9f471067 217 }
3705e3b2 218 else {
219 delete $self->{_column_data}{$col};
5ae153d7 220 $self->{_inflated_column}{$col} = $value;
3705e3b2 221 }
222
5ae153d7 223 return $value;
180c7679 224}
4a07648a 225
bcae85db 226=head1 SEE ALSO
227
228=over 4
229
230=item L<DBIx::Class::Core> - This component is loaded as part of the
d88ecca6 231 C<core> L<DBIx::Class> components; generally there is no need to
bcae85db 232 load it directly
233
234=back
235
a2bd3796 236=head1 FURTHER QUESTIONS?
bcae85db 237
a2bd3796 238Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
bcae85db 239
a2bd3796 240=head1 COPYRIGHT AND LICENSE
bcae85db 241
a2bd3796 242This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
243by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
244redistribute it and/or modify it under the same terms as the
245L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
bcae85db 246
247=cut
248
0e5c2582 2491;