1 package DBIx::Class::InflateColumn;
6 use base 'DBIx::Class::Row';
7 use DBIx::Class::_Util '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->column_info($col);
92 $self->throw_exception("InflateColumn does not work with FilterColumn")
93 if $self->isa('DBIx::Class::FilterColumn') &&
94 defined $colinfo->{_filter_info};
96 $self->throw_exception("No such column $col to inflate")
97 unless $self->has_column($col);
98 $self->throw_exception("inflate_column needs attr hashref")
99 unless ref $attrs eq 'HASH';
100 $colinfo->{_inflate_info} = $attrs;
101 my $acc = $colinfo->{accessor};
102 $self->mk_group_accessors('inflated_column' => [ (defined $acc ? $acc : $col), $col]);
106 sub _inflated_column {
107 my ($self, $col, $value) = @_;
108 return $value unless defined $value; # NULL is NULL is NULL
110 my $info = $self->column_info($col)
111 or $self->throw_exception("No column info for $col");
113 return $value unless exists $info->{_inflate_info};
115 my $inflate = $info->{_inflate_info}{inflate};
116 $self->throw_exception("No inflator for $col") unless defined $inflate;
118 return $inflate->($value, $self);
121 sub _deflated_column {
122 my ($self, $col, $value) = @_;
124 ## Deflate any refs except for literals, pass through plain values
128 is_literal_value($value)
131 my $info = $self->column_info($col) or
132 $self->throw_exception("No column info for $col");
134 return $value unless exists $info->{_inflate_info};
136 my $deflate = $info->{_inflate_info}{deflate};
137 $self->throw_exception("No deflator for $col") unless defined $deflate;
139 return $deflate->($value, $self);
142 =head2 get_inflated_column
144 my $val = $obj->get_inflated_column($col);
146 Fetch a column value in its inflated state. This is directly
147 analogous to L<DBIx::Class::Row/get_column> in that it only fetches a
148 column already retrieved from the database, and then inflates it.
149 Throws an exception if the column requested is not an inflated column.
153 sub get_inflated_column {
154 my ($self, $col) = @_;
155 $self->throw_exception("$col is not an inflated column")
156 unless exists $self->column_info($col)->{_inflate_info};
157 return $self->{_inflated_column}{$col}
158 if exists $self->{_inflated_column}{$col};
160 my $val = $self->get_column($col);
162 return $val if is_literal_value($val); #that would be a not-yet-reloaded literal update
164 return $self->{_inflated_column}{$col} = $self->_inflated_column($col, $val);
167 =head2 set_inflated_column
169 my $copy = $obj->set_inflated_column($col => $val);
171 Sets a column value from an inflated value. This is directly
172 analogous to L<DBIx::Class::Row/set_column>.
176 sub set_inflated_column {
177 my ($self, $col, $inflated) = @_;
178 $self->set_column($col, $self->_deflated_column($col, $inflated));
180 if (length ref $inflated and ! is_literal_value($inflated) ) {
181 $self->{_inflated_column}{$col} = $inflated;
183 delete $self->{_inflated_column}{$col};
188 =head2 store_inflated_column
190 my $copy = $obj->store_inflated_column($col => $val);
192 Sets a column value from an inflated value without marking the column
193 as dirty. This is directly analogous to L<DBIx::Class::Row/store_column>.
197 sub store_inflated_column {
198 my ($self, $col, $inflated) = @_;
200 if (is_literal_value($inflated)) {
201 delete $self->{_inflated_column}{$col};
202 $self->store_column($col => $inflated);
205 delete $self->{_column_data}{$col};
206 $self->{_inflated_column}{$col} = $inflated;
216 =item L<DBIx::Class::Core> - This component is loaded as part of the
217 C<core> L<DBIx::Class> components; generally there is no need to
224 Matt S. Trout <mst@shadowcatsystems.co.uk>
228 Daniel Westermann-Clark <danieltwc@cpan.org> (documentation)
230 Jess Robinson <cpan@desert-island.demon.co.uk>
234 You may distribute this code under the same terms as Perl itself.