[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;
use Data::Dumper;
require DBIx::Class;

our $VERSION = '0.16';

__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"
		  . "Here's what we got:\n"
		  . Dumper($self);
        }
    }

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