[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.11';

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

=head1 NAME

Catalyst::Model::DBIC::Schema - DBIx::Class::Schema Model Class

=head1 SYNOPSIS

    package MyApp::Model::Foo;
    use strict;
    use base 'Catalyst::Model::DBIC::Schema';

    __PACKAGE__->config(
        schema_class    => 'Foo::SchemaClass',
        connect_info    => [ 'dbi:Pg:dbname=foodb',
                             'postgres',
                             '',
                             { AutoCommit => 1 },
                             { limit_dialect => 'xxx',
                               quote_char => q{`},
                               name_sep => q{@},
                               on_connect_do => [
                                   'sql statement 1',
                                   'sql statement 2',
                               ]
                             }
                           ],
    );

    1;

    # In controller code:

    # ->schema To access schema methods:
    $c->model('Foo')->schema->source(...);

    # certain ->schema methods (source, resultset, class) have shortcuts
    $c->model('Foo')->source(...);
    $c->model('Foo')->resultset(...);
    $c->model('Foo')->class(...);

    # For resultsets, there's an even quicker shortcut:
    $c->model('Foo::Bar')
    # is the same as $c->model('Foo')->resultset('Bar')

    # To get the composed schema for making new connections:
    my $newconn = $c->model('Foo')->composed_schema->connect(...);

    # Or the same thing via a convenience shortcut:
    my $newconn = $c->model('Foo')->connect(...);

    # or, if your schema works on different storage drivers:
    my $newconn = $c->model('Foo')->composed_schema->clone();
    $newconn->storage_type('::LDAP');
    $newconn->connection(...);

    # and again, a convenience shortcut
    my $newconn = $c->model('Foo')->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> and
L<Catalyst::Helper::Model::DBIC::SchemaLoader> for information
on generating these Models via Helper scripts.  The latter of the two
will also generated a L<DBIx::Class::Schema::Loader>-based Schema class
for you.

=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 underneath
C<Catalyst::Model::>.  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 in itself (which would be the case for a Schema defined by
L<DBIx::Class::Schema::Loader>, for instance).

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 => [
                          'some SQL statement',
                          'another SQL statement',
                        ],
                      }
                    ],
    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 already 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
    #  dev 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>,
L<Catalyst::Helper::Model::DBIC::SchemaLoader>

=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
4bd6775c	10	our $VERSION = '0.11';
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
	21	package MyApp::Model::Foo;
	22	use strict;
	23	use base 'Catalyst::Model::DBIC::Schema';
	24
	25	__PACKAGE__->config(
cd7e6e4f	26	schema_class => 'Foo::SchemaClass',
	27	connect_info => [ 'dbi:Pg:dbname=foodb',
	28	'postgres',
	29	'',
	30	{ AutoCommit => 1 },
4bd6775c	31	{ limit_dialect => 'xxx',
	32	quote_char => q{`},
	33	name_sep => q{@},
	34	on_connect_do => [
	35	'sql statement 1',
	36	'sql statement 2',
	37	]
	38	}
cd7e6e4f	39	],
ad91060a	40	);
	41
	42	1;
	43
	44	# In controller code:
	45
	46	# ->schema To access schema methods:
	47	$c->model('Foo')->schema->source(...);
	48
c12b7310	49	# certain ->schema methods (source, resultset, class) have shortcuts
	50	$c->model('Foo')->source(...);
	51	$c->model('Foo')->resultset(...);
	52	$c->model('Foo')->class(...);
	53
	54	# For resultsets, there's an even quicker shortcut:
	55	$c->model('Foo::Bar')
	56	# is the same as $c->model('Foo')->resultset('Bar')
ad91060a	57
	58	# To get the composed schema for making new connections:
	59	my $newconn = $c->model('Foo')->composed_schema->connect(...);
	60
	61	# Or the same thing via a convenience shortcut:
	62	my $newconn = $c->model('Foo')->connect(...);
	63
	64	# or, if your schema works on different storage drivers:
	65	my $newconn = $c->model('Foo')->composed_schema->clone();
	66	$newconn->storage_type('::LDAP');
f7a944f8	67	$newconn->connection(...);
ad91060a	68
	69	# and again, a convenience shortcut
	70	my $newconn = $c->model('Foo')->clone();
	71	$newconn->storage_type('::LDAP');
f7a944f8	72	$newconn->connection(...);
ad91060a	73
	74	=head1 DESCRIPTION
	75
7b39f3f0	76	This is a Catalyst Model for L<DBIx::Class::Schema>-based Models. See
7b39f3f0	77	the documentation for L<Catalyst::Helper::Model::DBIC::Schema> and
1aeb6e1e	78	L<Catalyst::Helper::Model::DBIC::SchemaLoader> for information
	79	on generating these Models via Helper scripts. The latter of the two
	80	will also generated a L<DBIx::Class::Schema::Loader>-based Schema class
	81	for you.
ad91060a	82
	83	=head1 CONFIG PARAMETERS
	84
	85	=over 4
	86
	87	=item schema_class
	88
	89	This is the classname of your L<DBIx::Class::Schema> Schema. It needs
	90	to be findable in C<@INC>, but it does not need to be underneath
0f2fd2c0	91	C<Catalyst::Model::>. This parameter is required.
ad91060a	92
	93	=item connect_info
	94
	95	This is an arrayref of connection parameters, which are specific to your
7db6da78	96	C<storage_type> (see your storage type documentation for more details).
ad91060a	97
0f2fd2c0	98	This is not required if C<schema_class> already has connection information
	99	defined in itself (which would be the case for a Schema defined by
	100	L<DBIx::Class::Schema::Loader>, for instance).
	101
7db6da78	102	For L<DBIx::Class::Storage::DBI>, which is the only supported
	103	C<storage_type> in L<DBIx::Class> at the time of this writing, the
	104	parameters are your dsn, username, password, and connect options hashref.
	105
	106	If you need to specify the L<DBIx::Class::Storage::DBI> specific parameter
	107	C<on_connect_do>, or the related C<sql_maker> options C<limit_dialect>,
	108	C<quote_char>, or C<name_sep>, you can place these options into a hashref
	109	as the final element of the C<connect_info> arrayref. If in doubt, don't
	110	specify these options. You would know it if you needed them.
	111
	112	Examples:
	113
	114	connect_info => [ 'dbi:Pg:dbname=mypgdb', 'postgres', '' ],
	115	connect_info => [
	116	'dbi:SQLite:dbname=foo.db',
	117	{
	118	on_connect_do => [
	119	'some SQL statement',
	120	'another SQL statement',
	121	],
	122	}
	123	],
	124	connect_info => [
	125	'dbi:Pg:dbname=mypgdb',
	126	'postgres',
	127	'',
	128	{ AutoCommit => 0 },
	129	{
	130	on_connect_do => [
	131	'some SQL statement',
	132	'another SQL statement',
	133	],
	134	}
	135	],
	136
ad91060a	137	=item storage_type
	138
	139	Allows the use of a different C<storage_type> than what is set in your
	140	C<schema_class> (which in turn defaults to C<::DBI> if not set in current
b8427e0b	141	L<DBIx::Class>). Completely optional, and probably unnecessary for most
b8427e0b	142	people until other storage backends become available for L<DBIx::Class>.
ad91060a	143
	144	=back
	145
	146	=head1 METHODS
	147
	148	=over 4
	149
	150	=item new
	151
	152	Instantiates the Model based on the above-documented ->config parameters.
0f2fd2c0	153	The only required parameter is C<schema_class>. C<connect_info> is
	154	required in the case that C<schema_class> does not already have connection
	155	information defined for it.
ad91060a	156
	157	=item schema
	158
	159	Accessor which returns the connected schema being used by the this model.
c12b7310	160	There are already direct shortcuts on the model class itself for
c12b7310	161	schema->resultset, schema->source, and schema->class.
ad91060a	162
	163	=item composed_schema
	164
	165	Accessor which returns the composed schema, which has no connection info,
	166	which was used in constructing the C<schema> above. Useful for creating
c12b7310	167	new connections based on the same schema/model. There are direct shortcuts
c12b7310	168	from the model object for composed_schema->clone and composed_schema->connect
ad91060a	169
	170	=item clone
	171
	172	Shortcut for ->composed_schema->clone
	173
	174	=item connect
	175
	176	Shortcut for ->composed_schema->connect
	177
c12b7310	178	=item source
	179
	180	Shortcut for ->schema->source
	181
	182	=item class
	183
	184	Shortcut for ->schema->class
	185
	186	=item resultset
	187
	188	Shortcut for ->schema->resultset
	189
b8427e0b	190	=item storage
	191
	192	Provides an accessor for the connected schema's storage object.
	193	Used often for debugging and controlling transactions.
	194
ad91060a	195	=back
	196
	197	=cut
	198
	199	sub new {
46878f2e	200	my $self = shift->NEXT::new(@_);
ad91060a	201
	202	my $class = ref($self);
	203	my $model_name = $class;
	204	$model_name =~ s/^[\w:]+::(?:Model\|M):://;
	205
0f2fd2c0	206	croak "->config->{schema_class} must be defined for this model"
0f2fd2c0	207	unless $self->{schema_class};
ad91060a	208
	209	my $schema_class = $self->{schema_class};
	210
1aeb6e1e	211	$schema_class->require
1aeb6e1e	212	or croak "Cannot load schema class '$schema_class': $@";
ad91060a	213
0f2fd2c0	214	if( !$self->{connect_info} ) {
	215	if($schema_class->storage && $schema_class->storage->connect_info) {
	216	$self->{connect_info} = $schema_class->storage->connect_info;
	217	}
	218	else {
	219	croak "Either ->config->{connect_info} must be defined for $class"
1aeb6e1e	220	. " or $schema_class must have connect info defined on it";
0f2fd2c0	221	}
	222	}
	223
ad91060a	224	$self->composed_schema($schema_class->compose_namespace($class));
ad91060a	225	$self->schema($self->composed_schema->clone);
cd7e6e4f	226
	227	$self->schema->storage_type($self->{storage_type})
	228	if $self->{storage_type};
7db6da78	229
	230	# XXX This is temporary, until DBIx::Class::Storage::DBI supports the
	231	# same syntax and we switch our requisite to that version somewhere
	232	# down the line. This syntax is already committed into DBIx::Class
	233	# dev branch post-0.06.
	234	# At that time, this whole block can revert back to just being:
	235	# $self->schema->connection(@{$self->{connect_info}});
	236
	237	my $connect_info = [ @{$self->{connect_info}} ];
	238	my ($on_connect_do, %sql_maker_opts);
	239	if($DBIx::Class::VERSION < 0.069) {
	240	my $used;
	241	my $last_info = $self->{connect_info}->[-1];
	242	if(ref $last_info eq 'HASH') {
	243	if($on_connect_do = $last_info->{on_connect_do}) {
	244	$used = 1;
	245	}
	246	for my $sql_maker_opt (qw/limit_dialect quote_char name_sep/) {
	247	if(my $opt_val = $last_info->{$sql_maker_opt}) {
	248	$used = 1;
	249	$sql_maker_opts{$sql_maker_opt} = $opt_val;
	250	}
4bd6775c	251	}
7db6da78	252	pop(@$connect_info) if $used;
4bd6775c	253	}
4bd6775c	254	}
ad91060a	255
7db6da78	256	$self->schema->connection(@$connect_info);
	257
	258	if($DBIx::Class::VERSION < 0.069) {
	259	$self->schema->storage->on_connect_do($on_connect_do)
	260	if $on_connect_do;
	261	foreach my $sql_maker_opt (keys %sql_maker_opts) {
	262	$self->schema->storage->sql_maker->$sql_maker_opt(
	263	$sql_maker_opts{$sql_maker_opt}
	264	);
	265	}
	266	}
	267
	268	# XXX end of compatibility block referenced above
	269
ad91060a	270	no strict 'refs';
ad91060a	271	foreach my $moniker ($self->schema->sources) {
0b2a7108	272	my $classname = "${class}::$moniker";
7db6da78	273	*{"${classname}::ACCEPT_CONTEXT"} = sub {
ad91060a	274	shift;
c12b7310	275	shift->model($model_name)->resultset($moniker);
ad91060a	276	}
	277	}
	278
	279	return $self;
	280	}
	281
ad91060a	282	sub clone { shift->composed_schema->clone(@_); }
ad91060a	283
ad91060a	284	sub connect { shift->composed_schema->connect(@_); }
ad91060a	285
b8427e0b	286	sub storage { shift->schema->storage(@_); }
b8427e0b	287
ad91060a	288	=head1 SEE ALSO
ad91060a	289
7b39f3f0	290	General Catalyst Stuff:
	291
	292	L<Catalyst::Manual>, L<Catalyst::Test>, L<Catalyst::Request>,
	293	L<Catalyst::Response>, L<Catalyst::Helper>, L<Catalyst>,
	294
	295	Stuff related to DBIC and this Model style:
	296
	297	L<DBIx::Class>, L<DBIx::Class::Schema>,
	298	L<DBIx::Class::Schema::Loader>, L<Catalyst::Helper::Model::DBIC::Schema>,
1aeb6e1e	299	L<Catalyst::Helper::Model::DBIC::SchemaLoader>
ad91060a	300
	301	=head1 AUTHOR
	302
	303	Brandon L Black, C<blblack@gmail.com>
	304
	305	=head1 COPYRIGHT
	306
	307	This program is free software, you can redistribute it and/or modify it
	308	under the same terms as Perl itself.
	309
	310	=cut
	311
	312	1;