lib/DBIx/Class/CDBICompat.pm

   1 package DBIx::Class::CDBICompat;
   2
   3 use strict;
   4 use warnings;
   5 use base qw/DBIx::Class::Core DBIx::Class::DB/;
   6 use Carp::Clan qw/^DBIx::Class/;
   7
   8 eval {
   9   require Class::Trigger;
  10   require DBIx::ContextualFetch;
  11 };
  12 croak "Class::Trigger and DBIx::ContextualFetch is required for CDBICompat" if $@;
  13
  14 __PACKAGE__->load_own_components(qw/
  15   Constraints
  16   Triggers
  17   ReadOnly
  18   LiveObjectIndex
  19   AttributeAPI
  20   Stringify
  21   DestroyWarning
  22   Constructor
  23   AccessorMapping
  24   ColumnCase
  25   Relationships
  26   Copy
  27   LazyLoading
  28   AutoUpdate
  29   TempColumns
  30   GetSet
  31   Retrieve
  32   Pager
  33   ColumnGroups
  34   ColumnsAsHash
  35   AbstractSearch
  36   ImaDBI
  37   Iterator
  38 /);
  39
  40             #DBIx::Class::ObjIndexStubs
  41 1;
  42
  43 =head1 NAME
  44
  45 DBIx::Class::CDBICompat - Class::DBI Compatibility layer.
  46
  47 =head1 SYNOPSIS
  48
  49   package My::CDBI;
  50   use base qw/DBIx::Class::CDBICompat/;
  51
  52   ...continue as Class::DBI...
  53
  54 =head1 DESCRIPTION
  55
  56 DBIx::Class features a fully featured compatibility layer with L<Class::DBI>
  57 and some common plugins to ease transition for existing CDBI users.
  58
  59 This is not a wrapper or subclass of DBIx::Class but rather a series of plugins.  The result being that even though you're using the Class::DBI emulation layer you are still getting DBIx::Class objects.  You can use all DBIx::Class features and methods via CDBICompat.  This allows you to take advantage of DBIx::Class features without having to rewrite your CDBI code.
  60
  61
  62 =head2 Plugins
  63
  64 CDBICompat is good enough that many CDBI plugins will work with CDBICompat, but many of the plugin features are better done with DBIx::Class methods.
  65
  66 =head3 Class::DBI::AbstractSearch
  67
  68 C<search_where()> is fully emulated using DBIC's search.  Aside from emulation there's no reason to use C<search_where()>.
  69
  70 =head3 Class::DBI::Plugin::NoCache
  71
  72 C<nocache> is fully emulated.
  73
  74 =head3 Class::DBI::Sweet
  75
  76 The features of CDBI::Sweet are better done using DBIC methods which are almost exactly the same.  It even uses L<Data::Page>.
  77
  78 =head3 Class::DBI::Plugin::DeepAbstractSearch
  79
  80 This is better done using DBIC's native search facilities.  The major difference is that DBIC will not infer the join for you, you have to tell it the join tables.
  81
  82
  83 =head2 Choosing Features
  84
  85 In fact, this class is just a receipe containing all the features emulated.
  86 If you like, you can choose which features to emulate by building your
  87 own class and loading it like this:
  88
  89   package My::DB;
  90   __PACKAGE__->load_own_components(qw/CDBICompat/);
  91
  92 this will automatically load the features included in My::DB::CDBICompat,
  93 provided it looks something like this:
  94
  95   package My::DB::CDBICompat;
  96   __PACKAGE__->load_components(qw/
  97     CDBICompat::ColumnGroups
  98     CDBICompat::Retrieve
  99     CDBICompat::HasA
 100     CDBICompat::HasMany
 101     CDBICompat::MightHave
 102   /);
 103
 104
 105 =head1 LIMITATIONS
 106
 107 =head2 Unimplemented
 108
 109 The following methods and classes are not emulated, maybe in the future.
 110
 111 =over 4
 112
 113 =item Class::DBI::Query
 114
 115 Deprecated in Class::DBI.
 116
 117 =item Class::DBI::Column
 118
 119 Not documented in Class::DBI.  CDBICompat's columns() returns a plain string, not an object.
 120
 121 =item data_type()
 122
 123 Undocumented CDBI method.
 124
 125 =back
 126
 127 =head2 Limited Support
 128
 129 The following elements of Class::DBI have limited support.
 130
 131 =over 4
 132
 133 =item Class::DBI::Relationship
 134
 135 The semi-documented Class::DBI::Relationship objects returned by C<meta_info($type, $col)> are mostly emulated except for their C<args> method.
 136
 137 =item Relationships
 138
 139 Relationships between tables (has_a, has_many...) must be delcared after all tables in the relationship have been declared.  Thus the usual CDBI idiom of declaring columns and relationships for each class together will not work.  They must instead be done like so:
 140
 141     package Foo;
 142     use base qw(Class::DBI);
 143
 144     Foo->table("foo");
 145     Foo->columns( All => qw(this that bar) );
 146
 147     package Bar;
 148     use base qw(Class::DBI);
 149
 150     Bar->table("bar");
 151     Bar->columns( All => qw(up down) );
 152
 153     # Now that Foo and Bar are declared it is safe to declare a
 154     # relationship between them
 155     Foo->has_a( bar => "Bar" );
 156
 157
 158 =back
 159
 160 =head1 AUTHORS
 161
 162 Matt S. Trout <mst@shadowcatsystems.co.uk>
 163
 164 =head1 LICENSE
 165
 166 You may distribute this code under the same terms as Perl itself.
 167
 168 =cut
 169