Deprecate UTF8Columns with a lot of warning whistles

Changes

@@ -3,6 +3,8 @@ Revision history for DBIx::Class
         - Support for Firebird RDBMS with DBD::InterBase and ODBC
         - Add core support for INSERT RETURNING (for storages that
           supports this syntax, currently PostgreSQL and Firebird)
+        - Fix spurious warnings on multiple UTF8Columns component loads
+        - DBIx::Class::UTF8Columns entered deprecated state
         - DBIx::Class::InflateColumn::File entered deprecated state
         - DBIx::Class::Optional::Dependencies left experimental state
         - Add req_group_list to Opt::Deps (RT#55211)
@@ -31,8 +33,6 @@ Revision history for DBIx::Class
           (RT#54063)
         - Support add_columns('+colname' => { ... }) to augment column
           definitions.
-        - Fix spurious warnings on multiple UTF8Columns component loads
-        - Unicode support documentation in Cookbook and UTF8Columns
 
 0.08120 2010-02-24 08:58:00 (UTC)
         - Make sure possibly overwritten deployment_statements methods in

lib/DBIx/Class/Componentised.pm

@@ -8,6 +8,8 @@ use base 'Class::C3::Componentised';
 use Carp::Clan qw/^DBIx::Class|^Class::C3::Componentised/;
 use mro 'c3';
 
+my $warned;
+
 # this warns of subtle bugs introduced by UTF8Columns hacky handling of store_column
 # if and only if it is placed before something overriding store_column
 sub inject_base {
@@ -21,7 +23,7 @@ sub inject_base {
     $target->isa ('DBIx::Class::ForceUTF8')
   );
 
-  my (@target_isa, $base_store_column);
+  my @target_isa;
 
   while ($keep_checking && @complist) {
 
@@ -30,13 +32,21 @@ sub inject_base {
 
     my $comp = pop @complist;
 
-    if ($comp->isa ('DBIx::Class::UTF8Columns') || $comp->isa ('DBIx::Class::ForceUTF8') {
-
-      $keep_checking = 0;
+    # warn here on use of either component, as we have no access to ForceUTF8,
+    # the author does not respond, and the Catalyst wiki used to recommend it
+    for (qw/DBIx::Class::UTF8Columns DBIx::Class::ForceUTF8/) {
+      if ($comp->isa ($_) ) {
+        $keep_checking = 0; # no use to check from this point on
+        carp "Use of $_ is strongly discouraged. See documentationm of DBIx::Class::UTF8Columns for more info\n"
+          unless ($warned->{UTF8Columns}++ || $ENV{DBIC_UTF8COLUMNS_OK});
+        last;
+      }
+    }
 
-      $base_store_column ||=
-        do { require DBIx::Class::Row; DBIx::Class::Row->can ('store_column') };
+    # something unset $keep_checking - we got a unicode mangler
+    if (! $keep_checking) {
 
+      my $base_store_column = do { require DBIx::Class::Row; DBIx::Class::Row->can ('store_column') };
 
       my @broken;
       for my $existing_comp (@target_isa) {

lib/DBIx/Class/UTF8Columns.pm

@@ -7,10 +7,7 @@ __PACKAGE__->mk_classdata( '_utf8_columns' );
 
 =head1 NAME
 
-DBIx::Class::UTF8Columns - Force UTF8 (Unicode) flag on columns
-
-   Please ensure you understand the purpose of this module before use.
-   Read the warnings below to prevent data corruption through misuse.
+DBIx::Class::UTF8Columns - Force UTF8 (Unicode) flag on columns (DEPRECATED)
 
 =head1 SYNOPSIS
 
@@ -31,6 +28,36 @@ in a database that does not natively support unicode. It ensures
 that column data is correctly serialised as a byte stream when
 stored and de-serialised to unicode strings on retrieval.
 
+  THE USE OF THIS MODULE (AND ITS COUSIN DBIx::Class::ForceUTF8) IS VERY
+  STRONGLY DISCOURAGED, PLEASE READ THE WARNINGS BELOW FOR AN EXPLANATION.
+
+If you want to continue using this module and do not want to recieve
+further warnings set the environmane variable C<DBIC_UTF8COLUMNS_OK>
+to a true value.
+
+=head2 Warning - Module does not function properly on create/insert
+
+Recently (April 2010) a bug was found deep in the core of L<DBIx::Class>
+which affects any component attempting to perform encoding/decoding by
+overloading L<store_column|DBIx::Class::Row/store_column> and
+L<get_columns|DBIx::Class::Row/get_columns>. As a result of this problem
+L<create|DBIx::Class::ResultSet/create> sends the original column values
+to the database, while L<update|DBIx::Class::ResultSet/update> sends the
+encoded values. L<DBIx::Class::UTF8Columns> and L<DBIx::Class::ForceUTF8>
+are both affected by ths bug.
+
+It is unclear how this bug went undetected for so long (it was
+introduced in March 2006), No attempts to fix it will be made while the
+implications of changing such a fundamental behavior of DBIx::Class are
+being evaluated. However in this day and age you should not be using
+this module anyway as Unicode is properly supported by all major
+database engines, as explained below.
+
+If you have specific questions about the integrity of your data in light
+of this development - please 
+L<join us on IRC or the mailing list|DBIx::Class/GETTING HELP/SUPPORT>
+to further discuss your concerns with the team.
+
 =head2 Warning - Native Database Unicode Support
 
 If your database natively supports Unicode (as does SQLite with the
@@ -40,8 +67,8 @@ then this component should B<not> be used, and will corrupt unicode
 data in a subtle and unexpected manner.
 
 It is far better to do Unicode support within the database if
-possible rather convert data into and out of the database on every
-round trip.
+possible rather than converting data to and from raw bytes on every
+database round trip.
 
 =head2 Warning - Component Overloading
 

t/85utf8.t

@@ -22,6 +22,7 @@ use DBICTest;
 
 warnings_are (
   sub {
+    local $ENV{DBIC_UTF8COLUMNS_OK} = 1;
     package A::Test1;
     use base 'DBIx::Class::Core';
     __PACKAGE__->load_components(qw(Core +A::Comp Ordered UTF8Columns));