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