X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FModel%2FDBIC%2FSchema.pm;h=d1cdc0ab5fd951690a7a439aee0f67cbff6c83cb;hb=2ff00e2b7f50d7a5a8403051dfbbad12d92398e9;hp=eebe0c0c7567f14fb85ee3e1a9eb49ce22e68fd2;hpb=150c864cf7ee1de4240e690d87edfe34a3757e2a;p=catagits%2FCatalyst-Model-DBIC-Schema.git diff --git a/lib/Catalyst/Model/DBIC/Schema.pm b/lib/Catalyst/Model/DBIC/Schema.pm index eebe0c0..d1cdc0a 100644 --- a/lib/Catalyst/Model/DBIC/Schema.pm +++ b/lib/Catalyst/Model/DBIC/Schema.pm @@ -1,16 +1,24 @@ package Catalyst::Model::DBIC::Schema; -use strict; -use base qw/Catalyst::Model Class::Accessor::Fast Class::Data::Accessor/; -use NEXT; -use UNIVERSAL::require; -use Carp; -require DBIx::Class; +use Moose; +no warnings 'uninitialized'; -our $VERSION = '0.12'; +our $VERSION = '0.24'; -__PACKAGE__->mk_classaccessor('composed_schema'); -__PACKAGE__->mk_accessors('schema'); +use mro 'c3'; +extends 'Catalyst::Model'; +with 'MooseX::Object::Pluggable'; + +use Carp::Clan '^Catalyst::Model::DBIC::Schema'; +use Data::Dumper; +use DBIx::Class (); +use Scalar::Util 'reftype'; +use MooseX::ClassAttribute; +use Moose::Autobox; + +use Catalyst::Model::DBIC::Schema::Types qw/ConnectInfo SchemaClass/; + +use namespace::clean -except => 'meta'; =head1 NAME @@ -38,20 +46,20 @@ Actor in MyApp/Schema/FilmDB/Actor.pm: package MyApp::Schema::FilmDB::Actor; use base qw/DBIx::Class/ - + __PACKAGE__->load_components(qw/Core/); __PACKAGE__->table('actor'); - + ... -and a Role in MyApp/Schema/Role.pm: +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('actor'); - + __PACKAGE__->table('role'); + ... Notice that the schema is in MyApp::Schema, not in MyApp::Model. This way it's @@ -64,22 +72,21 @@ 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} - ] + connect_info => { + dsn => "DBI:...", + user => "username", + password => "password", + } ); 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 +Now you have a working Model which accesses your separate DBIC Schema. This can be used/accessed in the normal Catalyst manner, via $c->model(): my $actor = $c->model('FilmDB::Actor')->find(1); @@ -88,60 +95,94 @@ 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/; - + ... - + __PACKAGE__->config->{authentication}{dbic} = { user_class => 'FilmDB::Actor', user_field => 'name', password_field => 'password' } -C<< $c->model() >> 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. +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 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(...); + # 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') + # 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(...); + # 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 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(...); + # 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(...); + # 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'); + +In order to add methods to a DBIC resultset, you cannot simply add them to +the source (row, table) definition class; you must define a separate custom +resultset class. See L +for more info. =head1 CONFIG PARAMETERS @@ -156,47 +197,128 @@ C namespace. This parameter is required. =item connect_info This is an arrayref of connection parameters, which are specific to your -C (see your storage type documentation for more details). +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. -If you need to specify the L specific parameter -C, or the related C options C, -C, or C, you can place these options into a hashref -as the final element of the C arrayref. If in doubt, don't -specify these options. You would know it if you needed them. +See L for a detailed explanation +of the arguments supported. Examples: - connect_info => [ 'dbi:Pg:dbname=mypgdb', 'postgres', '' ], + connect_info => { + dsn => 'dbi:Pg:dbname=mypgdb', + user => 'postgres', + password => '' + } - 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', - ], - } - ], + connect_info => { + dsn => 'dbi:SQLite:dbname=foo.db', + on_connect_do => [ + 'PRAGMA synchronous = OFF', + ] + } + + connect_info => { + dsn => 'dbi:Pg:dbname=mypgdb', + user => 'postgres', + password => '', + pg_enable_utf8 => 1, + on_connect_do => [ + 'some SQL statement', + 'another SQL statement', + ], + } + +Or using L: + + + schema_class MyApp::Schema::FilmDB + + dsn dbi:Pg:dbname=mypgdb + user postgres + password '' + auto_savepoint 1 + 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 + + +Or using L: + + Model::MyDB: + schema_class: MyDB + connect_info: + dsn: dbi:Oracle:mydb + user: mtfnpy + password: mypass + LongReadLen: 1000000 + LongTruncOk: 1 + on_connect_do: [ "alter session set nls_date_format = 'YYYY-MM-DD HH24:MI:SS'" ] + cursor_class: 'DBIx::Class::Cursor::Cached' + +The old arrayref style with hashrefs for L then L options is also +supported: + + connect_info => [ + 'dbi:Pg:dbname=mypgdb', + 'postgres', + '', + { + pg_enable_utf8 => 1, + }, + { + auto_savepoint => 1, + on_connect_do => [ + 'some SQL statement', + 'another SQL statement', + ], + } + ] + +=item roles + +Array of Roles to apply at BUILD time. Roles are relative to the +C< then C<> +namespaces, unless prefixed with C<+> in which case they are taken to be a +fully qualified name. E.g.: + + roles Caching + roles +MyApp::DB::Role::Foo + +This is done using L. + +A new instance is created at application time, so any consumed required +attributes, coercions and modifiers will work. + +Roles are applied before setup, schema and connection are set, and have a chance +to modify C. + +C will not be what you expect. + +WARNING: you cannot modify C, modify C instead. + +Roles that come with the distribution: + +=over 4 + +=item L + +=back =item storage_type @@ -256,98 +378,121 @@ Shortcut for ->schema->resultset Provides an accessor for the connected schema's storage object. Used often for debugging and controlling transactions. -=back - =cut -sub new { - my $self = shift->NEXT::new(@_); - - my $class = ref($self); - my $model_name = $class; - $model_name =~ s/^[\w:]+::(?:Model|M):://; +class_has 'composed_schema' => (is => 'rw', isa => 'DBIx::Class::Schema'); - croak "->config->{schema_class} must be defined for this model" - unless $self->{schema_class}; +has 'schema' => (is => 'rw', isa => 'DBIx::Class::Schema'); - my $schema_class = $self->{schema_class}; +has 'schema_class' => ( + is => 'ro', + isa => SchemaClass, + coerce => 1, + required => 1 +); - $schema_class->require - or croak "Cannot load schema class '$schema_class': $@"; +has 'storage_type' => (is => 'ro', isa => 'Str'); - if( !$self->{connect_info} ) { +has 'connect_info' => (is => 'ro', isa => ConnectInfo, coerce => 1); + +# ref $self changes to anon after roles are applied, and _original_class_name is +# broken in MX::O::P 0.0009 +has '_class_name' => (is => 'ro', isa => 'ClassName', default => sub { + ref shift +}); + +has 'model_name' => (is => 'ro', isa => 'Str', default => sub { + my $self = shift; + + my $class = ref $self; + (my $model_name = $class) =~ s/^[\w:]+::(?:Model|M):://; + + $model_name +}); + +has 'roles' => (is => 'ro', isa => 'ArrayRef|Str'); + +sub BUILD { + my $self = shift; + my $class = ref $self; + my $schema_class = $self->schema_class; + + if( !$self->connect_info ) { if($schema_class->storage && $schema_class->storage->connect_info) { - $self->{connect_info} = $schema_class->storage->connect_info; + $self->connect_info($schema_class->storage->connect_info); } 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); } } + if (exists $self->connect_info->{cursor_class}) { + eval { Class::MOP::load_class($self->connect_info->{cursor_class}) } + or croak "invalid connect_info: Cannot load your cursor_class" + . " ".$self->connect_info->{cursor_class}.": $@"; + } + + $self->_plugin_ns('Role'); + + $self->load_plugins($self->roles->flatten) if $self->roles; + + $self->setup; + $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}; - - # XXX This is temporary, until DBIx::Class::Storage::DBI supports the - # same syntax and we switch our requisite to that version somewhere - # down the line. This syntax is already committed into DBIx::Class - # dev branch post-0.06. - # At that time, this whole block can revert back to just being: - # $self->schema->connection(@{$self->{connect_info}}); - - my $connect_info = [ @{$self->{connect_info}} ]; - my ($on_connect_do, %sql_maker_opts); - if($DBIx::Class::VERSION < 0.069) { - my $used; - my $last_info = $self->{connect_info}->[-1]; - if(ref $last_info eq 'HASH') { - if($on_connect_do = $last_info->{on_connect_do}) { - $used = 1; - } - for my $sql_maker_opt (qw/limit_dialect quote_char name_sep/) { - if(my $opt_val = $last_info->{$sql_maker_opt}) { - $used = 1; - $sql_maker_opts{$sql_maker_opt} = $opt_val; - } - } - pop(@$connect_info) if $used; - } - } + $self->schema->storage_type($self->storage_type) + if $self->storage_type; - $self->schema->connection(@$connect_info); + $self->schema->connection($self->connect_info); - if($DBIx::Class::VERSION < 0.069) { - $self->schema->storage->on_connect_do($on_connect_do) - if $on_connect_do; - foreach my $sql_maker_opt (keys %sql_maker_opts) { - $self->schema->storage->sql_maker->$sql_maker_opt( - $sql_maker_opts{$sql_maker_opt} - ); - } - } + $self->_install_rs_models; +} + +sub clone { shift->composed_schema->clone(@_); } + +sub connect { shift->composed_schema->connect(@_); } + +sub storage { shift->schema->storage(@_); } - # XXX end of compatibility block referenced above +=item setup + +Called at C<> time, for modifying in roles/subclasses. + +=cut + +sub setup { 1 } + +=item ACCEPT_CONTEXT + +Point of extension for doing things at C<<$c->model>> time, returns the model +instance, see L for more information. + +=cut + +sub ACCEPT_CONTEXT { shift } + +sub _install_rs_models { + my $self = shift; + my $class = $self->_class_name; no strict 'refs'; foreach my $moniker ($self->schema->sources) { my $classname = "${class}::$moniker"; *{"${classname}::ACCEPT_CONTEXT"} = sub { shift; - shift->model($model_name)->resultset($moniker); + shift->model($self->model_name)->resultset($moniker); } } - - return $self; } -sub clone { shift->composed_schema->clone(@_); } - -sub connect { shift->composed_schema->connect(@_); } +__PACKAGE__->meta->make_immutable; -sub storage { shift->schema->storage(@_); } +=back =head1 SEE ALSO @@ -359,13 +504,16 @@ L, L, L, Stuff related to DBIC and this Model style: L, L, -L, L, -L +L, L =head1 AUTHOR Brandon L Black, C +Contributors: + +Rafael Kitover, C<> + =head1 COPYRIGHT This program is free software, you can redistribute it and/or modify it