Merge 'trunk' into 'DBIx-Class-C3'
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / Schema.pm
CommitLineData
a02675cd 1package DBIx::Class::Schema;
2
3use strict;
4use warnings;
63e9583a 5use DBIx::Class::DB;
a02675cd 6
41a6f8c0 7use base qw/DBIx::Class/;
a02675cd 8
42a1aaa1 9__PACKAGE__->load_components(qw/Exception/);
74b92d9a 10__PACKAGE__->mk_classdata('class_registrations' => {});
a02675cd 11
c2da098a 12=head1 NAME
13
14DBIx::Class::Schema - composable schemas
15
16=head1 SYNOPSIS
17
03312470 18in My/Schema.pm
c2da098a 19
20 package My::Schema;
21
22 use base qw/DBIx::Class::Schema/;
23
24 __PACKAGE__->load_classes(qw/Foo Bar Baz/);
25
03312470 26in My/Schema/Foo.pm
c2da098a 27
28 package My::Schema::Foo;
29
03312470 30 use base qw/DBIx::Class/;
c2da098a 31
03312470 32 __PACKAGE__->load_components(qw/Core PK::Auto::Pg/); # for example
c2da098a 33 __PACKAGE__->table('foo');
34 ...
35
03312470 36in My/DB.pm
c2da098a 37
38 use My::Schema;
39
40 My::Schema->compose_connection('My::DB', $dsn, $user, $pass, $attrs);
41
03312470 42then in app code
c2da098a 43
656796f2 44 my @obj = My::DB::Foo->search({}); # My::DB::Foo isa My::Schema::Foo My::DB
c2da098a 45
46=head1 DESCRIPTION
47
429bd4f1 48Creates database classes based on a schema. This allows you to have more than
49one concurrent connection using the same database classes, by making
50subclasses under a new namespace for each connection. If you only need one
51class, you should probably use L<DBIx::Class::DB> directly instead.
52
03312470 53NB: If you're used to L<Class::DBI> it's worth reading the L</SYNOPSIS>
54carefully as DBIx::Class does things a little differently. Note in
55particular which module inherits off which.
56
c2da098a 57=head1 METHODS
58
59=over 4
60
076652e8 61=item register_class <component> <component_class>
62
63Registers the class in the schema's class_registrations. This is a hash
429bd4f1 64containing database classes, keyed by their monikers. It's used by
076652e8 65compose_connection to create/modify all the existing database classes.
66
c2da098a 67=cut
68
a02675cd 69sub register_class {
70 my ($class, $name, $to_register) = @_;
74b92d9a 71 my %reg = %{$class->class_registrations};
a02675cd 72 $reg{$name} = $to_register;
74b92d9a 73 $class->class_registrations(\%reg);
74}
75
076652e8 76=item registered_classes
77
78Simple read-only accessor for the schema's registered classes. See
79register_class above if you want to modify it.
80
81
82=cut
83
74b92d9a 84sub registered_classes {
85 return values %{shift->class_registrations};
a02675cd 86}
87
076652e8 88=item load_classes [<classes>}
89
429bd4f1 90Uses L<Module::Find> to find all classes under the database class' namespace,
91or uses the classes you select. Then it loads the component (using L<use>),
92and registers them (using B<register_class>);
076652e8 93
94=cut
95
a02675cd 96sub load_classes {
97 my $class = shift;
98 my @comp = grep { $_ !~ /^#/ } @_;
41a6f8c0 99 unless (@comp) {
100 eval "require Module::Find;";
101 $class->throw("No arguments to load_classes and couldn't load".
102 " Module::Find ($@)") if $@;
103 @comp = map { substr $_, length "${class}::" }
104 Module::Find::findallmod($class);
105 }
a02675cd 106 foreach my $comp (@comp) {
107 my $comp_class = "${class}::${comp}";
d3dec624 108 eval "use $comp_class"; # If it fails, assume the user fixed it
a02675cd 109 $class->register_class($comp => $comp_class);
110 }
111}
112
429bd4f1 113=item compose_connection <target> <@db_info>
114
115This is the most important method in this class. it takes a target namespace,
116as well as dbh connection info, and creates a L<DBIx::Class::DB> class as
117well as subclasses for each of your database classes in this namespace, using
118this connection.
076652e8 119
8c130052 120It will also setup a ->table method on the target class, which lets you
121resolve database classes based on the schema component name, for example
122
123 MyApp::DB->table('Foo') # returns MyApp::DB::Foo,
124 # which ISA MyApp::Schema::Foo
125
126This is the recommended API for accessing Schema generated classes, and
127using it might give you instant advantages with future versions of DBIC.
128
076652e8 129=cut
130
a02675cd 131sub compose_connection {
132 my ($class, $target, @info) = @_;
11b78bd6 133 my $conn_class = "${target}::_db";
134 $class->setup_connection_class($conn_class, @info);
74b92d9a 135 my %reg = %{ $class->class_registrations };
11b78bd6 136 my %target;
137 my %map;
a02675cd 138 while (my ($comp, $comp_class) = each %reg) {
139 my $target_class = "${target}::${comp}";
63e9583a 140 $class->inject_base($target_class, $comp_class, $conn_class);
227d4dee 141 $target_class->table($comp_class->table);
11b78bd6 142 @map{$comp, $comp_class} = ($target_class, $target_class);
b7951443 143 }
11b78bd6 144 {
145 no strict 'refs';
146 *{"${target}::class"} =
147 sub {
148 my ($class, $to_map) = @_;
149 return $map{$to_map};
150 };
d3dec624 151 *{"${target}::classes"} = sub { return \%map; };
11b78bd6 152 }
aa698961 153 $conn_class->class_resolver($target);
b7951443 154}
155
076652e8 156=item setup_connection_class <$target> <@info>
157
429bd4f1 158Sets up a database connection class to inject between the schema
159and the subclasses the schema creates.
160
076652e8 161=cut
162
b7951443 163sub setup_connection_class {
164 my ($class, $target, @info) = @_;
63e9583a 165 $class->inject_base($target => 'DBIx::Class::DB');
166 #$target->load_components('DB');
b7951443 167 $target->connection(@info);
168}
169
a02675cd 1701;
c2da098a 171
172=back
173
174=head1 AUTHORS
175
daec44b8 176Matt S. Trout <mst@shadowcatsystems.co.uk>
c2da098a 177
178=head1 LICENSE
179
180You may distribute this code under the same terms as Perl itself.
181
182=cut
183