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("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]);
 102   return 1;
 103 }
 104
 105 sub _inflated_column {
 106   my ($self, $col, $value) = @_;
 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   );
 113
 114   my $info = $self->result_source->columns_info([$col])->{$col};
 115
 116   return $value unless exists $info->{_inflate_info};
 117
 118   return (
 119     $info->{_inflate_info}{inflate}
 120       ||
 121     $self->throw_exception("No inflator found for '$col'")
 122   )->($value, $self);
 123 }
 124
 125 sub _deflated_column {
 126   my ($self, $col, $value) = @_;
 127
 128   ## Deflate any refs except for literals, pass through plain values
 129   return $value if (
 130     ! length ref $value
 131       or
 132     is_literal_value($value)
 133   );
 134
 135   my $info = $self->result_source->columns_info([$col])->{$col};
 136
 137   return $value unless exists $info->{_inflate_info};
 138
 139   return (
 140     $info->{_inflate_info}{deflate}
 141       ||
 142     $self->throw_exception("No deflator found for '$col'")
 143   )->($value, $self);
 144 }
 145
 146 =head2 get_inflated_column
 147
 148   my $val = $obj->get_inflated_column($col);
 149
 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.
 154
 155 =cut
 156
 157 sub get_inflated_column {
 158   my ($self, $col) = @_;
 159
 160   $self->throw_exception("$col is not an inflated column")
 161     unless exists $self->result_source->columns_info->{$col}{_inflate_info};
 162
 163   # we take care of keeping things in sync
 164   return $self->{_inflated_column}{$col}
 165     if exists $self->{_inflated_column}{$col};
 166
 167   my $val = $self->get_column($col);
 168
 169   return $self->{_inflated_column}{$col} = $self->_inflated_column($col, $val);
 170 }
 171
 172 =head2 set_inflated_column
 173
 174   my $copy = $obj->set_inflated_column($col => $val);
 175
 176 Sets a column value from an inflated value.  This is directly
 177 analogous to L<DBIx::Class::Row/set_column>.
 178
 179 =cut
 180
 181 sub set_inflated_column {
 182   my ($self, $col, $value) = @_;
 183
 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};
 188   }
 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
 192   else {
 193     $self->set_column($col, $self->_deflated_column($col, $value));
 194     $self->{_inflated_column}{$col} = $value;
 195   }
 196
 197   return $value;
 198 }
 199
 200 =head2 store_inflated_column
 201
 202   my $copy = $obj->store_inflated_column($col => $val);
 203
 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>.
 206
 207 =cut
 208
 209 sub store_inflated_column {
 210   my ($self, $col, $value) = @_;
 211
 212   if (! length ref $value or is_literal_value($value)) {
 213     delete $self->{_inflated_column}{$col};
 214     $self->store_column($col => $value);
 215   }
 216   else {
 217     delete $self->{_column_data}{$col};
 218     $self->{_inflated_column}{$col} = $value;
 219   }
 220
 221   return $value;
 222 }
 223
 224 =head1 SEE ALSO
 225
 226 =over 4
 227
 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
 230       load it directly
 231
 232 =back
 233
 234 =head1 FURTHER QUESTIONS?
 235
 236 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
 237
 238 =head1 COPYRIGHT AND LICENSE
 239
 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>.
 244
 245 =cut
 246
 247 1;