lib/DBIx/Class/InflateColumn.pm

   1 package DBIx::Class::InflateColumn;
   2
   3 use strict;
   4 use warnings;
   5
   6 use base 'DBIx::Class::Row';
   7 use DBIx::Class::_Util 'is_literal_value';
   8 use namespace::clean;
   9
  10 =head1 NAME
  11
  12 DBIx::Class::InflateColumn - Automatically create references from column data
  13
  14 =head1 SYNOPSIS
  15
  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   });
  27
  28 =head1 DESCRIPTION
  29
  30 This component translates column data into references, i.e. "inflating"
  31 the column data. It also "deflates" references into an appropriate format
  32 for the database.
  33
  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>.
  38
  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' >
  44 to work.
  45
  46 If you want to filter plain scalar values and replace them with
  47 something else, see L<DBIx::Class::FilterColumn>.
  48
  49 =head1 METHODS
  50
  51 =head2 inflate_column
  52
  53 Instruct L<DBIx::Class> to inflate the given column.
  54
  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.
  59
  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:
  63
  64     __PACKAGE__->inflate_column('insert_time', {
  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         },
  73     });
  74
  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.
  78
  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>
  84
  85 =cut
  86
  87 sub inflate_column {
  88   my ($self, $col, $attrs) = @_;
  89
  90   my $colinfo = $self->column_info($col);
  91
  92   $self->throw_exception("InflateColumn does not work with FilterColumn")
  93     if $self->isa('DBIx::Class::FilterColumn') &&
  94       defined $colinfo->{_filter_info};
  95
  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]);
 103   return 1;
 104 }
 105
 106 sub _inflated_column {
 107   my ($self, $col, $value) = @_;
 108   return $value unless defined $value; # NULL is NULL is NULL
 109
 110   my $info = $self->column_info($col)
 111     or $self->throw_exception("No column info for $col");
 112
 113   return $value unless exists $info->{_inflate_info};
 114
 115   my $inflate = $info->{_inflate_info}{inflate};
 116   $self->throw_exception("No inflator for $col") unless defined $inflate;
 117
 118   return $inflate->($value, $self);
 119 }
 120
 121 sub _deflated_column {
 122   my ($self, $col, $value) = @_;
 123
 124   ## Deflate any refs except for literals, pass through plain values
 125   return $value if (
 126     ! length ref $value
 127       or
 128     is_literal_value($value)
 129   );
 130
 131   my $info = $self->column_info($col) or
 132     $self->throw_exception("No column info for $col");
 133
 134   return $value unless exists $info->{_inflate_info};
 135
 136   my $deflate = $info->{_inflate_info}{deflate};
 137   $self->throw_exception("No deflator for $col") unless defined $deflate;
 138
 139   return $deflate->($value, $self);
 140 }
 141
 142 =head2 get_inflated_column
 143
 144   my $val = $obj->get_inflated_column($col);
 145
 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.
 150
 151 =cut
 152
 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};
 159
 160   my $val = $self->get_column($col);
 161
 162   return $val if is_literal_value($val);  #that would be a not-yet-reloaded literal update
 163
 164   return $self->{_inflated_column}{$col} = $self->_inflated_column($col, $val);
 165 }
 166
 167 =head2 set_inflated_column
 168
 169   my $copy = $obj->set_inflated_column($col => $val);
 170
 171 Sets a column value from an inflated value.  This is directly
 172 analogous to L<DBIx::Class::Row/set_column>.
 173
 174 =cut
 175
 176 sub set_inflated_column {
 177   my ($self, $col, $inflated) = @_;
 178   $self->set_column($col, $self->_deflated_column($col, $inflated));
 179
 180   if (length ref $inflated and ! is_literal_value($inflated) ) {
 181     $self->{_inflated_column}{$col} = $inflated;
 182   } else {
 183     delete $self->{_inflated_column}{$col};
 184   }
 185   return $inflated;
 186 }
 187
 188 =head2 store_inflated_column
 189
 190   my $copy = $obj->store_inflated_column($col => $val);
 191
 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>.
 194
 195 =cut
 196
 197 sub store_inflated_column {
 198   my ($self, $col, $inflated) = @_;
 199
 200   if (is_literal_value($inflated)) {
 201     delete $self->{_inflated_column}{$col};
 202     $self->store_column($col => $inflated);
 203   }
 204   else {
 205     delete $self->{_column_data}{$col};
 206     $self->{_inflated_column}{$col} = $inflated;
 207   }
 208
 209   return $inflated;
 210 }
 211
 212 =head1 SEE ALSO
 213
 214 =over 4
 215
 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
 218       load it directly
 219
 220 =back
 221
 222 =head1 AUTHOR
 223
 224 Matt S. Trout <mst@shadowcatsystems.co.uk>
 225
 226 =head1 CONTRIBUTORS
 227
 228 Daniel Westermann-Clark <danieltwc@cpan.org> (documentation)
 229
 230 Jess Robinson <cpan@desert-island.demon.co.uk>
 231
 232 =head1 LICENSE
 233
 234 You may distribute this code under the same terms as Perl itself.
 235
 236 =cut
 237
 238 1;