[catagits/Catalyst-Model-DBIC-Schema.git] / lib / Catalyst / Model / DBIC / Schema.pm

package Catalyst::Model::DBIC::Schema;

use strict;
use base qw/Catalyst::Model Class::Accessor::Fast Class::Data::Accessor/;
use NEXT;
use UNIVERSAL::require;
use Carp;
require DBIx::Class;

our $VERSION = '0.15';

__PACKAGE__->mk_classaccessor('composed_schema');
__PACKAGE__->mk_accessors('schema');

=head1 NAME

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/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 => [
                        "DBI:...",
                        "username",
                        "password",
                        {AutoCommit => 1}
                      ]
  );

See below for a full list of the possible config parameters.

=back

Now you have a working Model, accessing your separate DBIC Schema. Which can
be used/accessed in the normal Catalyst manner, via $c->model():

  my $actor = $c->model('FilmDB::Actor')->find(1);

You can also use it to set up DBIC authentication with 
Authentication::Store::DBIC in MyApp.pm:

  package MyApp;

  use Catalyst qw/... Authentication::Store::DBIC/;

  ...

  __PACKAGE__->config->{authentication}{dbic} = {
      user_class      => 'FilmDB::Actor',
      user_field      => 'name',
      password_field  => 'password'
  }

C<< $c->model() >> returns a L<DBIx::Class::ResultSet> 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<DBIx::Class> distribution.

Some examples are given below:

  # to access schema methods directly:
  $c->model('FilmDB')->schema->source(...);

  # 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('FilmDB::Actor')
  # is the same as $c->model('FilmDB')->resultset('Actor')

  # 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('FilmDB')->connect(...);

  # 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('FilmDB')->clone();
  $newconn->storage_type('::LDAP');
  $newconn->connection(...);

=head1 DESCRIPTION

This is a Catalyst Model for L<DBIx::Class::Schema>-based Models.  See
the documentation for L<Catalyst::Helper::Model::DBIC::Schema> for
information on generating these Models via Helper scripts.

=head1 CONFIG PARAMETERS

=over 4

=item schema_class

This is the classname of your L<DBIx::Class::Schema> Schema.  It needs
to be findable in C<@INC>, but it does not need to be inside the 
C<Catalyst::Model::> namespace.  This parameter is required.

=item connect_info

This is an arrayref of connection parameters, which are specific to your
C<storage_type> (see your storage type documentation for more details).

