lib/Catalyst/Model/DBIC/Schema.pm

   1 package Catalyst::Model::DBIC::Schema;
   2
   3 use strict;
   4 use base qw/Catalyst::Model Class::Accessor::Fast Class::Data::Accessor/;
   5 use NEXT;
   6 use UNIVERSAL::require;
   7 use Carp;
   8
   9 our $VERSION = '0.11';
  10
  11 __PACKAGE__->mk_classaccessor('composed_schema');
  12 __PACKAGE__->mk_accessors('schema');
  13
  14 =head1 NAME
  15
  16 Catalyst::Model::DBIC::Schema - DBIx::Class::Schema Model Class
  17
  18 =head1 SYNOPSIS
  19
  20     package MyApp::Model::Foo;
  21     use strict;
  22     use base 'Catalyst::Model::DBIC::Schema';
  23
  24     __PACKAGE__->config(
  25         schema_class    => 'Foo::SchemaClass',
  26         connect_info    => [ 'dbi:Pg:dbname=foodb',
  27                              'postgres',
  28                              '',
  29                              { AutoCommit => 1 },
  30                              { limit_dialect => 'xxx',
  31                                quote_char => q{`},
  32                                name_sep => q{@},
  33                                on_connect_do => [
  34                                    'sql statement 1',
  35                                    'sql statement 2',
  36                                ]
  37                              }
  38                            ],
  39     );
  40
  41     1;
  42
  43     # In controller code:
  44
  45     # ->schema To access schema methods:
  46     $c->model('Foo')->schema->source(...);
  47
  48     # certain ->schema methods (source, resultset, class) have shortcuts
  49     $c->model('Foo')->source(...);
  50     $c->model('Foo')->resultset(...);
  51     $c->model('Foo')->class(...);
  52
  53     # For resultsets, there's an even quicker shortcut:
  54     $c->model('Foo::Bar')
  55     # is the same as $c->model('Foo')->resultset('Bar')
  56
  57     # To get the composed schema for making new connections:
  58     my $newconn = $c->model('Foo')->composed_schema->connect(...);
  59
  60     # Or the same thing via a convenience shortcut:
  61     my $newconn = $c->model('Foo')->connect(...);
  62
  63     # or, if your schema works on different storage drivers:
  64     my $newconn = $c->model('Foo')->composed_schema->clone();
  65     $newconn->storage_type('::LDAP');
  66     $newconn->connection(...);
  67
  68     # and again, a convenience shortcut
  69     my $newconn = $c->model('Foo')->clone();
  70     $newconn->storage_type('::LDAP');
  71     $newconn->connection(...);
  72
  73 =head1 DESCRIPTION
  74
  75 This is a Catalyst Model for L<DBIx::Class::Schema>-based Models.  See
  76 the documentation for L<Catalyst::Helper::Model::DBIC::Schema> and
  77 L<Catalyst::Helper::Model::DBIC::SchemaLoader> for information
  78 on generating these Models via Helper scripts.  The latter of the two
  79 will also generated a L<DBIx::Class::Schema::Loader>-based Schema class
  80 for you.
  81
  82 =head1 CONFIG PARAMETERS
  83
  84 =over 4
  85
  86 =item schema_class
  87
  88 This is the classname of your L<DBIx::Class::Schema> Schema.  It needs
  89 to be findable in C<@INC>, but it does not need to be underneath
  90 C<Catalyst::Model::>.  This parameter is required.
  91
  92 =item connect_info
  93
  94 This is an arrayref of connection parameters, which are specific to your
  95 C<storage_type>.  For C<::DBI>, which is the only supported C<storage_type>
  96 in L<DBIx::Class> at the time of this writing, the 4 parameters are your
  97 dsn, username, password, and connect options hashref.
  98
  99 This is not required if C<schema_class> already has connection information
 100 defined in itself (which would be the case for a Schema defined by
 101 L<DBIx::Class::Schema::Loader>, for instance).
 102
 103 =item storage_type
 104
 105 Allows the use of a different C<storage_type> than what is set in your
 106 C<schema_class> (which in turn defaults to C<::DBI> if not set in current
 107 L<DBIx::Class>).  Completely optional, and probably unnecessary for most
 108 people until other storage backends become available for L<DBIx::Class>.
 109
 110 =back
 111
 112 =head1 METHODS
 113
 114 =over 4
 115
 116 =item new
 117
 118 Instantiates the Model based on the above-documented ->config parameters.
 119 The only required parameter is C<schema_class>.  C<connect_info> is
 120 required in the case that C<schema_class> does not already have connection
 121 information defined for it.
 122
 123 =item schema
 124
 125 Accessor which returns the connected schema being used by the this model.
 126 There are already direct shortcuts on the model class itself for
 127 schema->resultset, schema->source, and schema->class.
 128
 129 =item composed_schema
 130
 131 Accessor which returns the composed schema, which has no connection info,
 132 which was used in constructing the C<schema> above.  Useful for creating
 133 new connections based on the same schema/model.  There are direct shortcuts
 134 from the model object for composed_schema->clone and composed_schema->connect
 135
 136 =item clone
 137
 138 Shortcut for ->composed_schema->clone
 139
 140 =item connect
 141
 142 Shortcut for ->composed_schema->connect
 143
 144 =item source
 145
 146 Shortcut for ->schema->source
 147
 148 =item class
 149
 150 Shortcut for ->schema->class
 151
 152 =item resultset
 153
 154 Shortcut for ->schema->resultset
 155
 156 =item storage
 157
 158 Provides an accessor for the connected schema's storage object.
 159 Used often for debugging and controlling transactions.
 160
 161 =back
 162
 163 =cut
 164
 165 sub new {
 166     my $self = shift->NEXT::new(@_);
 167
 168     my $class = ref($self);
 169     my $model_name = $class;
 170     $model_name =~ s/^[\w:]+::(?:Model|M):://;
 171
 172     croak "->config->{schema_class} must be defined for this model"
 173         unless $self->{schema_class};
 174
 175     my $schema_class = $self->{schema_class};
 176
 177     $schema_class->require
 178         or croak "Cannot load schema class '$schema_class': $@";
 179
 180     if( !$self->{connect_info} ) {
 181         if($schema_class->storage && $schema_class->storage->connect_info) {
 182             $self->{connect_info} = $schema_class->storage->connect_info;
 183         }
 184         else {
 185             croak "Either ->config->{connect_info} must be defined for $class"
 186                   . " or $schema_class must have connect info defined on it";
 187         }
 188     }
 189
 190     $self->composed_schema($schema_class->compose_namespace($class));
 191     $self->schema($self->composed_schema->clone);
 192
 193     $self->schema->storage_type($self->{storage_type})
 194         if $self->{storage_type};
 195     $self->schema->connection(@{$self->{connect_info}});
 196
 197     # This is temporary, until DBIx::Class supports the same syntax and we
 198     #  switch our requisite to that version somewhere down the line.
 199     my $last_info = $self->{connect_info}->[-1];
 200     if(ref $last_info eq 'HASH') {
 201         if(my $on_connect_do = $last_info->{on_connect_do}) {
 202             $self->schema->storage->on_connect_do($self->{on_connect_do});
 203         }
 204         foreach my $sql_maker_opt (qw/limit_dialect quote_char name_sep/) {
 205             if(my $opt_val = $last_info->{$sql_maker_opt}) {
 206                 $self->schema->storage->sql_maker->$sql_maker_opt($opt_val);
 207             }
 208         }
 209     }
 210
 211     no strict 'refs';
 212     foreach my $moniker ($self->schema->sources) {
 213         my $classname = "${class}::$moniker";
 214         *{"${classname}::COMPONENT"} = sub {
 215             shift;
 216             shift->model($model_name)->resultset($moniker);
 217         }
 218     }
 219
 220     return $self;
 221 }
 222
 223 sub clone { shift->composed_schema->clone(@_); }
 224
 225 sub connect { shift->composed_schema->connect(@_); }
 226
 227 sub storage { shift->schema->storage(@_); }
 228
 229 =head1 SEE ALSO
 230
 231 General Catalyst Stuff:
 232
 233 L<Catalyst::Manual>, L<Catalyst::Test>, L<Catalyst::Request>,
 234 L<Catalyst::Response>, L<Catalyst::Helper>, L<Catalyst>,
 235
 236 Stuff related to DBIC and this Model style:
 237
 238 L<DBIx::Class>, L<DBIx::Class::Schema>,
 239 L<DBIx::Class::Schema::Loader>, L<Catalyst::Helper::Model::DBIC::Schema>,
 240 L<Catalyst::Helper::Model::DBIC::SchemaLoader>
 241
 242 =head1 AUTHOR
 243
 244 Brandon L Black, C<blblack@gmail.com>
 245
 246 =head1 COPYRIGHT
 247
 248 This program is free software, you can redistribute it and/or modify it
 249 under the same terms as Perl itself.
 250
 251 =cut
 252
 253 1;