Consider where condition when determining leftmost order stability
[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / CDBICompat.pm
CommitLineData
ea2e61bf 1package DBIx::Class::CDBICompat;
2
3use strict;
4use warnings;
75a23b3e 5use base qw/DBIx::Class::Core DBIx::Class::DB/;
289ba852 6
118edec6 7# Modules CDBICompat needs that DBIx::Class does not.
8my @Extra_Modules = qw(
9 Class::Trigger
10 DBIx::ContextualFetch
11 Clone
12);
d4daee7b 13
118edec6 14my @didnt_load;
15for my $module (@Extra_Modules) {
16 push @didnt_load, $module unless eval qq{require $module};
17}
70c28808 18__PACKAGE__->throw_exception("@{[ join ', ', @didnt_load ]} are missing and are required for CDBICompat")
118edec6 19 if @didnt_load;
20
126042ee 21
55e2d745 22__PACKAGE__->load_own_components(qw/
23 Constraints
24 Triggers
25 ReadOnly
55e2d745 26 LiveObjectIndex
27 AttributeAPI
28 Stringify
29 DestroyWarning
30 Constructor
31 AccessorMapping
32 ColumnCase
a9c8094b 33 Relationships
e60dc79f 34 Copy
55e2d745 35 LazyLoading
36 AutoUpdate
37 TempColumns
e60dc79f 38 GetSet
55e2d745 39 Retrieve
2a21de92 40 Pager
55e2d745 41 ColumnGroups
5ef62e9f 42 ColumnsAsHash
e60dc79f 43 AbstractSearch
44 ImaDBI
45 Iterator
46/);
55e2d745 47
48 #DBIx::Class::ObjIndexStubs
ea2e61bf 491;
34d52be2 50
75d07914 51=head1 NAME
34d52be2 52
880a1a0c 53DBIx::Class::CDBICompat - Class::DBI Compatibility layer.
34d52be2 54
15fe6346 55=head1 SYNOPSIS
56
4965b78d 57 package My::CDBI;
58 use base qw/DBIx::Class::CDBICompat/;
59
60 ...continue as Class::DBI...
15fe6346 61
34d52be2 62=head1 DESCRIPTION
63
880a1a0c 64DBIx::Class features a fully featured compatibility layer with L<Class::DBI>
8273e845 65and some common plugins to ease transition for existing CDBI users.
4965b78d 66
67This 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
72CDBICompat 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
76C<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
80C<nocache> is fully emulated.
81
82=head3 Class::DBI::Sweet
83
84The 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
fbee5c55 88This 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.
4965b78d 89
90
91=head2 Choosing Features
e7d1440f 92
48580715 93In fact, this class is just a recipe containing all the features emulated.
8273e845 94If you like, you can choose which features to emulate by building your
e7d1440f 95own class and loading it like this:
15fe6346 96
4965b78d 97 package My::DB;
15fe6346 98 __PACKAGE__->load_own_components(qw/CDBICompat/);
99
75d07914 100this will automatically load the features included in My::DB::CDBICompat,
15fe6346 101provided 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
34d52be2 112
e7d1440f 113=head1 LIMITATIONS
114
af133470 115=head2 Unimplemented
116
e7d1440f 117The following methods and classes are not emulated, maybe in the future.
118
119=over 4
120
121=item Class::DBI::Query
122
123Deprecated in Class::DBI.
124
125=item Class::DBI::Column
126
127Not documented in Class::DBI. CDBICompat's columns() returns a plain string, not an object.
128
129=item data_type()
130
131Undocumented CDBI method.
132
af133470 133=back
134
135=head2 Limited Support
136
137The following elements of Class::DBI have limited support.
138
139=over 4
140
474481a9 141=item Class::DBI::Relationship
e7d1440f 142
474481a9 143The semi-documented Class::DBI::Relationship objects returned by C<meta_info($type, $col)> are mostly emulated except for their C<args> method.
e7d1440f 144
af133470 145=item Relationships
146
48580715 147Relationships 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:
af133470 148
149 package Foo;
150 use base qw(Class::DBI);
d4daee7b 151
af133470 152 Foo->table("foo");
153 Foo->columns( All => qw(this that bar) );
154
155 package Bar;
156 use base qw(Class::DBI);
d4daee7b 157
af133470 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
e7d1440f 166=back
167
0c11ad0e 168=head1 AUTHOR AND CONTRIBUTORS
34d52be2 169
0c11ad0e 170See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
34d52be2 171
172=head1 LICENSE
173
174You may distribute this code under the same terms as Perl itself.
175
176=cut
177