This is not required if C<schema_class> already has connection information
defined inside itself (which isn't highly recommended, but can be done)

For L<DBIx::Class::Storage::DBI>, which is the only supported
C<storage_type> in L<DBIx::Class> at the time of this writing, the
parameters are your dsn, username, password, and connect options hashref.

If you need to specify the L<DBIx::Class::Storage::DBI> specific parameter
C<on_connect_do>, or the related C<sql_maker> options C<limit_dialect>,
C<quote_char>, or C<name_sep>, you can place these options into a hashref
as the final element of the C<connect_info> arrayref.  If in doubt, don't
specify these options.  You would know it if you needed them.

Examples:

  connect_info => [ 'dbi:Pg:dbname=mypgdb', 'postgres', '' ],

  connect_info => [
                    'dbi:SQLite:dbname=foo.db',
                    {
                      on_connect_do => [
                        'PRAGMA synchronous = OFF',
                      ],
                    }
                  ],

  connect_info => [
                    'dbi:Pg:dbname=mypgdb',
                    'postgres',
                    '',
                    { AutoCommit => 0 },
                    {
                      on_connect_do => [
                        'some SQL statement',
                        'another SQL statement',
                      ],
                    }
                  ],

=item storage_type

Allows the use of a different C<storage_type> than what is set in your
C<schema_class> (which in turn defaults to C<::DBI> if not set in current
L<DBIx::Class>).  Completely optional, and probably unnecessary for most
people until other storage backends become available for L<DBIx::Class>.

=back

=head1 METHODS

=over 4

=item new

Instantiates the Model based on the above-documented ->config parameters.
The only required parameter is C<schema_class>.  C<connect_info> is
required in the case that C<schema_class> does not already have connection
information defined for it.

=item schema

Accessor which returns the connected schema being used by the this model.
There are direct shortcuts on the model class itself for
schema->resultset, schema->source, and schema->class.

=item composed_schema

Accessor which returns the composed schema, which has no connection info,
which was used in constructing the C<schema> 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

Shortcut for ->composed_schema->clone

=item connect

Shortcut for ->composed_schema->connect

=item source

Shortcut for ->schema->source

=item class

Shortcut for ->schema->class

=item resultset

Shortcut for ->schema->resultset

=item storage

Provides an accessor for the connected schema's storage object.
Used often for debugging and controlling transactions.

=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};

    my $schema_class = $self->{schema_class};

    $schema_class->require
        or croak "Cannot load schema class '$schema_class': $@";

    if( !$self->{connect_info} ) {
        if($schema_class->storage && $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 connect info defined on it";
        }
    }

    $self->composed_schema($schema_class->compose_namespace($class));
    $self->schema($self->composed_schema->clone);

    $self->schema->storage_type($self->{storage_type})
        if $self->{storage_type};

    # XXX This is temporary, until DBIx::Class::Storage::DBI supports the
    #  same syntax and we switch our requisite to that version somewhere
    #  down the line.  This syntax is already committed into DBIx::Class
    #  -current branch post-0.06.
    # At that time, this whole block can revert back to just being:
    #  $self->schema->connection(@{$self->{connect_info}});
    
    my $connect_info = [ @{$self->{connect_info}} ];
    my ($on_connect_do, %sql_maker_opts);
    if($DBIx::Class::VERSION < 0.069) {
        my $used;
        my $last_info = $self->{connect_info}->[-1];
        if(ref $last_info eq 'HASH') {
            if($on_connect_do = $last_info->{on_connect_do}) {
              $used = 1;
            }
            for my $sql_maker_opt (qw/limit_dialect quote_char name_sep/) {
              if(my $opt_val = $last_info->{$sql_maker_opt}) {
                $used = 1;
                $sql_maker_opts{$sql_maker_opt} = $opt_val;
              }
            }
            pop(@$connect_info) if $used;
        }
    }

    $self->schema->connection(@$connect_info);

    if($DBIx::Class::VERSION < 0.069) {
        $self->schema->storage->on_connect_do($on_connect_do)
            if $on_connect_do;
        foreach my $sql_maker_opt (keys %sql_maker_opts) {
            $self->schema->storage->sql_maker->$sql_maker_opt(
                $sql_maker_opts{$sql_maker_opt}
            );
        }
    }

    # XXX end of compatibility block referenced above

    no strict 'refs';
    foreach my $moniker ($self->schema->sources) {
        my $classname = "${class}::$moniker";
        *{"${classname}::ACCEPT_CONTEXT"} = sub {
            shift;
            shift->model($model_name)->resultset($moniker);
        }
    }

    return $self;
}

sub clone { shift->composed_schema->clone(@_); }

sub connect { shift->composed_schema->connect(@_); }

sub storage { shift->schema->storage(@_); }

=head1 SEE ALSO

General Catalyst Stuff:

L<Catalyst::Manual>, L<Catalyst::Test>, L<Catalyst::Request>,
L<Catalyst::Response>, L<Catalyst::Helper>, L<Catalyst>,

Stuff related to DBIC and this Model style:

L<DBIx::Class>, L<DBIx::Class::Schema>,
L<DBIx::Class::Schema::Loader>, L<Catalyst::Helper::Model::DBIC::Schema>

=head1 AUTHOR

Brandon L Black, C<blblack@gmail.com>

=head1 COPYRIGHT

This program is free software, you can redistribute it and/or modify it
under the same terms as Perl itself.

=cut

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