X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FModel%2FDBIC%2FSchema.pm;h=5ee32c96e06360cb6169f06159da079e04831055;hb=cbe03ea7ec9a649973a404a41b3aa8d8f2ab4163;hp=201ac29191ac1a9400cb6670646e90fb9bd8fcf1;hpb=7b39f3f05b1cf0a70eaea7348f29a66fe62a4518;p=catagits%2FCatalyst-Model-DBIC-Schema.git diff --git a/lib/Catalyst/Model/DBIC/Schema.pm b/lib/Catalyst/Model/DBIC/Schema.pm index 201ac29..5ee32c9 100644 --- a/lib/Catalyst/Model/DBIC/Schema.pm +++ b/lib/Catalyst/Model/DBIC/Schema.pm @@ -1,16 +1,22 @@ package Catalyst::Model::DBIC::Schema; -use strict; -use base qw/Catalyst::Model Class::Accessor::Fast Class::Data::Accessor/; -use NEXT; -use UNIVERSAL::require; -use UNIVERSAL qw/ can /; -use Carp; +use Moose; +use mro 'c3'; +extends 'Catalyst::Model'; +with 'CatalystX::Component::Traits'; -our $VERSION = '0.03'; +our $VERSION = '0.32'; +$VERSION = eval $VERSION; -__PACKAGE__->mk_classaccessor('composed_schema'); -__PACKAGE__->mk_accessors('schema'); +use namespace::autoclean; +use Carp::Clan '^Catalyst::Model::DBIC::Schema'; +use Data::Dumper; +use DBIx::Class (); + +use Catalyst::Model::DBIC::Schema::Types + qw/ConnectInfo LoadedClass SchemaClass/; + +use MooseX::Types::Moose qw/ArrayRef Str ClassName Undef/; =head1 NAME @@ -18,183 +24,639 @@ 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 }, - ], - ); +First, prepare your database schema using L, see +L for how to generate a +L from your database using the Helper script, and +L. + +A typical usage of the helper script would be: + + script/myapp_create.pl model FilmDB DBIC::Schema MyApp::Schema::FilmDB \ + create=static dbi:mysql:filmdb dbusername dbpass \ + quote_char='`' name_sep='.' + +If you are unfamiliar with L, see L +first. + +These examples assume that you already have a schema called +C, which defines some Result classes for tables in +C and +C. Either created by the helper script (as +shown above) or manually. + +The helper also creates a Model in C, if you already +have a schema you can create just the Model using: + + script/myapp_create.pl model FilmDB DBIC::Schema MyApp::Schema::FilmDB + dbi:mysql:filmdb dbusername dbpass + +The connect_info is optional and will be hardcoded into the Model if provided. +It's better to configure it in your L config file, which will also +override any hardcoded config, see L for examples. + +Now you have a working Model which accesses your separate DBIC Schema. This can +be used/accessed in the normal Catalyst manner, via C<< $c->model() >>: + + my $db_model = $c->model('FilmDB'); # a Catalyst::Model + my $dbic = $c->model('FilmDB')->schema; # the actual DBIC object + +The Model proxies to the C instance so you can do: + + my $rs = $db_model->resultset('Actor'); # ... or ... + my $rs = $dbic ->resultset('Actor'); # same! + +There is also a shortcut, which returns a L directly, +instead of a L: + + my $rs = $c->model('FilmDB::Actor'); + +See L to find out more about which methods can be +called on ResultSets. + +You can also define your own ResultSet methods to encapsulate the +database/business logic of your applications. These go into, for example, +C. The class must inherit from +L and is automatically loaded. + +Then call your methods like any other L method: - 1; + $c->model('FilmDB::Actor')->SAG_members - # In controller code: +=head2 Some examples: - # ->schema To access schema methods: - $c->model('Foo')->schema->source(...); + # to access schema methods directly: + $c->model('FilmDB')->schema->source(...); - # certain ->schema methods (source, resultset, class) have shortcuts - $c->model('Foo')->source(...); - $c->model('Foo')->resultset(...); - $c->model('Foo')->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('Foo::Bar') - # is the same as $c->model('Foo')->resultset('Bar') + # 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('Foo')->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('Foo')->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('Foo')->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('Foo')->clone(); - $newconn->storage_type('::LDAP'); - $newconn->connection(...); + # and again, a convenience shortcut + my $newconn = $c->model('FilmDB')->clone(); + $newconn->storage_type('::LDAP'); + $newconn->connection(...); + +To set up authentication, see L below. =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 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 (but also proxies other methods to 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. This is just a matter of making a +C class that inherits from +L, if you are using +L, the default for helper script generated +schemas. + +See L +for information on definining your own L classes for +use with L, the old default. =head1 CONFIG PARAMETERS -=over 4 +Any options in your config not listed here are passed to your schema. -=item schema_class +=head2 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 +=head2 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 => { + dsn => 'dbi:Pg:dbname=mypgdb', + user => 'postgres', + password => '' + } + + 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 + traits Caching + + dsn dbi:Pg:dbname=mypgdb + user postgres + password "" + auto_savepoint 1 + quote_char """ + on_connect_do some SQL statement + on_connect_do another SQL statement + + user_defined_schema_accessor foo + + +or + + + schema_class MyApp::Schema::FilmDB + connect_info dbi:SQLite:dbname=foo.db + + +Or using L: + + Model::MyDB: + schema_class: MyDB + traits: Caching + connect_info: + dsn: dbi:Oracle:mydb + user: mtfnpy + password: mypass + LongReadLen: 1000000 + LongTruncOk: 1 + on_connect_call: 'datetime_setup' + quote_char: '"' + +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', + ], + } + ] + +=head2 traits + +Array of Traits to apply to the instance. Traits are Ls. + +They are relative to the C<< MyApp::TraitFor::Model::DBIC::Schema:: >>, then the C<< +Catalyst::TraitFor::Model::DBIC::Schema:: >> namespaces, unless prefixed with C<+> +in which case they are taken to be a fully qualified name. E.g.: + + traits Caching + traits +MyApp::TraitFor::Model::Foo + +A new instance is created at application time, so any consumed required +attributes, coercions and modifiers will work. + +Traits are applied at L time using +L. + +C will be an anon class if any traits are applied, C<< +$self->_original_class_name >> will be the original class. + +When writing a Trait, interesting points to modify are C, L and +L. + +Traits that come with the distribution: + +=over 4 + +=item L + +=item L + +=back -=item storage_type +=head2 storage_type Allows the use of a different C than what is set in your C (which in turn defaults to C<::DBI> if not set in current -L). Completely optional, and probably unneccesary for most -people, until other storage backends become available for L. +L). Completely optional, and probably unnecessary for most +people until other storage backends become available for L. -=back +=head1 ATTRIBUTES + +The keys you pass in the model configuration are available as attributes. + +Other attributes available: + +=head2 connect_info + +Your connect_info args normalized to hashref form (with dsn/user/password.) See +L for more info on the hashref form of +L. + +=head2 model_name + +The model name L uses to resolve this model, the part after +C<::Model::> or C<::M::> in your class name. E.g. if your class name is +C the L will be C. + +=head2 _default_cursor_class + +What to reset your L to if a custom one +doesn't work out. Defaults to L. + +=head1 ATTRIBUTES FROM L + +=head2 _original_class_name + +The class name of your model before any L are applied. E.g. +C. + +=head2 _traits + +Unresolved arrayref of traits passed in the config. + +=head2 _resolved_traits + +Traits you used resolved to full class names. =head1 METHODS -=over 4 +Methods not listed here are delegated to the connected schema used by the model +instance, so the following are equivalent: + + $c->model('DB')->schema->my_accessor('foo'); + # or + $c->model('DB')->my_accessor('foo'); + +Methods on the model take precedence over schema methods. -=item new +=head2 new Instantiates the Model based on the above-documented ->config parameters. The only required parameter is C. C is required in the case that C does not already have connection information defined for it. -=item schema +=head2 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 +=head2 composed_schema Accessor which returns the composed schema, which has no connection info, which was used in constructing the C above. Useful for creating new connections based on the same schema/model. There are direct shortcuts from the model object for composed_schema->clone and composed_schema->connect -=item clone +=head2 clone Shortcut for ->composed_schema->clone -=item connect +=head2 connect Shortcut for ->composed_schema->connect -=item source +=head2 source Shortcut for ->schema->source -=item class +=head2 class Shortcut for ->schema->class -=item resultset +=head2 resultset Shortcut for ->schema->resultset -=back - -=cut - -sub new { - my $self = shift->NEXT::new(@_); - - my $class = ref($self); - my $model_name = $class; - $model_name =~ s/^[\w:]+::(?:Model|M):://; - - croak "->config->{schema_class} must be defined for this model" - unless $self->{schema_class}; +=head2 storage - my $schema_class = $self->{schema_class}; +Provides an accessor for the connected schema's storage object. +Used often for debugging and controlling transactions. - # don't require if the class is already loaded... - if( !can($schema_class, 'source') ) { - $schema_class->require - or croak "Cannot load schema class '$schema_class': $@"; - } +=cut - if( !$self->{connect_info} ) { +has schema_class => ( + is => 'ro', + isa => SchemaClass, + coerce => 1, + required => 1 +); + +has storage_type => (is => 'rw', isa => Str); + +has connect_info => (is => 'rw', isa => ConnectInfo, coerce => 1); + +has model_name => ( + is => 'ro', + isa => Str, + required => 1, + lazy_build => 1, +); + +has _default_cursor_class => ( + is => 'ro', + isa => LoadedClass, + default => 'DBIx::Class::Storage::DBI::Cursor', + coerce => 1 +); + +sub BUILD { + my ($self, $args) = @_; + my $class = $self->_original_class_name; + 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 connection defined on it"; + die "Either ->config->{connect_info} must be defined for $class" + . " 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->setup; + $self->composed_schema($schema_class->compose_namespace($class)); + + my $was_mutable = $self->meta->is_mutable; + + $self->meta->make_mutable; + $self->meta->add_attribute('schema', + is => 'rw', + isa => 'DBIx::Class::Schema', + handles => $self->_delegates + ); + $self->meta->make_immutable unless $was_mutable; + $self->schema($self->composed_schema->clone); - $self->schema->storage_type($self->{storage_type}) if $self->{storage_type}; - $self->schema->connection(@{$self->{connect_info}}); + + $self->_pass_options_to_schema($args); + + $self->schema->storage_type($self->storage_type) + if $self->storage_type; + + $self->schema->connection($self->connect_info); + + $self->_install_rs_models; +} + +sub clone { shift->composed_schema->clone(@_); } + +sub connect { shift->composed_schema->connect(@_); } + +=head2 setup + +Called at C time before configuration, but after L is +set. To do something after configuuration use C<< after BUILD => >>. + +=cut + +sub setup { 1 } + +=head2 ACCEPT_CONTEXT + +Point of extension for doing things at C<< $c->model >> time with context, +returns the model instance, see L for +more information. + +=cut + +sub ACCEPT_CONTEXT { shift } + +sub _install_rs_models { + my $self = shift; + my $class = $self->_original_class_name; no strict 'refs'; - foreach my $moniker ($self->schema->sources) { - *{"${class}::${moniker}::ACCEPT_CONTEXT"} = sub { + + my @sources = $self->schema->sources; + + unless (@sources) { + warn <<'EOF' unless $ENV{CMDS_NO_SOURCES}; +******************************* WARNING *************************************** +* No sources found (did you forget to define your tables?) * +* * +* To turn off this warning, set the CMDS_NO_SOURCES environment variable. * +******************************************************************************* +EOF + } + + foreach my $moniker (@sources) { + my $classname = "${class}::$moniker"; + *{"${classname}::ACCEPT_CONTEXT"} = sub { shift; - shift->model($model_name)->resultset($moniker); + shift->model($self->model_name)->resultset($moniker); } } +} + +sub _reset_cursor_class { + my $self = shift; - return $self; + if ($self->storage->can('cursor_class')) { + $self->storage->cursor_class($self->_default_cursor_class) + if $self->storage->cursor_class ne $self->_default_cursor_class; + } } -sub clone { shift->composed_schema->clone(@_); } +{ + my %COMPOSED_CACHE; -sub connect { shift->composed_schema->connect(@_); } + sub composed_schema { + my $self = shift; + my $class = $self->_original_class_name; + my $store = \$COMPOSED_CACHE{$class}{$self->schema_class}; + + $$store = shift if @_; + + return $$store + } +} + +sub _build_model_name { + my $self = shift; + my $class = $self->_original_class_name; + (my $model_name = $class) =~ s/^[\w:]+::(?:Model|M):://; + + return $model_name; +} + +sub _delegates { + my $self = shift; + + my $schema_meta = Class::MOP::Class->initialize($self->schema_class); + my @schema_methods = $schema_meta->get_all_method_names; + +# combine with any already added by other schemas + my @handles = eval { + @{ $self->meta->find_attribute_by_name('schema')->handles } + }; + +# now kill the attribute, otherwise add_attribute in BUILD will not do the right +# thing (it clears the handles for some reason.) May be a Moose bug. + eval { $self->meta->remove_attribute('schema') }; + + my %schema_methods; + @schema_methods{ @schema_methods, @handles } = (); + @schema_methods = keys %schema_methods; + + my @my_methods = $self->meta->get_all_method_names; + my %my_methods; + @my_methods{@my_methods} = (); + + my @delegates; + for my $method (@schema_methods) { + push @delegates, $method unless exists $my_methods{$method}; + } + + return \@delegates; +} + +sub _pass_options_to_schema { + my ($self, $args) = @_; + + my @attributes = map { + $_->init_arg || () + } $self->meta->get_all_attributes; + + my %attributes; + @attributes{@attributes} = (); + + for my $opt (keys %$args) { + if (not exists $attributes{$opt}) { + next unless $self->schema->can($opt); + $self->schema->$opt($self->{$opt}); + } + } +} + +__PACKAGE__->meta->make_immutable; + +=head1 ENVIRONMENT + +=over 4 + +=item CMDS_NO_SOURCES + +Set this variable if you will be using schemas with no sources (Result classes) +to disable the warning. The warning is there because having no Result classes +is usually a mistake. + +=back + +=head1 Setting up DBIC authentication + +You can set this up with +L in MyApp.pm: + + package MyApp; + + use Catalyst qw/... Authentication .../; + + ... + + __PACKAGE__->config('Plugin::Authentication' => + { + default_realm => 'members', + members => { + credential => { + class => 'Password', + password_field => 'password', + password_type => 'hashed' + password_hash_type => 'SHA-256' + }, + store => { + class => 'DBIx::Class', + user_model => 'DB::User', + role_relation => 'roles', + role_field => 'rolename', + } + } + }); =head1 SEE ALSO @@ -207,17 +669,44 @@ Stuff related to DBIC and this Model style: L, L, L, L, -L +L, L + +Traits: + +L, +L, +L =head1 AUTHOR -Brandon L Black, C +Brandon L Black C + +=head1 CONTRIBUTORS + +caelum: Rafael Kitover C + +dandv: Dan Dascalescu C + +bluefeet: Aran Deltac C + +t0m: Tomas Doran C + +osfameron: C + +ozum: Ozum Eldogan C =head1 COPYRIGHT -This program is free software, you can redistribute it and/or modify it +Copyright (c) 2006 - 2009 +the Catalyst::Model::DBIC::Schema L and L +as listed above. + +=head1 LICENSE + +This program is free software. You can redistribute it and/or modify it under the same terms as Perl itself. =cut 1; +# vim:sts=4 sw=4 et: