view release on metacpan or  search on metacpan

lib/DBIx/EAV/ResultSet.pm  view on Meta::CPAN

can be used to walk through all the L<entities|DBIx::EAV::Entity> the ResultSet
represents.

The query that the ResultSet represents is B<only> executed against
the database when these methods are called:
L</find>, L</next>, L</all>, L</first>, L</count>.

If a resultset is used in a numeric context it returns the L</count>.
However, if it is used in a boolean context it is B<always> true.  So if
you want to check if a resultset has any results, you must use C<if $rs
!= 0>.

=head1 METHODS

=head2 new_entity

=over 4

=item Arguments: \%entity_data

=item Return Value: L<$entity|DBIx::EAV::EntityType>

=back

Creates a new entity object of the resultset's L<type|DBIx::EAV::EntityType> and
returns it. The row is not inserted into the database at this point, call
L<DBIx::EAV::Entity/save> to do that. Calling L<DBIx::EAV::Entity/in_storage>
will tell you whether the entity object has been inserted or not.

    # create a new entity, do some modifications...
    my $cd = $eav->resultset('CD')->new_entity({ title  => 'CD1' });
    $cd->set('year', 2016);

    # now insert it
    $cd->save;

=head2 insert

=over 4

=item Arguments: \%entity_data

=item Return Value: L<$entity|DBIx:EAV::Entity>

=back

Attempt to create a single new entity or a entity with multiple related entities
in the L<type|DBIx::EAV::EntityType> represented by the resultset (and related
types). This will not check for duplicate entities before inserting, use
L</find_or_create> to do that.

To create one entity for this resultset, pass a hashref of key/value
pairs representing the attributes of the L</type> and the values you wish to
store. If the appropriate relationships are set up, you can also pass related
data.

To create related entities, pass a hashref of related-object attribute values
B<keyed on the relationship name>. If the relationship is of type C<has_many>
or C<many_to_many> - pass an arrayref of hashrefs.
The process will correctly identify the relationship type and side, and will
transparently populate the L<entitiy_relationships table>.
This can be applied recursively, and will work correctly for a structure
with an arbitrary depth and width, as long as the relationships actually
exists and the correct data has been supplied.

Instead of hashrefs of plain related data (key/value pairs), you may
also pass new or inserted objects. New objects (not inserted yet, see
L</new_entity>), will be inserted into their appropriate types.

Effectively a shortcut for C<< ->new_entity(\%entity_data)->save >>.

Example of creating a new entity.

    my $cd1 = $cds_rs->insert({
        title  => 'CD1',
        year   => 2016
    });

Example of creating a new entity and also creating entities in a related
C<has_many> resultset.  Note Arrayref for C<tracks>.

    my $cd1 = $eav->resultset('CD')->insert({
        title  => 'CD1',
        year   => 2016
        tracks => [
            { title => 'Track1', duration => ... },
            { title => 'Track2', duration => ... },
            { title => 'Track3', duration => ... }
        ]
    });

Example of passing existing objects as related data.

    my @tags = $eav->resultset('Tag')->search(\%where);

    my $article = $eav->resultset('Article')->insert({
        title   => 'Some Article',
        content => '...',
        tags    => \@tags
    });


=over

=item WARNING

When subclassing ResultSet never attempt to override this method. Since
it is a simple shortcut for C<< $self->new_entity($data)->save >>, a
lot of the internals simply never call it, so your override will be
bypassed more often than not. Override either L<DBIx::EAV::Entity/new>
or L<DBIx::EAV::Entity/save> depending on how early in the
L</insert> process you need to intervene.

=back

=head2 populate

=over 4

=item Arguments: \@entites