afc89f25f06c064c77ff5280b487d7eb963dc72c
[dbsrgits/DBIx-Class-Historic.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 use Carp::Clan qw/^DBIx::Class/;
7
8 eval {
9   require Class::Trigger;
10   require DBIx::ContextualFetch;
11 };
12 croak "Class::Trigger and DBIx::ContextualFetch is required for CDBICompat" if $@;
13
14 __PACKAGE__->load_own_components(qw/
15   Constraints
16   Triggers
17   ReadOnly
18   LiveObjectIndex
19   AttributeAPI
20   Stringify
21   DestroyWarning
22   Constructor
23   AccessorMapping
24   ColumnCase
25   Relationships
26   Copy
27   LazyLoading
28   AutoUpdate
29   TempColumns
30   GetSet
31   Retrieve
32   Pager
33   ColumnGroups
34   ColumnsAsHash
35   AbstractSearch
36   ImaDBI
37   Iterator
38 /);
39
40             #DBIx::Class::ObjIndexStubs
41 1;
42
43 =head1 NAME
44
45 DBIx::Class::CDBICompat - Class::DBI Compatibility layer.
46
47 =head1 SYNOPSIS
48
49   use base qw/DBIx::Class/;
50   __PACKAGE__->load_components(qw/CDBICompat Core DB/);
51
52 =head1 DESCRIPTION
53
54 DBIx::Class features a fully featured compatibility layer with L<Class::DBI>
55 and L<Class::DBI::AbstractSearch> to ease transition for existing CDBI users. 
56
57 In fact, this class is just a receipe containing all the features emulated.
58 If you like, you can choose which features to emulate by building your 
59 own class and loading it like this:
60
61   __PACKAGE__->load_own_components(qw/CDBICompat/);
62
63 this will automatically load the features included in My::DB::CDBICompat,
64 provided it looks something like this:
65
66   package My::DB::CDBICompat;
67   __PACKAGE__->load_components(qw/
68     CDBICompat::ColumnGroups
69     CDBICompat::Retrieve
70     CDBICompat::HasA
71     CDBICompat::HasMany
72     CDBICompat::MightHave
73   /);
74
75 =back
76
77 =head1 LIMITATIONS
78
79 =head2 Unimplemented
80
81 The following methods and classes are not emulated, maybe in the future.
82
83 =over 4
84
85 =item Class::DBI::Query
86
87 Deprecated in Class::DBI.
88
89 =item Class::DBI::Column
90
91 Not documented in Class::DBI.  CDBICompat's columns() returns a plain string, not an object.
92
93 =item data_type()
94
95 Undocumented CDBI method.
96
97 =back
98
99 =head2 Limited Support
100
101 The following elements of Class::DBI have limited support.
102
103 =over 4
104
105 =item Class::DBI::Relationship
106
107 The semi-documented Class::DBI::Relationship objects returned by C<meta_info($type, $col)> are mostly emulated except for their C<args> method.
108
109 =item Relationships
110
111 Relationships between tables (has_a, has_many...) must be delcared 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:
112
113     package Foo;
114     use base qw(Class::DBI);
115     
116     Foo->table("foo");
117     Foo->columns( All => qw(this that bar) );
118
119     package Bar;
120     use base qw(Class::DBI);
121     
122     Bar->table("bar");
123     Bar->columns( All => qw(up down) );
124
125     # Now that Foo and Bar are declared it is safe to declare a
126     # relationship between them
127     Foo->has_a( bar => "Bar" );
128
129
130 =back
131
132 =head1 AUTHORS
133
134 Matt S. Trout <mst@shadowcatsystems.co.uk>
135
136 =head1 LICENSE
137
138 You may distribute this code under the same terms as Perl itself.
139
140 =cut
141