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