X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Model-DBIC-Schema.git;a=blobdiff_plain;f=lib%2FCatalyst%2FModel%2FDBIC%2FSchema.pm;h=5ee32c96e06360cb6169f06159da079e04831055;hp=7acec2c90cd7fc42799b65de0ece54ed8cae3bad;hb=cbe03ea7ec9a649973a404a41b3aa8d8f2ab4163;hpb=60e01a60bd6bde1deb3092bd146f7568ca65f5e4 diff --git a/lib/Catalyst/Model/DBIC/Schema.pm b/lib/Catalyst/Model/DBIC/Schema.pm index 7acec2c..5ee32c9 100644 --- a/lib/Catalyst/Model/DBIC/Schema.pm +++ b/lib/Catalyst/Model/DBIC/Schema.pm @@ -2,19 +2,19 @@ package Catalyst::Model::DBIC::Schema; use Moose; use mro 'c3'; -with 'MooseX::Traits'; extends 'Catalyst::Model'; +with 'CatalystX::Component::Traits'; -our $VERSION = '0.24'; +our $VERSION = '0.32'; +$VERSION = eval $VERSION; use namespace::autoclean; use Carp::Clan '^Catalyst::Model::DBIC::Schema'; use Data::Dumper; use DBIx::Class (); -use Moose::Autobox; use Catalyst::Model::DBIC::Schema::Types - qw/ConnectInfo SchemaClass CursorClass/; + qw/ConnectInfo LoadedClass SchemaClass/; use MooseX::Types::Moose qw/ArrayRef Str ClassName Undef/; @@ -24,107 +24,65 @@ Catalyst::Model::DBIC::Schema - DBIx::Class::Schema Model Class =head1 SYNOPSIS -Manual creation of a DBIx::Class::Schema and a Catalyst::Model::DBIC::Schema: +First, prepare your database schema using L, see +L for how to generate a +L from your database using the Helper script, and +L. -=over +A typical usage of the helper script would be: -=item 1. + script/myapp_create.pl model FilmDB DBIC::Schema MyApp::Schema::FilmDB \ + create=static dbi:mysql:filmdb dbusername dbpass \ + quote_char='`' name_sep='.' -Create the DBIx:Class schema in MyApp/Schema/FilmDB.pm: +If you are unfamiliar with L, see L +first. - package MyApp::Schema::FilmDB; - use base qw/DBIx::Class::Schema/; +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. - __PACKAGE__->load_classes(qw/Actor Role/); +The helper also creates a Model in C, if you already +have a schema you can create just the Model using: -=item 2. + script/myapp_create.pl model FilmDB DBIC::Schema MyApp::Schema::FilmDB + dbi:mysql:filmdb dbusername dbpass -Create some classes for the tables in the database, for example an -Actor in MyApp/Schema/FilmDB/Actor.pm: +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. - package MyApp::Schema::FilmDB::Actor; - use base qw/DBIx::Class/ - - __PACKAGE__->load_components(qw/Core/); - __PACKAGE__->table('actor'); - - ... - -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 => { - dsn => "DBI:...", - user => "username", - password => "password", - } - ); - -See below for a full list of the possible config parameters. +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() >>: -=back + my $db_model = $c->model('FilmDB'); # a Catalyst::Model + my $dbic = $c->model('FilmDB')->schema; # the actual DBIC object -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(): +The Model proxies to the C instance so you can do: - my $actor = $c->model('FilmDB::Actor')->find(1); + my $rs = $db_model->resultset('Actor'); # ... or ... + my $rs = $dbic ->resultset('Actor'); # same! -You can also use it to set up DBIC authentication with -L in MyApp.pm: +There is also a shortcut, which returns a L directly, +instead of a L: - package MyApp; + my $rs = $c->model('FilmDB::Actor'); - use Catalyst qw/... Authentication .../; +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. - __PACKAGE__->config->{authentication} = - { - default_realm => 'members', - realms => { - 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', - } - } - } - }; +Then call your methods like any other L method: -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. + $c->model('FilmDB::Actor')->SAG_members -Some examples are given below: +=head2 Some examples: # to access schema methods directly: $c->model('FilmDB')->schema->source(...); @@ -154,17 +112,19 @@ Some examples are given below: $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 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. +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 @@ -194,11 +154,20 @@ resultset object: 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. +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 +Any options in your config not listed here are passed to your schema. + =head2 schema_class This is the classname of your L Schema. It needs @@ -262,6 +231,7 @@ Or using L: on_connect_do some SQL statement on_connect_do another SQL statement + user_defined_schema_accessor foo or @@ -275,14 +245,14 @@ 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_do: [ "alter session set nls_date_format = 'YYYY-MM-DD HH24:MI:SS'" ] - cursor_class: 'DBIx::Class::Cursor::Cached' + on_connect_call: 'datetime_setup' quote_char: '"' The old arrayref style with hashrefs for L then L options is also @@ -308,17 +278,18 @@ supported: Array of Traits to apply to the instance. Traits are Ls. -They are relative to the C<< MyApp::Model::DB::Trait:: >>, then the C<< -Catalyst::Model::DBIC::Schema::Trait:: >> namespaces, unless prefixed with C<+> +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::DB::Trait::Foo + 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. +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. @@ -330,9 +301,9 @@ Traits that come with the distribution: =over 4 -=item L +=item L -=item L +=item L =back @@ -361,16 +332,18 @@ 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 _original_class_name - -The class name of your model before any L are applied. E.g. -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. @@ -381,6 +354,15 @@ Traits you used resolved to full class names. =head1 METHODS +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. + =head2 new Instantiates the Model based on the above-documented ->config parameters. @@ -428,8 +410,6 @@ Used often for debugging and controlling transactions. =cut -has schema => (is => 'rw', isa => 'DBIx::Class::Schema'); - has schema_class => ( is => 'ro', isa => SchemaClass, @@ -439,7 +419,7 @@ has schema_class => ( has storage_type => (is => 'rw', isa => Str); -has connect_info => (is => 'ro', isa => ConnectInfo, coerce => 1); +has connect_info => (is => 'rw', isa => ConnectInfo, coerce => 1); has model_name => ( is => 'ro', @@ -448,45 +428,16 @@ has model_name => ( lazy_build => 1, ); -has _traits => (is => 'ro', isa => ArrayRef); -has _resolved_traits => (is => 'ro', isa => ArrayRef); - has _default_cursor_class => ( is => 'ro', - isa => CursorClass, + isa => LoadedClass, default => 'DBIx::Class::Storage::DBI::Cursor', coerce => 1 ); -has _original_class_name => ( - is => 'ro', - required => 1, - isa => Str, - default => sub { blessed $_[0] }, -); - -sub COMPONENT { - my ($class, $app, $args) = @_; - - $args = $class->merge_config_hashes($class->config, $args); - - if (my $traits = delete $args->{traits}) { - my @traits = $class->_resolve_traits($traits->flatten); - return $class->new_with_traits( - traits => \@traits, - _original_class_name => $class, - _traits => $traits, - _resolved_traits => \@traits, - %$args - ); - } - - return $class->new($args); -} - sub BUILD { - my $self = shift; - my $class = ref $self; + my ($self, $args) = @_; + my $class = $self->_original_class_name; my $schema_class = $self->schema_class; if( !$self->connect_info ) { @@ -511,8 +462,20 @@ sub BUILD { $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->_pass_options_to_schema($args); + $self->schema->storage_type($self->storage_type) if $self->storage_type; @@ -525,13 +488,9 @@ sub clone { shift->composed_schema->clone(@_); } sub connect { shift->composed_schema->connect(@_); } -sub storage { shift->schema->storage(@_); } - -sub resultset { shift->schema->resultset(@_); } - =head2 setup -Called at C> time before configuration, but after L is +Called at C time before configuration, but after L is set. To do something after configuuration use C<< after BUILD => >>. =cut @@ -556,8 +515,15 @@ sub _install_rs_models { my @sources = $self->schema->sources; - die "No sources found (did you forget to define your tables?)" - unless @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"; @@ -591,32 +557,6 @@ sub _reset_cursor_class { } } -sub _resolve_traits { - my ($class, @names) = @_; - my $base = 'Trait'; - - my @search_ns = grep !/^(?:Moose|Class::MOP)::/, - $class->meta->class_precedence_list; - - my @traits; - - OUTER: for my $name (@names) { - if ($name =~ /^\+(.*)/) { - push @traits, $1; - next; - } - for my $ns (@search_ns) { - my $full = "${ns}::${base}::${name}"; - if (eval { Class::MOP::load_class($full) }) { - push @traits, $full; - next OUTER; - } - } - } - - return @traits; -} - sub _build_model_name { my $self = shift; my $class = $self->_original_class_name; @@ -625,8 +565,99 @@ sub _build_model_name { 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 General Catalyst Stuff: @@ -638,24 +669,41 @@ Stuff related to DBIC and this Model style: L, L, L, L, -L +L, L Traits: -L, -L +L, +L, +L =head1 AUTHOR -Brandon L Black, C +Brandon L Black C + +=head1 CONTRIBUTORS -Contributors: +caelum: Rafael Kitover C -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