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 SQL::Abstract '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->result_source->columns_info([$col])->{$col};
  91
  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');
  94
  95   $self->throw_exception("inflate_column needs attr hashref")
  96     unless ref $attrs eq 'HASH';
  97
  98   $colinfo->{_inflate_info} = $attrs;
  99   my $acc = $colinfo->{accessor};
 100   $self->mk_group_accessors('inflated_column' => [ (defined $acc ? $acc : $col), $col]);
 101   return 1;
 102 }
 103
 104 sub _inflated_column {
 105   my ($self, $col, $value) = @_;
 106
 107   return $value if (
 108     ! defined $value # NULL is NULL is NULL
 109       or
 110     is_literal_value($value) #that would be a not-yet-reloaded literal update
 111   );
 112
 113   my $info = $self->result_source->columns_info([$col])->{$col};
 114
 115   return $value unless exists $info->{_inflate_info};
 116
 117   return (
 118     $info->{_inflate_info}{inflate}
 119       ||
 120     $self->throw_exception("No inflator found for '$col'")
 121   )->($value, $self);
 122 }
 123
 124 sub _deflated_column {
 125   my ($self, $col, $value) = @_;
 126
 127   ## Deflate any refs except for literals, pass through plain values
 128   return $value if (
 129     ! length ref $value
 130       or
 131     is_literal_value($value)
 132   );
 133
 134   my $info = $self->result_source->columns_info([$col])->{$col};
 135
 136   return $value unless exists $info->{_inflate_info};
 137
 138   return (
 139     $info->{_inflate_info}{deflate}
 140       ||
 141     $self->throw_exception("No deflator found for '$col'")
 142   )->($value, $self);
 143 }
 144
 145 =head2 get_inflated_column
 146
 147   my $val = $obj->get_inflated_column($col);
 148
 149 Fetch a column value in its inflated state.  This is directly
 150 analogous to L<DBIx::Class::Row/get_column> in that it only fetches a
 151 column already retrieved from the database, and then inflates it.
 152 Throws an exception if the column requested is not an inflated column.
 153
 154 =cut
 155
 156 sub get_inflated_column {
 157   my ($self, $col) = @_;
 158
 159   $self->throw_exception("$col is not an inflated column")
 160     unless exists $self->result_source->columns_info->{$col}{_inflate_info};
 161
 162   # we take care of keeping things in sync
 163   return $self->{_inflated_column}{$col}
 164     if exists $self->{_inflated_column}{$col};
 165
 166   my $val = $self->get_column($col);
 167
 168   return $self->{_inflated_column}{$col} = $self->_inflated_column($col, $val);
 169 }
 170
 171 =head2 set_inflated_column
 172
 173   my $copy = $obj->set_inflated_column($col => $val);
 174
 175 Sets a column value from an inflated value.  This is directly
 176 analogous to L<DBIx::Class::Row/set_column>.
 177
 178 =cut
 179
 180 sub set_inflated_column {
 181   my ($self, $col, $value) = @_;
 182
 183   # pass through deflated stuff
 184   if (! length ref $value or is_literal_value($value)) {
 185     $self->set_column($col, $value);
 186     delete $self->{_inflated_column}{$col};
 187   }
 188   # need to call set_column with the deflate cycle so that
 189   # relationship caches are nuked if any
 190   # also does the compare-for-dirtyness and change tracking dance
 191   else {
 192     $self->set_column($col, $self->_deflated_column($col, $value));
 193     $self->{_inflated_column}{$col} = $value;
 194   }
 195
 196   return $value;
 197 }
 198
 199 =head2 store_inflated_column
 200
 201   my $copy = $obj->store_inflated_column($col => $val);
 202
 203 Sets a column value from an inflated value without marking the column
 204 as dirty. This is directly analogous to L<DBIx::Class::Row/store_column>.
 205
 206 =cut
 207
 208 sub store_inflated_column {
 209   my ($self, $col, $value) = @_;
 210
 211   if (! length ref $value or is_literal_value($value)) {
 212     delete $self->{_inflated_column}{$col};
 213     $self->store_column($col => $value);
 214   }
 215   else {
 216     delete $self->{_column_data}{$col};
 217     $self->{_inflated_column}{$col} = $value;
 218   }
 219
 220   return $value;
 221 }
 222
 223 =head1 SEE ALSO
 224
 225 =over 4
 226
 227 =item L<DBIx::Class::Core> - This component is loaded as part of the
 228       C<core> L<DBIx::Class> components; generally there is no need to
 229       load it directly
 230
 231 =back
 232
 233 =head1 FURTHER QUESTIONS?
 234
 235 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
 236
 237 =head1 COPYRIGHT AND LICENSE
 238
 239 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
 240 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
 241 redistribute it and/or modify it under the same terms as the
 242 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
 243
 244 =cut
 245
 246 1;