lib/Catalyst/Model/DBIC/Schema.pm

   1 package Catalyst::Model::DBIC::Schema;
   2
   3 use strict;
   4 use warnings;
   5
   6 our $VERSION = '0.23';
   7
   8 use base qw/Catalyst::Model Class::Accessor::Fast Class::Data::Accessor/;
   9 use Class::C3;
  10 use MRO::Compat;
  11 use mro 'c3';
  12 use UNIVERSAL::require;
  13 use Carp;
  14 use Data::Dumper;
  15 require DBIx::Class;
  16
  17 __PACKAGE__->mk_classaccessor('composed_schema');
  18 __PACKAGE__->mk_accessors('schema');
  19
  20 =head1 NAME
  21
  22 Catalyst::Model::DBIC::Schema - DBIx::Class::Schema Model Class
  23
  24 =head1 SYNOPSIS
  25
  26 Manual creation of a DBIx::Class::Schema and a Catalyst::Model::DBIC::Schema:
  27
  28 =over
  29
  30 =item 1.
  31
  32 Create the DBIx:Class schema in MyApp/Schema/FilmDB.pm:
  33
  34   package MyApp::Schema::FilmDB;
  35   use base qw/DBIx::Class::Schema/;
  36
  37   __PACKAGE__->load_classes(qw/Actor Role/);
  38
  39 =item 2.
  40
  41 Create some classes for the tables in the database, for example an
  42 Actor in MyApp/Schema/FilmDB/Actor.pm:
  43
  44   package MyApp::Schema::FilmDB::Actor;
  45   use base qw/DBIx::Class/
  46
  47   __PACKAGE__->load_components(qw/Core/);
  48   __PACKAGE__->table('actor');
  49
  50   ...
  51
  52 and a Role in MyApp/Schema/FilmDB/Role.pm:
  53
  54   package MyApp::Schema::FilmDB::Role;
  55   use base qw/DBIx::Class/
  56
  57   __PACKAGE__->load_components(qw/Core/);
  58   __PACKAGE__->table('role');
  59
  60   ...
  61
  62 Notice that the schema is in MyApp::Schema, not in MyApp::Model. This way it's
  63 usable as a standalone module and you can test/run it without Catalyst.
  64
  65 =item 3.
  66
  67 To expose it to Catalyst as a model, you should create a DBIC Model in
  68 MyApp/Model/FilmDB.pm:
  69
  70   package MyApp::Model::FilmDB;
  71   use base qw/Catalyst::Model::DBIC::Schema/;
  72
  73   __PACKAGE__->config(
  74       schema_class => 'MyApp::Schema::FilmDB',
  75       connect_info => [
  76                         "DBI:...",
  77                         "username",
  78                         "password",
  79                         {AutoCommit => 1}
  80                       ]
  81   );
  82
  83 See below for a full list of the possible config parameters.
  84
  85 =back
  86
  87 Now you have a working Model which accesses your separate DBIC Schema. This can
  88 be used/accessed in the normal Catalyst manner, via $c->model():
  89
  90   my $actor = $c->model('FilmDB::Actor')->find(1);
  91
  92 You can also use it to set up DBIC authentication with
  93 Authentication::Store::DBIC in MyApp.pm:
  94
  95   package MyApp;
  96
  97   use Catalyst qw/... Authentication::Store::DBIC/;
  98
  99   ...
 100
 101   __PACKAGE__->config->{authentication}{dbic} = {
 102       user_class      => 'FilmDB::Actor',
 103       user_field      => 'name',
 104       password_field  => 'password'
 105   }
 106
 107 C<< $c->model('Schema::Source') >> returns a L<DBIx::Class::ResultSet> for
 108 the source name parameter passed. To find out more about which methods can
 109 be called on a ResultSet, or how to add your own methods to it, please see
 110 the ResultSet documentation in the L<DBIx::Class> distribution.
 111
 112 Some examples are given below:
 113
 114   # to access schema methods directly:
 115   $c->model('FilmDB')->schema->source(...);
 116
 117   # to access the source object, resultset, and class:
 118   $c->model('FilmDB')->source(...);
 119   $c->model('FilmDB')->resultset(...);
 120   $c->model('FilmDB')->class(...);
 121
 122   # For resultsets, there's an even quicker shortcut:
 123   $c->model('FilmDB::Actor')
 124   # is the same as $c->model('FilmDB')->resultset('Actor')
 125
 126   # To get the composed schema for making new connections:
 127   my $newconn = $c->model('FilmDB')->composed_schema->connect(...);
 128
 129   # Or the same thing via a convenience shortcut:
 130   my $newconn = $c->model('FilmDB')->connect(...);
 131
 132   # or, if your schema works on different storage drivers:
 133   my $newconn = $c->model('FilmDB')->composed_schema->clone();
 134   $newconn->storage_type('::LDAP');
 135   $newconn->connection(...);
 136
 137   # and again, a convenience shortcut
 138   my $newconn = $c->model('FilmDB')->clone();
 139   $newconn->storage_type('::LDAP');
 140   $newconn->connection(...);
 141
 142 =head1 DESCRIPTION
 143
 144 This is a Catalyst Model for L<DBIx::Class::Schema>-based Models.  See
 145 the documentation for L<Catalyst::Helper::Model::DBIC::Schema> for
 146 information on generating these Models via Helper scripts.
 147
 148 When your Catalyst app starts up, a thin Model layer is created as an
 149 interface to your DBIC Schema. It should be clearly noted that the model
 150 object returned by C<< $c->model('FilmDB') >> is NOT itself a DBIC schema or
 151 resultset object, but merely a wrapper proving L<methods|/METHODS> to access
 152 the underlying schema.
 153
 154 In addition to this model class, a shortcut class is generated for each
 155 source in the schema, allowing easy and direct access to a resultset of the
 156 corresponding type. These generated classes are even thinner than the model
 157 class, providing no public methods but simply hooking into Catalyst's
 158 model() accessor via the
 159 L<ACCEPT_CONTEXT|Catalyst::Component/ACCEPT_CONTEXT> mechanism. The complete
 160 contents of each generated class is roughly equivalent to the following:
 161
 162   package MyApp::Model::FilmDB::Actor
 163   sub ACCEPT_CONTEXT {
 164       my ($self, $c) = @_;
 165       $c->model('FilmDB')->resultset('Actor');
 166   }
 167
 168 In short, there are three techniques available for obtaining a DBIC
 169 resultset object:
 170
 171   # the long way
 172   my $rs = $c->model('FilmDB')->schema->resultset('Actor');
 173
 174   # using the shortcut method on the model object
 175   my $rs = $c->model('FilmDB')->resultset('Actor');
 176
 177   # using the generated class directly
 178   my $rs = $c->model('FilmDB::Actor');
 179
 180 In order to add methods to a DBIC resultset, you cannot simply add them to
 181 the source (row, table) definition class; you must define a separate custom
 182 resultset class. See L<DBIx::Class::Manual::Cookbook/"Predefined searches">
 183 for more info.
 184
 185 =head1 CONFIG PARAMETERS
 186
 187 =over 4
 188
 189 =item schema_class
 190
 191 This is the classname of your L<DBIx::Class::Schema> Schema.  It needs
 192 to be findable in C<@INC>, but it does not need to be inside the
 193 C<Catalyst::Model::> namespace.  This parameter is required.
 194
 195 =item connect_info
 196
 197 This is an arrayref of connection parameters, which are specific to your
 198 C<storage_type> (see your storage type documentation for more details).
 199 If you only need one parameter (e.g. the DSN), you can just pass a string
 200 instead of an arrayref.
 201
 202 This is not required if C<schema_class> already has connection information
 203 defined inside itself (which isn't highly recommended, but can be done)
 204
 205 For L<DBIx::Class::Storage::DBI>, which is the only supported
 206 C<storage_type> in L<DBIx::Class> at the time of this writing, the
 207 parameters are your dsn, username, password, and connect options hashref.
 208
 209 See L<DBIx::Class::Storage::DBI/connect_info> for a detailed explanation
 210 of the arguments supported.
 211
 212 Examples:
 213
 214   connect_info => [ 'dbi:Pg:dbname=mypgdb', 'postgres', '' ],
 215
 216   connect_info => [
 217                     'dbi:SQLite:dbname=foo.db',
 218                     {
 219                       on_connect_do => [
 220                         'PRAGMA synchronous = OFF',
 221                       ],
 222                     }
 223                   ],
 224
 225   connect_info => [
 226                     'dbi:Pg:dbname=mypgdb',
 227                     'postgres',
 228                     '',
 229                     { AutoCommit => 0 },
 230                     {
 231                       on_connect_do => [
 232                         'some SQL statement',
 233                         'another SQL statement',
 234                       ],
 235                     }
 236                   ],
 237
 238 Or using L<Config::General>:
 239
 240     <Model::FilmDB>
 241         schema_class   MyApp::Schema::FilmDB
 242         connect_info   dbi:Pg:dbname=mypgdb
 243         connect_info   postgres
 244         connect_info
 245         <connect_info>
 246             AutoCommit   0
 247             on_connect_do   some SQL statement
 248             on_connect_do   another SQL statement
 249         </connect_info>
 250     </Model::FilmDB>
 251
 252 or
 253
 254     <Model::FilmDB>
 255         schema_class   MyApp::Schema::FilmDB
 256         connect_info   dbi:SQLite:dbname=foo.db
 257     </Model::FilmDB>
 258
 259
 260 =item storage_type
 261
 262 Allows the use of a different C<storage_type> than what is set in your
 263 C<schema_class> (which in turn defaults to C<::DBI> if not set in current
 264 L<DBIx::Class>).  Completely optional, and probably unnecessary for most
 265 people until other storage backends become available for L<DBIx::Class>.
 266
 267 =back
 268
 269 =head1 METHODS
 270
 271 =over 4
 272
 273 =item new
 274
 275 Instantiates the Model based on the above-documented ->config parameters.
 276 The only required parameter is C<schema_class>.  C<connect_info> is
 277 required in the case that C<schema_class> does not already have connection
 278 information defined for it.
 279
 280 =item schema
 281
 282 Accessor which returns the connected schema being used by the this model.
 283 There are direct shortcuts on the model class itself for
 284 schema->resultset, schema->source, and schema->class.
 285
 286 =item composed_schema
 287
 288 Accessor which returns the composed schema, which has no connection info,
 289 which was used in constructing the C<schema> above.  Useful for creating
 290 new connections based on the same schema/model.  There are direct shortcuts
 291 from the model object for composed_schema->clone and composed_schema->connect
 292
 293 =item clone
 294
 295 Shortcut for ->composed_schema->clone
 296
 297 =item connect
 298
 299 Shortcut for ->composed_schema->connect
 300
 301 =item source
 302
 303 Shortcut for ->schema->source
 304
 305 =item class
 306
 307 Shortcut for ->schema->class
 308
 309 =item resultset
 310
 311 Shortcut for ->schema->resultset
 312
 313 =item storage
 314
 315 Provides an accessor for the connected schema's storage object.
 316 Used often for debugging and controlling transactions.
 317
 318 =back
 319
 320 =cut
 321
 322 sub new {
 323     my $self = shift->next::method(@_);
 324
 325     my $class = ref($self);
 326     my $model_name = $class;
 327     $model_name =~ s/^[\w:]+::(?:Model|M):://;
 328
 329     croak "->config->{schema_class} must be defined for this model"
 330         unless $self->{schema_class};
 331
 332     my $schema_class = $self->{schema_class};
 333
 334     $schema_class->require
 335         or croak "Cannot load schema class '$schema_class': $@";
 336
 337     if( !$self->{connect_info} ) {
 338         if($schema_class->storage && $schema_class->storage->connect_info) {
 339             $self->{connect_info} = $schema_class->storage->connect_info;
 340         }
 341         else {
 342             croak "Either ->config->{connect_info} must be defined for $class"
 343                   . " or $schema_class must have connect info defined on it."
 344                   . " Here's what we got:\n"
 345                   . Dumper($self);
 346         }
 347     }
 348
 349     $self->composed_schema($schema_class->compose_namespace($class));
 350     $self->schema($self->composed_schema->clone);
 351
 352     $self->schema->storage_type($self->{storage_type})
 353         if $self->{storage_type};
 354
 355     $self->schema->connection(
 356         ref $self->{connect_info} eq 'ARRAY' ?
 357         @{$self->{connect_info}} :
 358         $self->{connect_info}
 359     );
 360
 361     no strict 'refs';
 362     foreach my $moniker ($self->schema->sources) {
 363         my $classname = "${class}::$moniker";
 364         *{"${classname}::ACCEPT_CONTEXT"} = sub {
 365             shift;
 366             shift->model($model_name)->resultset($moniker);
 367         }
 368     }
 369
 370     return $self;
 371 }
 372
 373 sub clone { shift->composed_schema->clone(@_); }
 374
 375 sub connect { shift->composed_schema->connect(@_); }
 376
 377 sub storage { shift->schema->storage(@_); }
 378
 379 =head1 SEE ALSO
 380
 381 General Catalyst Stuff:
 382
 383 L<Catalyst::Manual>, L<Catalyst::Test>, L<Catalyst::Request>,
 384 L<Catalyst::Response>, L<Catalyst::Helper>, L<Catalyst>,
 385
 386 Stuff related to DBIC and this Model style:
 387
 388 L<DBIx::Class>, L<DBIx::Class::Schema>,
 389 L<DBIx::Class::Schema::Loader>, L<Catalyst::Helper::Model::DBIC::Schema>
 390
 391 =head1 AUTHOR
 392
 393 Brandon L Black, C<blblack@gmail.com>
 394
 395 =head1 COPYRIGHT
 396
 397 This program is free software, you can redistribute it and/or modify it
 398 under the same terms as Perl itself.
 399
 400 =cut
 401
 402 1;