view release on metacpan or  search on metacpan

lib/DBIx/Class/FrozenColumns.pm  view on Meta::CPAN

package DBIx::Class::FrozenColumns;
use base qw/DBIx::Class/;

use strict;
use warnings;

our $VERSION = 1.0;

__PACKAGE__->mk_group_accessors(inherited => qw/_frozen_columns _dirty_frozen_columns/);
__PACKAGE__->_frozen_columns({});

=head1 NAME

DBIx::Class::FrozenColumns - Store virtual columns inside another column.

=head1 SYNOPSIS

    package Artist;
    __PACKAGE__->load_components(qw/FrozenColumns Core/);
    __PACKAGE__->add_columns(qw/name description frozen/);
    __PACKAGE__->add_frozen_columns(
        frozen => qw/biography url img50x50 img100x100/
    );

    $artist->url('http://cpan.org');
    $artist->get_column('url');
    $artist->get_dirty_columns; # 'url' and 'frozen' are dirty
    $artist->update; #updates column 'frozen' (using Storable::freeze)

    $artistRS->create({
        name     => 'theodor bastard',
        img50x50 => '50x50.gif',
    }); #that's ok. 'img50x50' will be stored in 'frozen'

    my @artists = $artistRS->search({
        name => '.....',
        url  => 'http://cpan.org',
    }); # Error! no such column 'url'

    package Artist;
    __PACKAGE__->add_frozen_columns(
        biography => qw/childhood adolescence youth present/,
    );

    $artist->childhood('bla-bla-bla');
    $artist->update; #Updates column 'frozen'.

=head1 DESCRIPTION

This module allows you to store multiple columns in one. This is useful when
you want to store dynamic number of columns in database or you just don't know
what columns will be stored there. Or when you can't (or don't want) to alter
your tables in database.

Module allows you to transparently use this columns as if they were normal
columns in your table. With one obvious restriction: you cannot search rows in a
table and therefore you cannot add relationships using these columns (search is
needed to build reverse relationship).

Module handles its own dirty column management and will not update the parent
field unless any columns is changed.

Note: The component needs to be loaded before Core and plugin 'Ordered'.
If you get an error like 'no such column: <frozencolumn>' while updating a row
then try to move this module more closer to the start of the load_components
list.

Also note that frozen column IS NOT a real column of your result class.
This impose some restrictions on use of this columns such as searching, adding
relationships, has_column, get_columns, etc.
See L</EXTENDED METHODS> for the list of method that will work with frozen
columns (as will methods that use it).

Module unpacks frozen columns only once when you first accessing it and packs
when you call update.

You can also create frozen columns in another frozen column any level deep.
The only restriction is that they all use the same storing mechanism.

=head1 METHODS

=head2 add_frozen_columns

    __PACKAGE__->add_frozen_columns ($data_column, @columns)
    __PACKAGE__->add_frozen_columns ($hashref)

Adds frozen @columns to your result source class. These columns will be stored in
$data_column using Storable freeze/thaw algorithm.
If $hashref is specified instead, then below params is expected in it:
    data_column - same as $data_column
    columns     - same as @columns
    type        - class with custom mechanism of storing/restoring frozen cols
See below for more information about L</Custom frozen class>.

=head2 add_dumped_columns ($data_column, @columns)

Same as L</add_frozen_columns> but uses Data::Dumper mechanism.

=head2 add_json_columns ($data_column, @columns)

Same as L</add_frozen_columns> but uses JSON::XS mechanism.

=cut

sub add_frozen_columns {
    my $this = shift;
    my ($type, $data_column, @frozen_columns);

    if(ref $_[0]) {
        my $params = shift;
        $type           = $params->{type};
        $data_column    = $params->{data_column};
        @frozen_columns = @{$params->{columns}||[]};
    }
    else {