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=0db268b0e01725ddee097ca208f187efa3879964;hp=9c5c2f52bd969c5ad43a62561b1114c2c605563a;hb=2a5644e8ea19e2db4136eaf8e458030d596071c4;hpb=a75b6e588e4dfc332d5d6b342ca6386c550b7092 diff --git a/lib/Catalyst/Model/DBIC/Schema.pm b/lib/Catalyst/Model/DBIC/Schema.pm index 9c5c2f5..0db268b 100644 --- a/lib/Catalyst/Model/DBIC/Schema.pm +++ b/lib/Catalyst/Model/DBIC/Schema.pm @@ -3,23 +3,22 @@ package Catalyst::Model::DBIC::Schema; use Moose; use mro 'c3'; extends 'Catalyst::Model'; -with 'MooseX::Object::Pluggable'; +with 'CatalystX::Component::Traits'; -our $VERSION = '0.24'; +our $VERSION = '0.65'; +$VERSION = eval $VERSION; +use namespace::autoclean; use Carp::Clan '^Catalyst::Model::DBIC::Schema'; use Data::Dumper; use DBIx::Class (); -use Scalar::Util 'reftype'; -use MooseX::ClassAttribute; -use Moose::Autobox; +use Module::Runtime qw/use_module/; use Catalyst::Model::DBIC::Schema::Types - qw/ConnectInfo SchemaClass CursorClass/; + qw/ConnectInfo SchemaClass Schema/; -use MooseX::Types::Moose qw/ArrayRef Str ClassName/; - -use namespace::clean -except => 'meta'; +use MooseX::Types::Moose qw/Str/; +use MooseX::Types::LoadableClass qw/LoadableClass/; =head1 NAME @@ -27,92 +26,60 @@ Catalyst::Model::DBIC::Schema - DBIx::Class::Schema Model Class =head1 SYNOPSIS -Manual creation of a DBIx::Class::Schema and a Catalyst::Model::DBIC::Schema: - -=over - -=item 1. - -Create the DBIx:Class schema in MyApp/Schema/FilmDB.pm: - - package MyApp::Schema::FilmDB; - use base qw/DBIx::Class::Schema/; - - __PACKAGE__->load_classes(qw/Actor Role/); - -=item 2. - -Create some classes for the tables in the database, for example an -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/FilmDB/Role.pm: - - package MyApp::Schema::FilmDB::Role; - use base qw/DBIx::Class/ - - __PACKAGE__->load_components(qw/Core/); - __PACKAGE__->table('role'); +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: -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. + script/myapp_create.pl model FilmDB DBIC::Schema MyApp::Schema::FilmDB \ + create=static dbi:mysql:filmdb dbusername dbpass \ + quote_names=1 -=item 3. +If you are unfamiliar with L, see L +first. -To expose it to Catalyst as a model, you should create a DBIC Model in -MyApp/Model/FilmDB.pm: +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 MyApp::Model::FilmDB; - use base qw/Catalyst::Model::DBIC::Schema/; +The helper also creates a Model in C, if you already +have a schema you can create just the Model using: - __PACKAGE__->config( - schema_class => 'MyApp::Schema::FilmDB', - connect_info => { - dsn => "DBI:...", - user => "username", - password => "password", - } - ); + script/myapp_create.pl model FilmDB DBIC::Schema MyApp::Schema::FilmDB + dbi:mysql:filmdb dbusername dbpass -See below for a full list of the possible config parameters. - -=back +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->model(): +be used/accessed in the normal Catalyst manner, via C<< $c->model() >>: - my $actor = $c->model('FilmDB::Actor')->find(1); + my $db_model = $c->model('FilmDB'); # a Catalyst::Model + my $dbic = $c->model('FilmDB')->schema; # the actual DBIC object -You can also use it to set up DBIC authentication with -Authentication::Store::DBIC 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::Store::DBIC/; +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}{dbic} = { - user_class => 'FilmDB::Actor', - user_field => 'name', - password_field => 'password' - } +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(...); @@ -142,17 +109,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. 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 @@ -182,8 +151,15 @@ 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 @@ -195,13 +171,12 @@ C namespace. This parameter is required. =head2 connect_info -This is an arrayref of connection parameters, which are specific to your -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 a hashref or arrayref of connection parameters, which are specific to +your 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. This is not required if C already has connection information -defined inside itself (which isn't highly recommended, but can be done) +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 @@ -240,16 +215,17 @@ Or using L: schema_class MyApp::Schema::FilmDB - roles Caching + traits Caching dsn dbi:Pg:dbname=mypgdb user postgres - password '' + password "" auto_savepoint 1 - quote_char """ + quote_names 1 on_connect_do some SQL statement on_connect_do another SQL statement + user_defined_schema_accessor foo or @@ -263,15 +239,15 @@ 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' - quote_char: '"' + on_connect_call: 'datetime_setup' + quote_names: 1 The old arrayref style with hashrefs for L then L options is also supported: @@ -292,39 +268,55 @@ supported: } ] -=head2 roles +=head2 traits -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.: +Array of Traits to apply to the instance. Traits are Ls. - roles Caching - roles +MyApp::DB::Role::Foo +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.: -This is done using L. + 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. -Roles are applied before setup, schema and connection are set. - -C will be an anon class if any roles are applied. +Traits are applied at L time using +L. -You cannot modify C or C, modify C instead. +C will be an anon class if any traits are applied, C<< +$self->_original_class_name >> will be the original class. -L and L can also be modified. +When writing a Trait, interesting points to modify are C, L and +L. -Roles that come with the distribution: +Traits that come with the distribution: =over 4 -=item L +=item L + +=item L + +=item L -=item L +=item L =back +=head2 compose_namespaces + +This model calls L by default to +install classes into the model namespaces. You can turn that off by +setting this attribute to false. Default is true. + +=head2 install_model_shortcuts + +If you don't want shortcut models so you can do e.g. C<< $c->model('DB::Book') +>> set this attribute to false, Default is true. + =head2 storage_type Allows the use of a different C than what is set in your @@ -332,6 +324,51 @@ C (which in turn defaults to C<::DBI> if not set in current L). Completely optional, and probably unnecessary for most people until other storage backends become available for L. +=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 CONFIGURING YOUR SCHEMA AND RESULTSETS + +See the documentation for +L for instructions on how +to pass config values from your L config to your +L and/or L classes. + =head1 METHODS =head2 new @@ -350,10 +387,13 @@ schema->resultset, schema->source, and schema->class. =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 +which was used in constructing the L. 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 +If L is not true, L is equivalent to +C<< $model->schema_class->clone >>. + =head2 clone Shortcut for ->composed_schema->clone @@ -374,55 +414,62 @@ Shortcut for ->schema->class Shortcut for ->schema->resultset +=head2 txn_do + +Shortcut for ->schema->txn_do + +=head2 txn_scope_guard + +Shortcut for ->schema->txn_scope_guard + =head2 storage Provides an accessor for the connected schema's storage object. -Used often for debugging and controlling transactions. -=cut +See L and L. -class_has 'composed_schema' => (is => 'rw', isa => 'DBIx::Class::Schema'); - -has 'schema' => (is => 'rw', isa => 'DBIx::Class::Schema'); +=cut -has 'schema_class' => ( +has schema_class => ( is => 'ro', isa => SchemaClass, - coerce => 1, required => 1 ); -has 'storage_type' => (is => 'rw', isa => Str); - -has 'connect_info' => (is => 'ro', isa => ConnectInfo, coerce => 1); +has compose_namespaces => (is => 'ro', default => sub { 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 install_model_shortcuts => (is => 'ro', default => sub { 1 }); -has 'model_name' => (is => 'ro', isa => Str, default => sub { - my $self = shift; - - my $class = ref $self; - (my $model_name = $class) =~ s/^[\w:]+::(?:Model|M):://; +has storage_type => (is => 'rw', isa => Str); - $model_name -}); +has connect_info => (is => 'rw', isa => ConnectInfo, coerce => 1); -has 'roles' => (is => 'ro', isa => ArrayRef|Str); +has model_name => ( + is => 'ro', + isa => Str, + required => 1, + lazy_build => 1, +); -has '_default_cursor_class' => ( +has _default_cursor_class => ( is => 'ro', - isa => CursorClass, + isa => LoadableClass, default => 'DBIx::Class::Storage::DBI::Cursor', - coerce => 1 ); +has schema => (is => 'rw', isa => Schema); + +my $app_class; + +before COMPONENT => sub { + $app_class = ref $_[1] || $_[1]; +}; + +sub app_class { $app_class } + 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 ) { @@ -433,62 +480,71 @@ sub BUILD { 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); + . Dumper($args); } } if (exists $self->connect_info->{cursor_class}) { - eval { Class::MOP::load_class($self->connect_info->{cursor_class}) } + eval { use_module($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->setup($args); - $self->load_plugins($self->roles->flatten) if $self->roles; + my $is_installed = defined $self->composed_schema; - $self->setup; - - $self->composed_schema($schema_class->compose_namespace($class)); + if (not $is_installed) { + $self->composed_schema($self->compose_namespaces ? + $schema_class->compose_namespace($class) + : + $schema_class->clone + ); + } - $self->schema($self->composed_schema->clone); + $self->schema($self->composed_schema->clone) + unless $self->schema; $self->schema->storage_type($self->storage_type) if $self->storage_type; $self->schema->connection($self->connect_info); - $self->_install_rs_models; - - $self->finalize; + if ((not $is_installed) && $self->install_model_shortcuts) { + $self->_install_rs_models; + } } sub clone { shift->composed_schema->clone(@_); } sub connect { shift->composed_schema->connect(@_); } -sub storage { shift->schema->storage(@_); } +# some proxy methods, see also SchemaProxy -=head2 setup +sub resultset { shift->schema->resultset(@_); } -Called at C<> time before configuration. +sub txn_do { shift->schema->txn_do(@_); } -=cut +sub txn_scope_guard { shift->schema->txn_scope_guard(@_); } -sub setup { 1 } +sub storage { shift->schema->storage(@_); } -=head2 finalize +=head2 setup + +Called at C time before configuration, but after L is +set. To do something after configuuration use C<< after BUILD => >>. -Called at the end of C after everything has been configured. +Receives a hashref of args passed to C. =cut -sub finalize { 1 } +sub setup { 1 } =head2 ACCEPT_CONTEXT -Point of extension for doing things at C<<$c->model>> time, returns the model -instance, see L for more information. +Point of extension for doing things at C<< $c->model >> time with context, +returns the model instance, see L for +more information. =cut @@ -496,14 +552,21 @@ sub ACCEPT_CONTEXT { shift } sub _install_rs_models { my $self = shift; - my $class = $self->_class_name; + my $class = $self->_original_class_name; no strict 'refs'; 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"; @@ -523,8 +586,80 @@ sub _reset_cursor_class { } } +{ + my %COMPOSED_CACHE; + + 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; +} + __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 METHOD PROXYING + +The automatic proxying to the underlying L has been +removed as of version C<0.34>, to enable this feature add C to +L. + +See L. + =head1 SEE ALSO General Catalyst Stuff: @@ -536,26 +671,50 @@ Stuff related to DBIC and this Model style: L, L, L, L, -L +L, L -Roles: +Traits: -L, -L +L, +L, +L, +L, +L =head1 AUTHOR -Brandon L Black, C +Brandon L Black C + +=head1 CONTRIBUTORS + +caelum: Rafael Kitover C -Contributors: +dandv: Dan Dascalescu C -Rafael Kitover, C<> +bluefeet: Aran Deltac C + +t0m: Tomas Doran C + +osfameron: C + +ozum: Ozum Eldogan C + +Pavel I. Shaydo C + +SineSwiper: Brendan Byrd =head1 COPYRIGHT -This program is free software, you can redistribute it and/or modify it +Copyright (c) 2006 - 2010 +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 tw=80: