/ 
DBICx-Shortcuts-0.007
River stage one • 1 direct dependent • 1 total dependent
/ DBICx::Shortcuts

NAME

DBICx::Shortcuts - Setup a class with shortcut methods to the sources of a DBIx::Class-based schema

VERSION

version 0.007

SYNOPSIS

package S;
use parent 'DBICx::Shortcuts';

__PACKAGE__->setup('Class::Of::Your::Schema');

## Alternate version, this one import txn_do from DBIx::Class::Schema
## __PACKAGE__->setup('Class::Of::Your::Schema', 'txn_do');

sub connect_info {
  ## return DBIx::Class::Schema::connect() arguments
  return ('dbi:SQLite:test.db', undef, undef, {AutoCommit => 1});
}

1;


# And on your code, assuming you had a Books source

# Without arguments, returns ResultSet
$book = S->books->create({ ... });

# With first argument as a defined non-ref, passes @_ to find()
$book = S->books(42);  ## 42 is the PK of the book

# With first argument as a ScalarRef, uses a unique constraint
$book = S->book(\'isbn_key', '9123123432123');

# All other cases, calls search()
$rs = S->books({title => { like => '%Perl%' }});

DESCRIPTION

If you use DBIx::Class a lot, you soon get tired of writting:

$schema->resultset('Books')->create({...});

All that resultset($source_name') bussiness is a lot of code to write.

The DBICx::Shortcuts class provides you with a shorter alternative. First you must create a new class, S for example, and connect it to the real Schema class using the "setup()" method.

For each source defined in your schema class, a method will be created in the shortcut class.

This method can be used in four ways.

If called without parameters, the shortcut method will return a ResultSet for the source. Usefull to call create().

If called with parameters where the first is not a reference, it calls find(). Usefull to fetch a row based on the primary key.

If called with parameters where the first is a scalarRef, we assume it to be the name of the unique constraint to use, and the rest of the arguments to be the required values for that constraint.

In all other cases, it calls search() and returns the resultset.

Connection information

But to do this, your shortcuts class needs to connect your schema to the database. To do that, you must override the "connect_info()" method and have it return all the required connect() parameters.

METHODS

setup()

package MyShortcutsClass;
__PACKAGE__->setup('MySchemaClass');
## or
__PACKAGE__->setup('MySchemaClass', 'txn_do', 'storage', $other_methods);

The "setup()" accepts your schema class as a parameter, loads it, and creates a shortcut method for each source found inside.

Optionally you can follow with a list of methods that you want to create as shortcuts to the same named method in DBIx::Class::Schema.

You can control some aspects of the shortcut creation using the <source_info()|DBIx::Class::ResultSource/source_info> ResultSource metadata hashref. The following keys are supported:

shortcut

Defines the name of the shortcut to create for this source.

If the shortcut is declared as undef, no shortcut wil be created for this source.

skip_shortcut

If true, disables the creation of a shortcut key for this source.

This is available as a more explicit alternative to setting the shortcut key to undef.

schema()

Returns a connected and ready to use schema object. Uses the "connect_info()" information to connect.

connect_info()

This method is not to be called directly, but to be defined by your own shortcut class.

It must return the parameters that DBICx::Shortcuts must use in the call to connect() to create the schema object.

DIAGNOSTICS

The following exceptions might be thrown:

Shortcut failed, '$method' already defined in '$class'

If two sources use the same shortcut, or if you define an adition method on your shortcuts class that conflits with a source method, you will get this exception in the call to "setup()".

Class '$class' did not call 'setup()'

If you forgot to call "setup()" and start calling "schema()", this is the result.

Class '$shortcuts_class' needs to override 'connect_info()'

You forgot to override the "connect_info()" method.

Also, the "setup()" method calls "require" in perlfunc to load your schema class, and propagates any exception that you might get from that call.

SEE ALSO

DBIx::Class

AUTHOR

Pedro Melo, <melo@simplicidade.org>

COPYRIGHT & LICENSE

Copyright 2010 Pedro Melo

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