/ 
Valiant-0.002012
River stage one • 1 direct dependent • 1 total dependent
/ DBIx::Class::Valiant::Result

NAME

DBIx::Class::Valiant::Result - Base component to add Valiant functionality

SYNOPSIS

package Example::Schema::Result::Person;

use base 'DBIx::Class::Core';

__PACKAGE__->load_components('Valiant::Result');

Or just add to your base Result class

package Example::Schema::Result;

use strict;
use warnings;
use base 'DBIx::Class::Core';

__PACKAGE__->load_components('Valiant::Result');

DESCRIPTION

Glue Valiant validations into your DBIC result sources. This package just has some basic API level docs, you should see DBIx::Class::Valiant for a somewhat more detailed documentation and examples.

CONTEXTS

When doing an insert / create on a result, we automatically add a 'create' context which you can use to limit validations to create events. Additionally for an update we add an 'update' context.

CLASS METHODS

This component adds the following class or package methods to your result classes. Please note this is only class methods added by this package, it does not cover those which are aggregated from the Valiant::Validates role.

auto_validation (Boolean)

Defaults to true. When true Valiant will first perform a validation on the existing result object (and any related objects nested under it which have been loaded from the DB or created) and if there are validation errors will skip persisting the data to the database. You can use this to disable this behavior globally. Please not there are features to enable skipping auto validation on a per result/set basis as well.

accept_nested_for (field => \%options)

Allows you to update / create related objected which are nested under the parent (via has_one, might_have or has_many defined relationships). Accepts the following hashref of options:

allow_destroy

By default you cannot delete related (nested) results. Setting this to true allows that.

reject_if

A coderef that will cause a nested result to skip if you return true. Arguments are the parent result and a hashref of the values to be used for the nested build:

__PACKAGE__->accept_nested_for(
  might => {
    reject_if => sub {
      my ($self, $params) = @_;
      return ($params->{value}||'') eq 'test14' ? 1:0;
    },
  }
);

Please note that if you have this on a has_many relationship the code ref will be invoked on each result in the collection of related results you are attempted to nest values into. This can impact performance.

limit

accepts a scalar which will cause the nested results to fail of the number of items is greater than the scalar.

update_only

For has_one or might_have relationships will force update the existing nested result (if any exists) even if you fail to set the primary key. Otherwise the current record will be deleted and a new one inserted. Default is false.

find_with_uniques

Generally we only try to find a matching row in the DB if a primary key is given. If you set this to true then we also try to match using and unique keys establish for the related row.

If you set this flag to 'allow_create' then we will allow the creation of a new related row if we can't find one in the DB. Otherwise we will set an error if the related row can't be found. You should be careful here because allowing the creation of a new related row could be a security risk (a hacker could try to insert a new related row by guessing the unique keys). That's why the default behavior is to set an error if the related row can't be found.

NOTE Recursion warning! You cannot currently accept_nested_for for a relationship whose target result source is setting accept_nested_for into yourself. This is probably fixable, patches and use cases welcomed!

METHODS

This component adds the following object methods. Please note this is only class methods added by this package, it does not cover those which are aggregated from the Valiant::Validates role.

is_marked_for_deletion

Will be true if the result has been marked for deletion. You might see this in a related result nested under a parent when an update calls for the record to be deleted but validation errors prevented the deletion from occuring.

is_pruned

Will be true if the result is nested under a result which has been marked_for_deletion. The result is not itself marked to be deleted (if validation passes) but it will no longer be attached to the parent result under which it is nested.

is_removed

Is true if is_pruned or is_marked_for_deletion is true.

Builds a related result into the cache. The result is only in memory; it can be used to run validation but is not inserted unless specified later.

You might use these methods if you are validating a nested results but the results are not already in the database (see example directory for an application that uses this).

AUTHOR

John Napiorkowski email:jjnapiork@cpan.org

SEE ALSO

Valiant, DBIx::Class

COPYRIGHT & LICENSE

Copyright 2020, John Napiorkowski email:jjnapiork@cpan.org

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