/ 
MooseX-DBIC-Scaffold-0.102881
/ MooseX::DBIC::Scaffold

NAME

MooseX::DBIC::Scaffold - Schema class scaffold generator for DBIx::Class

VERSION

version 0.102881

SYNOPSIS

use MooseX::DBIC::Scaffold;
use SQL::Translator;
use DBI;

my $dbh = DBI->connect($dsn, $user, $pass);

my $sqlt = SQL::Translator->new(dbh => $dbh, from => 'DBI');
$sqlt->parse(undef);

my $scaffold = MooseX::DBIC::Scaffold->new(
  schema       => $sqlt->schema,
  schema_class => 'My::Schema',
);

$scaffold->produce(\*STDOUT);

DESCRIPTION

MooseX::DBIC::Scaffold creates a scaffold of code for DBIx::Class using a schema object from SQL::Translator. At time of writing the version of SQL::Translator required is not available on CPAN and must be fetched directly from github.

The result is a hierarchy of packages describes below. Moose is used so that any custom methods needed to be added to the result or resultset classes can be done by writing Moose::Role classes. This allows separation between generated code and written code.

MooseX::DBIC::Scaffold defines methods to map table names to class names, relationships and columns to accessor methods. It is also possible to have any table, relationship or column excluded from the generated model. If the defaults do not meet your needs, then it is trvial to subclass MooseX::DBIC::Scaffold and provide overrides.

Package Hierarchy

Given a schema_class name of Schema and a schema containing a single table foo_bars the following packages would be created or searched for with the default settings.

Schema

Top level schema class. The user needs to provide this themselves. See "Example Schema Class".

Schema::_scaffold

The main generated package that will be a Moose::Role to be consumed into the top level schema class. See "The _scaffold Role"

Although the model generated is a hierarchy of packages, it is expected that all generated code be in one file loaded as Schema::_scaffold. This file contains all the generated code and should never be modified.

Schema::_dbic

A subclass of DBIx::Class::Schema that will be used to register the generated classes.

Schema::FooBar

Schema::FooBar will be the result class for the table foo_bars

Schema::Role::FooBar

During scaffolding Module::Pluggable will be used to search for Schema::Role::FooBar, which should be a Moose::Role class. If it exists then it will be consumed into Schema::FooBar.

Schema::ResultSet::FooBar

Schema::ResultSet::FooBar is the resultset class for the table foo_bars.

Schema::ResultSet::Role::FooBar

During scaffolding Module::Pluggable will be used to search for Schema::ResultSet::Role::FooBar, which should be a Moose::Role class. If it exists then it will be consumed into Schema::ResultSet::FooBar.

The _scaffold Role

The _scaffold will define methods for each resultset. In our example above it will define a method foo_bar.

It also has a method dbic which will return the DBIx::Class::Schema object.

Example Schema Class

The minimum requirement for a schema class is that it providers a method connect_args. The result of calling this method will be passed to the connect method of DBIx::Class::Schema.

package Schema;
use Moose;
with 'Schema::_scaffold';

sub connect_args { 
    return @args_for_dbix_class_connect;
}

1;

Some other useful additions

# delegate txn_* methods to the DBIx::Class object itself
has '+dbic' => (handles => [qw(txn_do txn_scope_guard txn_begin txn_commit txn_rollback)]);

# Fetch a DBI handle
sub dbh {
  shift->dbic->storage->dbh;
}

With our example schema, searching of the foo_bars table would be done with

my $schema = Schema->new;
$schema->foo_bar->search({id => 27});

ATTRIBUTES

schema

Required. A SQL::Translator::Object::Schema object that the scaffolding will be generated from.

schema_class

Required. Package name that the scaffold will be generated for. The actual package created will be a Moose::Role with the named schema_class plus ::_scaffold

result_class_namespace

Optional. Namespace used by default to prefix package names generated for DBIx::Class result classes. Defaults to schema_class

resultset_class_namespace

Optional. Namespace used by default to prefix package names generated for DBIx::Class result set classes. Defaults to result_class_namespace plus ::ResultSet

result_role_namespace

Optional. Namespace that will be searched for, during scaffolding, for roles to add to result classes. The generated code will include with statements for any role that is found during scaffolding. Defaults to result_class_namespace plus ::Role

resultset_role_namespace

Optional. Namespace that will be searched for, during scaffolding, for roles to add to result set classes. The generated code will include with statements for any role that is found during scaffolding. Defaults to resultset_class_namespace plus ::Role

METHODS

table_components ( $table )

Returns a list of DBIx::Class components to be loaded by the result class

column_components ( $column )

Returns a list of DBIx::Class components to be loaded by the result class

table_roles ( $table )

Returns a list of Moose::Role classes to be comsumed into the result class Default is to join result_role_namespace with table_class_element, if the module can be found by Module::Pluggable

resultset_roles ( $table )

Returns a list of Moose::Role classes to be comsumed into the result class. Default is to join resultset_role_namespace with table_class_element, if the module can be found by Module::Pluggable

column_info ( $column )

Returns a hash reference which will be serialized as the arguments passed to add_column

insert_default ( $column )

Provides a hook to allow inserting objects to have default values set on columns if no value has been specified. It should return valid perl code that will be inserted into the generated code and will be evaluated in a scalar context

ignore_table ( $table )
ignore_column ( $column )
ignore_index ( $index )
ignore_constraint ( $constraint )
ignore_relationship ( $relationship )

Return a boolean to determine if the passed object should be excluded from the generated model. Default: 0

relationship_accessor ( $relationship )

Returns name for a relationship. Default is to call the method based on the relationship type.

mapping_accessor ( $mapping )
belongs_to_accessor ( $relationship )
might_have_accessor ( $relationship )
has_one_accessor ( $relationship )
has_many_accessor ( $relationship )

Return relationship accessor name. Default is to call to_singlular or to_plural with the name for the foreign table. Which is called depends on the arity of the relationship

column_accessor

Return the accessor name for the column. Default it to return the column name.

result_class ( $table )

Return name for the result class. Default is to join result_class_namespace with table_class_element

resultset_class

Return name for the resultset class. Default is to join resultset_class_namespace with table_class_element

table_moniker

Return moniker used to register result class with DBIx::Class::Schema. Default is to call to_singular with the lowercase table name

table_class_element

Return package name element that will be prefixed with result_class_namespace, resultset_class_namespace, result_role_namespace and resultset_role_namespace to generate class names. Default takes the table_moniker and title-cases based on _ as a word separator

to_singular ( $word )

Utility method to return singular form of $word. Default implementation uses "to_S" in Lingua::EN::Inflect::Number

to_plural ( $word )

Utility method to return plural form of $word. Default implementation uses "to_PL" in Lingua::EN::Inflect::Number

reciprocate_relationship ( $relationship )

Create a relatonship which is the opposite of the given relationship.

is_mapping_table ( $table )

Return boolean to indicate if the table is a mapping table and many to many mapping relationships need to be created

produce ( $fh )

Generate code and write to filehandle

build_relationship ( $constraint )

Build a MooseX::DBIC::Scaffold::Relationship object given a constraint

build_mapping ( $relationship, $relationship )

Build a MooseX::DBIC::Scaffold::Mapping given relationship for a mant to many mapping

SEE ALSO

DBIx::Class, Moose, Moose::Role, SQL::Translator

At time of writing the version required is not available on CPAN and needs to be fetched from github. http://github.com/arcanez/SQL-Translator

AUTHOR

Graham Barr <gbarr@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Graham Barr.

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