X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FModel%2FDBIC%2FSchema.pm;h=e44324e875bd4cd4b7668506a2acbd557e22dafc;hb=d52bc376e64d1ef6a50d0356290a55804f766ce1;hp=cc7ed486a65cb58cca7ba9b435c1c12fe627bce9;hpb=b8427e0b4e21c06dd38f18cc529a3db35ff2dcc0;p=catagits%2FCatalyst-Model-DBIC-Schema.git diff --git a/lib/Catalyst/Model/DBIC/Schema.pm b/lib/Catalyst/Model/DBIC/Schema.pm index cc7ed48..e44324e 100644 --- a/lib/Catalyst/Model/DBIC/Schema.pm +++ b/lib/Catalyst/Model/DBIC/Schema.pm @@ -1,12 +1,16 @@ package Catalyst::Model::DBIC::Schema; use strict; +use warnings; + +our $VERSION = '0.22'; + use base qw/Catalyst::Model Class::Accessor::Fast Class::Data::Accessor/; use NEXT; use UNIVERSAL::require; use Carp; - -our $VERSION = '0.09'; +use Data::Dumper; +require DBIx::Class; __PACKAGE__->mk_classaccessor('composed_schema'); __PACKAGE__->mk_accessors('schema'); @@ -17,62 +21,159 @@ Catalyst::Model::DBIC::Schema - DBIx::Class::Schema Model Class =head1 SYNOPSIS - package MyApp::Model::Foo; - use strict; - use base 'Catalyst::Model::DBIC::Schema'; - - __PACKAGE__->config( - schema_class => 'Foo::SchemaClass', - connect_info => [ 'dbi:Pg:dbname=foodb', - 'postgres', - '', - { AutoCommit => 1 }, - ], - ); +Manual creation of a DBIx::Class::Schema and a Catalyst::Model::DBIC::Schema: - 1; +=over - # In controller code: +=item 1. - # ->schema To access schema methods: - $c->model('Foo')->schema->source(...); +Create the DBIx:Class schema in MyApp/Schema/FilmDB.pm: - # certain ->schema methods (source, resultset, class) have shortcuts - $c->model('Foo')->source(...); - $c->model('Foo')->resultset(...); - $c->model('Foo')->class(...); + package MyApp::Schema::FilmDB; + use base qw/DBIx::Class::Schema/; - # For resultsets, there's an even quicker shortcut: - $c->model('Foo::Bar') - # is the same as $c->model('Foo')->resultset('Bar') + __PACKAGE__->load_classes(qw/Actor Role/); - # To get the composed schema for making new connections: - my $newconn = $c->model('Foo')->composed_schema->connect(...); +=item 2. - # Or the same thing via a convenience shortcut: - my $newconn = $c->model('Foo')->connect(...); +Create some classes for the tables in the database, for example an +Actor in MyApp/Schema/FilmDB/Actor.pm: - # or, if your schema works on different storage drivers: - my $newconn = $c->model('Foo')->composed_schema->clone(); - $newconn->storage_type('::LDAP'); - $newconn->connection(...); + package MyApp::Schema::FilmDB::Actor; + use base qw/DBIx::Class/ - # and again, a convenience shortcut - my $newconn = $c->model('Foo')->clone(); - $newconn->storage_type('::LDAP'); - $newconn->connection(...); + __PACKAGE__->load_components(qw/Core/); + __PACKAGE__->table('actor'); -=head1 DESCRIPTION + ... + +and a Role in MyApp/Schema/FilmDB/Role.pm: + + package MyApp::Schema::FilmDB::Role; + use base qw/DBIx::Class/ + + __PACKAGE__->load_components(qw/Core/); + __PACKAGE__->table('role'); + + ... + +Notice that the schema is in MyApp::Schema, not in MyApp::Model. This way it's +usable as a standalone module and you can test/run it without Catalyst. + +=item 3. + +To expose it to Catalyst as a model, you should create a DBIC Model in +MyApp/Model/FilmDB.pm: + + package MyApp::Model::FilmDB; + use base qw/Catalyst::Model::DBIC::Schema/; + + __PACKAGE__->config( + schema_class => 'MyApp::Schema::FilmDB', + connect_info => [ + "DBI:...", + "username", + "password", + {AutoCommit => 1} + ] + ); + +See below for a full list of the possible config parameters. + +=back + +Now you have a working Model, accessing your separate DBIC Schema. Which can +be used/accessed in the normal Catalyst manner, via $c->model(): + + my $actor = $c->model('FilmDB::Actor')->find(1); + +You can also use it to set up DBIC authentication with +Authentication::Store::DBIC in MyApp.pm: + + package MyApp; + + use Catalyst qw/... Authentication::Store::DBIC/; + + ... -NOTE: This is the first public release, there's probably a higher than -average chance of random bugs and shortcomings: you've been warned. + __PACKAGE__->config->{authentication}{dbic} = { + user_class => 'FilmDB::Actor', + user_field => 'name', + password_field => 'password' + } + +C<< $c->model('Schema::Source') >> returns a L for +the source name parameter passed. To find out more about which methods can +be called on a ResultSet, or how to add your own methods to it, please see +the ResultSet documentation in the L distribution. + +Some examples are given below: + + # to access schema methods directly: + $c->model('FilmDB')->schema->source(...); + + # to access the source object, resultset, and class: + $c->model('FilmDB')->source(...); + $c->model('FilmDB')->resultset(...); + $c->model('FilmDB')->class(...); + + # For resultsets, there's an even quicker shortcut: + $c->model('FilmDB::Actor') + # is the same as $c->model('FilmDB')->resultset('Actor') + + # To get the composed schema for making new connections: + my $newconn = $c->model('FilmDB')->composed_schema->connect(...); + + # Or the same thing via a convenience shortcut: + my $newconn = $c->model('FilmDB')->connect(...); + + # or, if your schema works on different storage drivers: + my $newconn = $c->model('FilmDB')->composed_schema->clone(); + $newconn->storage_type('::LDAP'); + $newconn->connection(...); + + # and again, a convenience shortcut + my $newconn = $c->model('FilmDB')->clone(); + $newconn->storage_type('::LDAP'); + $newconn->connection(...); + +=head1 DESCRIPTION This is a Catalyst Model for L-based Models. See -the documentation for L and -L for information -on generating these Models via Helper scripts. The latter of the two -will also generated a L-based Schema class -for you. +the documentation for L for +information on generating these Models via Helper scripts. + +When your Catalyst app starts up, a thin Model layer is created as an +interface to your DBIC Schema. It should be clearly noted that the model +object returned by C<< $c->model('FilmDB') >> is NOT itself a DBIC schema or +resultset object, but merely a wrapper proving L to access +the underlying schema. + +In addition to this model class, a shortcut class is generated for each +source in the schema, allowing easy and direct access to a resultset of the +corresponding type. These generated classes are even thinner than the model +class, providing no public methods but simply hooking into Catalyst's +model() accessor via the +L mechanism. The complete +contents of each generated class is roughly equivalent to the following: + + package MyApp::Model::FilmDB::Actor + sub ACCEPT_CONTEXT { + my ($self, $c) = @_; + $c->model('FilmDB')->resultset('Actor'); + } + +In short, there are three techniques available for obtaining a DBIC +resultset object: + + # the long way + my $rs = $c->model('FilmDB')->schema->resultset('Actor'); + + # using the shortcut method on the model object + my $rs = $c->model('FilmDB')->resultset('Actor'); + + # using the generated class directly + my $rs = $c->model('FilmDB::Actor'); =head1 CONFIG PARAMETERS @@ -81,19 +182,73 @@ for you. =item schema_class This is the classname of your L Schema. It needs -to be findable in C<@INC>, but it does not need to be underneath -C. This parameter is required. +to be findable in C<@INC>, but it does not need to be inside the +C namespace. This parameter is required. =item connect_info This is an arrayref of connection parameters, which are specific to your -C. For C<::DBI>, which is the only supported C -in L at the time of this writing, the 4 parameters are your -dsn, username, password, and connect options hashref. +C (see your storage type documentation for more details). +If you only need one parameter (e.g. the DSN), you can just pass a string +instead of an arrayref. This is not required if C already has connection information -defined in itself (which would be the case for a Schema defined by -L, for instance). +defined inside itself (which isn't highly recommended, but can be done) + +For L, which is the only supported +C in L at the time of this writing, the +parameters are your dsn, username, password, and connect options hashref. + +See L for a detailed explanation +of the arguments supported. + +Examples: + + connect_info => [ 'dbi:Pg:dbname=mypgdb', 'postgres', '' ], + + connect_info => [ + 'dbi:SQLite:dbname=foo.db', + { + on_connect_do => [ + 'PRAGMA synchronous = OFF', + ], + } + ], + + connect_info => [ + 'dbi:Pg:dbname=mypgdb', + 'postgres', + '', + { AutoCommit => 0 }, + { + on_connect_do => [ + 'some SQL statement', + 'another SQL statement', + ], + } + ], + +Or using L: + + + schema_class MyApp::Schema::FilmDB + connect_info dbi:Pg:dbname=mypgdb + connect_info postgres + connect_info + + AutoCommit 0 + on_connect_do some SQL statement + on_connect_do another SQL statement + + + +or + + + schema_class MyApp::Schema::FilmDB + connect_info dbi:SQLite:dbname=foo.db + + =item storage_type @@ -118,7 +273,7 @@ information defined for it. =item schema Accessor which returns the connected schema being used by the this model. -There are already direct shortcuts on the model class itself for +There are direct shortcuts on the model class itself for schema->resultset, schema->source, and schema->class. =item composed_schema @@ -178,15 +333,24 @@ sub new { } else { croak "Either ->config->{connect_info} must be defined for $class" - . " or $schema_class must have connect info defined on it"; + . " or $schema_class must have connect info defined on it." + . " Here's what we got:\n" + . Dumper($self); } } $self->composed_schema($schema_class->compose_namespace($class)); $self->schema($self->composed_schema->clone); - $self->schema->storage_type($self->{storage_type}) if $self->{storage_type}; - $self->schema->connection(@{$self->{connect_info}}); + $self->schema->storage_type($self->{storage_type}) + if $self->{storage_type}; + + $self->schema->connection( + ref $self->{connect_info} eq 'ARRAY' ? + @{$self->{connect_info}} : + $self->{connect_info} + ); + no strict 'refs'; foreach my $moniker ($self->schema->sources) { my $classname = "${class}::$moniker"; @@ -215,8 +379,7 @@ L, L, L, Stuff related to DBIC and this Model style: L, L, -L, L, -L +L, L =head1 AUTHOR