1 package DBIx::Class::InflateColumn;
6 use base 'DBIx::Class::Row';
7 use SQL::Abstract 'is_literal_value';
12 DBIx::Class::InflateColumn - Automatically create references from column data
16 # In your table classes
17 __PACKAGE__->inflate_column('column_name', {
19 my ($raw_value_from_db, $result_object) = @_;
23 my ($inflated_value_from_user, $result_object) = @_;
30 This component translates column data into references, i.e. "inflating"
31 the column data. It also "deflates" references into an appropriate format
34 It can be used, for example, to automatically convert to and from
35 L<DateTime> objects for your date and time fields. There's a
36 convenience component to actually do that though, try
37 L<DBIx::Class::InflateColumn::DateTime>.
39 It will handle all types of references except scalar references. It
40 will not handle scalar values, these are ignored and thus passed
41 through to L<SQL::Abstract>. This is to allow setting raw values to
42 "just work". Scalar references are passed through to the database to
43 deal with, to allow such settings as C< \'year + 1'> and C< \'DEFAULT' >
46 If you want to filter plain scalar values and replace them with
47 something else, see L<DBIx::Class::FilterColumn>.
53 Instruct L<DBIx::Class> to inflate the given column.
55 In addition to the column name, you must provide C<inflate> and
56 C<deflate> methods. The C<inflate> method is called when you access
57 the field, while the C<deflate> method is called when the field needs
58 to used by the database.
60 For example, if you have a table C<events> with a timestamp field
61 named C<insert_time>, you could inflate the column in the
62 corresponding table class using something like:
64 __PACKAGE__->inflate_column('insert_time', {
66 my ($insert_time_raw_value, $event_result_object) = @_;
67 DateTime->from_epoch( epoch => $insert_time_raw_value );
70 my ($insert_time_dt_object, $event_result_object) = @_;
71 $insert_time_dt_object->epoch;
75 The coderefs you set for inflate and deflate are called with two parameters,
76 the first is the value of the column to be inflated/deflated, the second is
77 the result object itself.
79 In this example, calls to an event's C<insert_time> accessor return a
80 L<DateTime> object. This L<DateTime> object is later "deflated" back
81 to the integer epoch representation when used in the database layer.
82 For a much more thorough handling of the above example, please see
83 L<DBIx::Class::DateTime::Epoch>
88 my ($self, $col, $attrs) = @_;
90 my $colinfo = $self->result_source->columns_info([$col])->{$col};
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');
95 $self->throw_exception("No such column $col to inflate")
96 unless $self->result_source_instance->has_column($col);
97 $self->throw_exception("inflate_column needs attr hashref")
98 unless ref $attrs eq 'HASH';
99 $colinfo->{_inflate_info} = $attrs;
100 my $acc = $colinfo->{accessor};
101 $self->mk_group_accessors('inflated_column' => [ (defined $acc ? $acc : $col), $col]);
105 sub _inflated_column {
106 my ($self, $col, $value) = @_;
109 ! defined $value # NULL is NULL is NULL
111 is_literal_value($value) #that would be a not-yet-reloaded literal update
114 my $info = $self->result_source->columns_info([$col])->{$col};
116 return $value unless exists $info->{_inflate_info};
119 $info->{_inflate_info}{inflate}
121 $self->throw_exception("No inflator found for '$col'")
125 sub _deflated_column {
126 my ($self, $col, $value) = @_;
128 ## Deflate any refs except for literals, pass through plain values
132 is_literal_value($value)
135 my $info = $self->result_source->columns_info([$col])->{$col};
137 return $value unless exists $info->{_inflate_info};
140 $info->{_inflate_info}{deflate}
142 $self->throw_exception("No deflator found for '$col'")
146 =head2 get_inflated_column
148 my $val = $obj->get_inflated_column($col);
150 Fetch a column value in its inflated state. This is directly
151 analogous to L<DBIx::Class::Row/get_column> in that it only fetches a
152 column already retrieved from the database, and then inflates it.
153 Throws an exception if the column requested is not an inflated column.
157 sub get_inflated_column {
158 my ($self, $col) = @_;
160 $self->throw_exception("$col is not an inflated column")
161 unless exists $self->result_source->columns_info->{$col}{_inflate_info};
163 # we take care of keeping things in sync
164 return $self->{_inflated_column}{$col}
165 if exists $self->{_inflated_column}{$col};
167 my $val = $self->get_column($col);
169 return $self->{_inflated_column}{$col} = $self->_inflated_column($col, $val);
172 =head2 set_inflated_column
174 my $copy = $obj->set_inflated_column($col => $val);
176 Sets a column value from an inflated value. This is directly
177 analogous to L<DBIx::Class::Row/set_column>.
181 sub set_inflated_column {
182 my ($self, $col, $value) = @_;
184 # pass through deflated stuff
185 if (! length ref $value or is_literal_value($value)) {
186 $self->set_column($col, $value);
187 delete $self->{_inflated_column}{$col};
189 # need to call set_column with the deflate cycle so that
190 # relationship caches are nuked if any
191 # also does the compare-for-dirtyness and change tracking dance
193 $self->set_column($col, $self->_deflated_column($col, $value));
194 $self->{_inflated_column}{$col} = $value;
200 =head2 store_inflated_column
202 my $copy = $obj->store_inflated_column($col => $val);
204 Sets a column value from an inflated value without marking the column
205 as dirty. This is directly analogous to L<DBIx::Class::Row/store_column>.
209 sub store_inflated_column {
210 my ($self, $col, $value) = @_;
212 if (! length ref $value or is_literal_value($value)) {
213 delete $self->{_inflated_column}{$col};
214 $self->store_column($col => $value);
217 delete $self->{_column_data}{$col};
218 $self->{_inflated_column}{$col} = $value;
228 =item L<DBIx::Class::Core> - This component is loaded as part of the
229 C<core> L<DBIx::Class> components; generally there is no need to
234 =head1 FURTHER QUESTIONS?
236 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
238 =head1 COPYRIGHT AND LICENSE
240 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
241 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
242 redistribute it and/or modify it under the same terms as the
243 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.