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
   7 unless (DBIx::Class::Optional::Dependencies->req_ok_for('cdbicompat')) {
   8   __PACKAGE__->throw_exception(Class::Optional::Dependencies->req_missing_for('cdbicompat') . ' are missing and are required for CDBICompat');
   9 }
  10
  11 __PACKAGE__->load_own_components(qw/
  12   Constraints
  13   Triggers
  14   ReadOnly
  15   LiveObjectIndex
  16   AttributeAPI
  17   Stringify
  18   DestroyWarning
  19   Constructor
  20   AccessorMapping
  21   ColumnCase
  22   Relationships
  23   Copy
  24   LazyLoading
  25   AutoUpdate
  26   TempColumns
  27   GetSet
  28   Retrieve
  29   Pager
  30   ColumnGroups
  31   ColumnsAsHash
  32   AbstractSearch
  33   ImaDBI
  34   Iterator
  35 /);
  36
  37 1;
  38
  39 __END__
  40
  41 =head1 NAME
  42
  43 DBIx::Class::CDBICompat - Class::DBI Compatibility layer.
  44
  45 =head1 SYNOPSIS
  46
  47   package My::CDBI;
  48   use base qw/DBIx::Class::CDBICompat/;
  49
  50   ...continue as Class::DBI...
  51
  52 =head1 DESCRIPTION
  53
  54 DBIx::Class features a fully featured compatibility layer with L<Class::DBI>
  55 and some common plugins to ease transition for existing CDBI users.
  56
  57 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.
  58
  59
  60 =head2 Plugins
  61
  62 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.
  63
  64 =head3 Class::DBI::AbstractSearch
  65
  66 C<search_where()> is fully emulated using DBIC's search.  Aside from emulation there's no reason to use C<search_where()>.
  67
  68 =head3 Class::DBI::Plugin::NoCache
  69
  70 C<nocache> is fully emulated.
  71
  72 =head3 Class::DBI::Sweet
  73
  74 The features of CDBI::Sweet are better done using DBIC methods which are almost exactly the same.  It even uses L<Data::Page>.
  75
  76 =head3 Class::DBI::Plugin::DeepAbstractSearch
  77
  78 This plugin will work, but it is more efficiently 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.
  79
  80
  81 =head2 Choosing Features
  82
  83 In fact, this class is just a recipe containing all the features emulated.
  84 If you like, you can choose which features to emulate by building your
  85 own class and loading it like this:
  86
  87   package My::DB;
  88   __PACKAGE__->load_own_components(qw/CDBICompat/);
  89
  90 this will automatically load the features included in My::DB::CDBICompat,
  91 provided it looks something like this:
  92
  93   package My::DB::CDBICompat;
  94   __PACKAGE__->load_components(qw/
  95     CDBICompat::ColumnGroups
  96     CDBICompat::Retrieve
  97     CDBICompat::HasA
  98     CDBICompat::HasMany
  99     CDBICompat::MightHave
 100   /);
 101
 102
 103 =head1 LIMITATIONS
 104
 105 =head2 Unimplemented
 106
 107 The following methods and classes are not emulated, maybe in the future.
 108
 109 =over 4
 110
 111 =item Class::DBI::Query
 112
 113 Deprecated in Class::DBI.
 114
 115 =item Class::DBI::Column
 116
 117 Not documented in Class::DBI.  CDBICompat's columns() returns a plain string, not an object.
 118
 119 =item data_type()
 120
 121 Undocumented CDBI method.
 122
 123 =back
 124
 125 =head2 Limited Support
 126
 127 The following elements of Class::DBI have limited support.
 128
 129 =over 4
 130
 131 =item Class::DBI::Relationship
 132
 133 The semi-documented Class::DBI::Relationship objects returned by C<meta_info($type, $col)> are mostly emulated except for their C<args> method.
 134
 135 =item Relationships
 136
 137 Relationships between tables (has_a, has_many...) must be declared 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:
 138
 139     package Foo;
 140     use base qw(Class::DBI);
 141
 142     Foo->table("foo");
 143     Foo->columns( All => qw(this that bar) );
 144
 145     package Bar;
 146     use base qw(Class::DBI);
 147
 148     Bar->table("bar");
 149     Bar->columns( All => qw(up down) );
 150
 151     # Now that Foo and Bar are declared it is safe to declare a
 152     # relationship between them
 153     Foo->has_a( bar => "Bar" );
 154
 155
 156 =back
 157
 158 =head1 FURTHER QUESTIONS?
 159
 160 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
 161
 162 =head1 COPYRIGHT AND LICENSE
 163
 164 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
 165 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
 166 redistribute it and/or modify it under the same terms as the
 167 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.