Expand/fortify the handling of attributes
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / CDBICompat.pm
1 package DBIx::Class::CDBICompat;
2
3 use strict;
4 use warnings;
5
6 BEGIN {
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   }
11 }
12
13 use base qw/DBIx::Class::Core DBIx::Class::DB/;
14
15 __PACKAGE__->load_own_components(qw/
16   Constraints
17   Triggers
18   ReadOnly
19   LiveObjectIndex
20   AttributeAPI
21   Stringify
22   DestroyWarning
23   Constructor
24   AccessorMapping
25   ColumnCase
26   Relationships
27   Copy
28   LazyLoading
29   AutoUpdate
30   TempColumns
31   GetSet
32   Retrieve
33   Pager
34   ColumnGroups
35   ColumnsAsHash
36   AbstractSearch
37   ImaDBI
38   Iterator
39 /);
40
41 1;
42
43 __END__
44
45 =head1 NAME
46
47 DBIx::Class::CDBICompat - Class::DBI Compatibility layer.
48
49 =head1 SYNOPSIS
50
51   package My::CDBI;
52   use base qw/DBIx::Class::CDBICompat/;
53
54   ...continue as Class::DBI...
55
56 =head1 DESCRIPTION
57
58 DBIx::Class features a fully featured compatibility layer with L<Class::DBI>
59 and some common plugins to ease transition for existing CDBI users.
60
61 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.
62
63
64 =head2 Plugins
65
66 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.
67
68 =head3 Class::DBI::AbstractSearch
69
70 C<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
74 C<nocache> is fully emulated.
75
76 =head3 Class::DBI::Sweet
77
78 The 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
82 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.
83
84
85 =head2 Choosing Features
86
87 In fact, this class is just a recipe containing all the features emulated.
88 If you like, you can choose which features to emulate by building your
89 own class and loading it like this:
90
91   package My::DB;
92   __PACKAGE__->load_own_components(qw/CDBICompat/);
93
94 this will automatically load the features included in My::DB::CDBICompat,
95 provided 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
106
107 =head1 LIMITATIONS
108
109 =head2 Unimplemented
110
111 The following methods and classes are not emulated, maybe in the future.
112
113 =over 4
114
115 =item Class::DBI::Query
116
117 Deprecated in Class::DBI.
118
119 =item Class::DBI::Column
120
121 Not documented in Class::DBI.  CDBICompat's columns() returns a plain string, not an object.
122
123 =item data_type()
124
125 Undocumented CDBI method.
126
127 =back
128
129 =head2 Limited Support
130
131 The following elements of Class::DBI have limited support.
132
133 =over 4
134
135 =item Class::DBI::Relationship
136
137 The semi-documented Class::DBI::Relationship objects returned by C<meta_info($type, $col)> are mostly emulated except for their C<args> method.
138
139 =item Relationships
140
141 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:
142
143     package Foo;
144     use base qw(Class::DBI);
145
146     Foo->table("foo");
147     Foo->columns( All => qw(this that bar) );
148
149     package Bar;
150     use base qw(Class::DBI);
151
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
160 =back
161
162 =head1 FURTHER QUESTIONS?
163
164 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
165
166 =head1 COPYRIGHT AND LICENSE
167
168 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
169 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
170 redistribute it and/or modify it under the same terms as the
171 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.