NAME

       DBIx::Class::Factory - factory-style fixtures for DBIx::Class

VERSION

       Version 0.04

SYNOPSIS

       Create factory:

           package My::UserFactory;
           use base qw(DBIx::Class::Factory);

           __PACKAGE__->resultset(My::Schema->resultset('User'));
           __PACKAGE__->fields({
               name => __PACKAGE__->seq(sub {'User #' . shift}),
               status => 'new',
           });

           package My::SuperUserFactory;
           use base qw(DBIx::Class::Factory);

           __PACKAGE__->base_factory('My::UserFactory');
           __PACKAGE__->field(superuser => 1);

       Use factory:

           my $user = My::UserFactory->create();
           my @verified_users = @{ My::UserFactory->create_batch(3, {status => 'verified'}) };

           my $superuser = My::SuperUserFactory->build();
           $superuser->insert();

DESCRIPTION

       Ruby has "factory_girl", Python has "factory_boy". Now Perl has "DBIx::Class::Factory".

       Creating big fixture batches may be a pain. This module provides easy way of creating data in database
       via DBIx::Class.

       To create a factory just derive from DBIx::Class::Factory and apply some settings.  You can also add some
       data at the moment of creating instance, redefining factory defaults.

       Tests for this module contains a bunch of useful examples.

METHODS

   Factory settings
       base_factory
           Use this to create one factory derived from another. Don't use direct inheritance.

       resultset
           Set resultset this factory is going to work with.

       fields
           Accept hashref as an argument. Add fields to factory. See "field" for more details.

       field
               __PACKAGE__->field($name => $value);

           Add  field  to  the  factory. $name is directly used in resultset's "new" method.  $value must be any
           value or helper result (see "Helpers").  "CODEREF" as a value will be used as callback. However,  you
           must not rely on this, it can be changed in future releases — use "callback" helper instead.

       exclude
           Sometimes you want some fields to be in the factory but not in the created object.

           You can use "exclude" to exclude them. Both arrayref and scalar are accepted.

               {
                   package My::UserFactory;

                   use base qw(DBIx::Class::Factory);

                   __PACKAGE__->resultset(My::Schema->resultset('User'));
                   __PACKAGE__->exclude('all_names');
                   __PACKAGE__->fields({
                       first_name => __PACKAGE__->callback(sub {shift->get('all_names')}),
                       last_name => __PACKAGE__->callback(sub {shift->get('all_names')}),
                   });
               }

               My::UserFactory->create({all_names => 'Bond'});

   Helpers
       Sometimes you want the value of the field to be not just static value but something special.  Helpers are
       here for that.

       callback
           Sometimes  you  want  field  value  to  be calculated every time fields for object are created.  Just
           provide "callback" as a value in that case.

           It will be called with the DBIx::Class::Factory::Fields instance as an argument.

               __PACKAGE__->fields({
                   status => __PACKAGE__->callback(sub {
                       my ($fields) = @_;

                       return $fields->get('superuser') ? 3 : 5;
                   }),
               });

       seq Same as "callback", but the callback is called with  an  additional  first  argument:  the  iterating
           counter.

           You can also provide the initial value of the counter (0 is default).

               __PACKAGE__->field(id => __PACKAGE__->seq(sub {shift}, 1));

       related_factory
           This  helper just calls another factory's "get_fields" method.  Thanks to "DBIx::Class", the returned
           data will be used to create a related object.

               package My::UserFactory;

               use base qw(DBIx::Class::Factory);

               __PACKAGE__->resultset(My::Schema->resultset('User'));
               __PACKAGE__->fields({
                   # create a new city if it's not specified
                   city => __PACKAGE__->related_factory('My::CityFactory'),
               });

       related_factory_batch
           Same as "related_factory", but calls "get_fields_batch" method.

               __PACKAGE__->fields({
                   # Add three accounts to the user
                   accounts => __PACKAGE__->related_factory_batch(3, 'My::AccountFactory')
               });

   Factory actions
       get_fields
           Returns fields that will be used to create object without creating something.

       build
           Creates DBIx::Class::Row object without saving it to a database.

       create
           Creates DBIx::Class::Row object and saves it to a database.

           "discard_changes" in DBIx::Class::Row is also called on the created object.

       get_fields_batch
           Runs "get_fields" "n" times and returns arrayref of results.

       build_batch
           Runs "build" "n" times and returns arrayref of results.

       create_batch
           Runs "create" "n" times and returns arrayref of results.

   Hooks
       You can define the following methods in your factory to be executed after corresponding methods.

       They take result of the corresponding methods as an argument and must return the new one.

       after_get_fields
       after_build
       after_create
               sub after_create {
                   my ($class, $user_row) = @_;

                   $user_row->auth();

                   return $user_row;
               }

DEDICATION

       This module is lovingly dedicated to my wife Catherine.

AUTHOR

       Vadim Pushtaev, "pushtaev@cpan.org"

BUGS AND FEATURES

       Bugs are possible, feature requests are welcome. Write me as soon as possible.

LICENSE AND COPYRIGHT

       Copyright 2015 Vadim Pushtaev.

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

perl v5.36.0                                       2023-02-14                          DBIx::Class::Factory(3pm)