NAME

DBIx::Mint::Table - Role that maps a class to a table

SYNOPSIS

 # In your class:
 
 package Bloodbowl::Coach;
 use Moo;
 with 'DBIx::Mint::Table';
 
 has 'id'     => ( is => 'rwp', required => 1 );
 has 'name'   => ( is => 'ro',  required => 1 );
 ....
 
 # And in your schema:
 $schema->add_class(
    class   => 'Bloodbowl::Coach',
    table   => 'coaches',
    pk      => 'id',
    auto_pk => 1
 );
 
 # Finally, in your application:
 my $coach = Bloodbowl::Coach->find(3);
 say $coach->name;
 
 $coach->name('Will E. Coyote');
 $coach->update;
 
 my @ids = Bloodbowl::Coach->insert(
    { name => 'Coach 1' },
    { name => 'Coach 2' },
    { name => 'Coach 3' }
 );
 
 $coach->delete;
 
 my $coach = Bloodbowl::Coach->find_or_create(3);
 say $coach->id;
 
 # The following two lines are equivalent:
 my $rs = Bloodbowl::Coach->result_set;
 my $rs = DBIx::Mint::ResultSet->new( table => 'coaches' );

DESCRIPTION

This role allows your class to interact with a database table. It allows for record modification (insert, update and delete records) as well as data fetching (find and find_or_create) and access to DBIx::Mint::ResultSet objects.

Database modification methods can be called as instance or class methods. In the first case, they act only on the calling object. When called as class methods they allow for the modification of several records.

Triggers can be added using the methods before, after, and around from Class::Method::Modifiers.

The database modifying parts of the routines are run under DBIx::Connector's fixup mode, as they are so small that no side-effects are expected. If you use transactions, the connection will be checked only at the outermost block method call. See DBIx::Connector for more information.

METHODS

create

This methods is a convenience that calls new and insert to create a new object. The following two lines are equivalent:

 my $coach = Bloodbowl::Coach->create( name => 'Will E. Coyote');
 my $coach = Bloodbowl::Coach->new( name => 'Will E. Coyote')->insert;

Or, using a different database connection:

 my $mint  = DBIx::Mint->instance('other');
 my $coach = Bloodbowl::Coach->create( $mint, name => 'Will E. Coyote');

insert

When called as a class method, it takes a list of hash references and inserts them into the table which corresponds to the calling class. The hash references must have the same keys to benefit from a prepared statement holder. The list of fields is taken from the first record. If only one record is used, it can be simply a list of key-value pairs.

When called as an instance method, it inserts the data contained within the object into the database.

 # Using the default DBIx::Mint object:
 
 Bloodbowl::Coach->insert( name => 'Bruce Wayne' );
 Bloodbowl::Coach->insert(
    { name => 'Will E. Coyote' },
    { name => 'Clark Kent'     },
    { name => 'Peter Parker'   });

 $batman->insert;

Additionally, it can be given an alternative DBIx::Mint object to act on a connection other than the default one:

 # Using a given DBIx::Mint object:
 Bloodbowl::Coach->insert( $mint,
    { name => 'Will E. Coyote' },
    { name => 'Clark Kent'     },
    { name => 'Peter Parker'   });

 $batman->insert($mint);

update

When called as a class method it will act over the whole table. The first argument defines the change to update and the second, the conditions that the records must comply with to be updated:

 Bloodbowl::Coach->update( { email => 'unknown'}, { email => undef });
 

When called as an instance method it updates only the record that corresponds to the calling object:

 $coach->name('Mr. Will E. Coyote');
 $coach->update;

To use a DBIx::Mint instance other than the default one:

 my $mint = DBIx::Mint->instance('database_2');
 Bloodbowl::Coach->update( { email => 'unknown'}, { email => undef }, $mint);

delete

This method deletes information from the corresponding table. When called as a class method it acts on the whole table; when called as an instance method it deletes the calling object from the database:

 Bloodbowl::Coach->delete({ email => undef });
 Bloodbowl::Team->delete( name => 'Tinieblas');
 $coach->delete;

The statements above delete information using the default database connection. If a named DBIx::Mint instance is needed:

 my $mint = DBIx::Mint->instance('database_2');
 Bloodbowl::Coach->delete({ email => undef }, $mint);

find

Fetches a single record from the database and blesses it into the calling class. It can be called as a class record only. It can as take as input either the values of the primary keys for the corresponding table or a hash reference with criteria to fetch a single record:

 my $coach_3 = Bloodbowl::Coach->find(3);
 my $coach_3 = Bloodbowl::Coach->find({ name => 'coach 3'});

To use a named DBIx::Mint instance:

 my $mint = DBIx::Mint->instance('database_2');
 my $coach_3 = Bloodbowl::Coach->find({ id => 3 }, $mint);

find_or_create

This method will call 'create' if the requested record is not found in the database.

 my $obj = Bloodbowl::Coach->find_or_create(
    name => 'Bob', email => 'bob@coaches.net'
 );
 my $obj = Bloodbowl::Coach->find_or_create(
    $mint, { name => 'Bob', email => 'bob@coaches.net' }
 );

result_set

Get a DBIx::Mint::ResultSet object for the table associated with this class. Optionally, use a named Mint object:

 my $rs = Bloodbowl::Team->result_set;            # With default db
 my $rs = Bloodbowl::Team->result_set('other');   # With other db

SEE ALSO

This module is part of DBIx::Mint.

AUTHOR

Julio Fraire, <julio.fraire@gmail.com>

LICENCE AND COPYRIGHT

Copyright (c) 2013, Julio Fraire. All rights reserved.

LICENSE

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

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

cpanm DBIx::Mint

perl -MCPAN -e shell
install DBIx::Mint