1 package DBIx::Class::UTF8Columns;
4 use base qw/DBIx::Class/;
6 __PACKAGE__->mk_classdata( '_utf8_columns' );
10 DBIx::Class::UTF8Columns - Force UTF8 (Unicode) flag on columns
12 Please ensure you understand the purpose of this module before use.
13 Read the warnings below to prevent data corruption through misuse.
18 use base 'DBIx::Class::Core';
20 __PACKAGE__->load_components(qw/UTF8Columns/);
21 __PACKAGE__->utf8_columns(qw/name description/);
23 # then belows return strings with utf8 flag
25 $artist->get_column('description');
29 This module allows you to get and store utf8 (unicode) column data
30 in a database that does not natively support unicode. It ensures
31 that column data is correctly serialised as a byte stream when
32 stored and de-serialised to unicode strings on retrieval.
34 =head2 Warning - Native Database Unicode Support
36 If your database natively supports Unicode (as does SQLite with the
37 C<sqlite_unicode> connect flag, MySQL with C<mysql_enable_utf8>
38 connect flag or Postgres with the C<pg_enable_utf8> connect flag),
39 then this component should B<not> be used, and will corrupt unicode
40 data in a subtle and unexpected manner.
42 It is far better to do Unicode support within the database if
43 possible rather convert data into and out of the database on every
46 =head2 Warning - Component Overloading
48 Note that this module overloads L<DBIx::Class::Row/store_column> in a way
49 that may prevent other components overloading the same method from working
50 correctly. This component must be the last one before L<DBIx::Class::Row>
51 (which is provided by L<DBIx::Class::Core>). DBIx::Class will detect such
52 incorrect component order and issue an appropriate warning, advising which
53 components need to be loaded differently.
57 L<Template::Stash::ForceUTF8>, L<DBIx::Class::UUIDColumns>.
68 foreach my $col (@_) {
69 $self->throw_exception("column $col doesn't exist")
70 unless $self->has_column($col);
72 return $self->_utf8_columns({ map { $_ => 1 } @_ });
74 return $self->_utf8_columns;
78 =head1 EXTENDED METHODS
85 my ( $self, $column ) = @_;
86 my $value = $self->next::method($column);
88 utf8::decode($value) if (
89 defined $value and $self->_is_utf8_column($column) and ! utf8::is_utf8($value)
101 my %data = $self->next::method(@_);
103 foreach my $col (keys %data) {
104 utf8::decode($data{$col}) if (
105 exists $data{$col} and defined $data{$col} and $self->_is_utf8_column($col) and ! utf8::is_utf8($data{$col})
117 my ( $self, $column, $value ) = @_;
119 # the dirtyness comparison must happen on the non-encoded value
122 if ( defined $value and $self->_is_utf8_column($column) and utf8::is_utf8($value) ) {
124 utf8::encode($value);
127 $self->next::method( $column, $value );
129 return $copy || $value;
132 # override this if you want to force everything to be encoded/decoded
133 sub _is_utf8_column {
134 # my ($self, $col) = @_;
135 return ($_[0]->utf8_columns || {})->{$_[1]};
140 See L<DBIx::Class/CONTRIBUTORS>.
144 You may distribute this code under the same terms as Perl itself.