NAME

Database::Schema::Verification - Perl extension for storing and verifing various levels of information

SYNOPSIS

  use Database::Schema::Verification;

  my $v = Database::Schema::Verification->new(
        -dbh => $dbh,
        -type => 'my_type',
        -type_id => 22,
        -msg => $txtVerificationEmailMsg,
  );

  my $rv = $v->check();
  my $rv = $v->insert();
  my $rv = $v->isVerified();
  my $rv = $v->load();
  my $rv = $v->requestVerification();
  my $rv = $v->verifiy(-action => 1);
  my $rv = $v->remove();

  # returns array of Database::Schema::Verification objects
  # each of a hardcoded return limit of 500, wich can be overwritten
  my @ary = $v->returnUnprocessed();
  my @ary = $v->returnUnverified();

DESCRIPTION

The Verification module provides an easy storage interface for keeping track of what data has been verified, what has been surpressed and what needs verification. At it's core it provides a relation between it's master key (vid) and a combination of the type of data you are working with (usually associates with a table within your database) and it's master key. This module also provides you with a simple email tool that provides notification of an event requiring verification.

Accompanied within this is a 'contrib' directory. In there you'll find a CGI script. The purpose of this script is to allow authors the ability to place embedded links within the email notifications. These links can provide a set of parameters that will trigger any of the verification functions. This allows users to click the links in the email and verify or surpess data as it becomes avalible.

The basic concept is to allow authors to insert this where ever they need to. This can be it's own verification database where:

  type => 'databaseName.table',
  type_id => $databaseName.table.keyId

This would allow you to maintain one verification database for multiple databases or applications

OR it can be a simple table embeded into your program database

  type => 'table',
  type_id => $table.keyId

This allows you to scale it as you need it and apply verification to any level of data you are working with.

**Note: All string returns are in the format:

 return ('reason we bombed out...',[undef,0]);

This allows you to extract why the function failed with a:

 my ($str,$rv) = function->check(...);
 if(!defined($rv)){
        die($str);
 }

OBJECT METHODS

new()

Default constructor

  my $v = Database::Schema::Verification->new(
        # required
        -dbh => $dbh,
        -type => 'my_type',
        -type_id => 22,
        -msg => $txtVerificationEmailMsg,

        # optional
        -vid            => $vid,
        -dt_added       => $dt_added, [see Time::Timestamp]
        -dt_updated     => $dt_updated, [see Time::Timestamp]
        -verified       => $verified, # see verified() for inputs
        -verified_by    => $verified_by,
        -verified_by_ip => $verified_by_ip, [see Net::IP]
        -table          => $table # default is 'verification'
  );

dbh [DBI handle]: A DBI handle
vid [int]: This pre-specifies the verification id
type [string]: This is the type of data we are verifiying (usually use the database table we are targeting)
type_id [int]: The key id field for the table data we are verifing
msg [string]: Text to be included in the verification message
dt_added [int|string] (stored as Time::Timestamp obj): Optional: Initial timestamp, automagically inserted if left blank
dt_updated [int|string] (stored as Time::Timestamp obj): Optional: Last updated timestamp, automagically handled if left blank
verified [int]: Optional: Allows you to auto set the verification status (see verify() for list of inputs
verified_by [string]: Optional: Allows specification of the verifing source (who done did it)
verified_by_ip [string|int] (stores as Net::IP object): Optional: Allows specification of the source ip who verified the data (who's box done did it)
table [string]: Option: Overrides the default base table definition # default is 'verification'

check()

This function checks to see if your key or key pair (type && type_id) already exist in the database. By default $v->vid(), $v->type() and $v->type_id() are taken in the function but can be overwritten with parms.

  $v->check(
        # optional override of object properties
        -type => $type,
        -type_id => $type_id,
        -vid => $vid,
  );

Returns:

  Errstr on failure
  1 on KeyExsits
  0 on keyNotExists

insert()

This function loads a verification object into the database (pre-checks the type && type_id first). By default $v->vid(),$v->type() and $v->type_id() are checked. These can be overwritten with params.

  $v->insert(
        # optional override of object properties
        -type => $type,
        -type_id => $type_id,
        -fork => 1,     # forks back a loaded object on insert completion

        # vid can be set manually, but it's usually auto-incremented by the database
        # all other properties should be set by the new() or their accessors before this is called
  );

Returns:

 0 on KeyExists
 $objectRef [-forkOnExists]
 Errstr on failure
 ($vid,1) on success
 ($objectRef,1) on success [with fork parm]

requestVerification()

Function takes in MIME::Lite parms and submits a notification for review. It can become particularly useful when coupled with a cgi script (see contrib directory). Embedding links into these messages allows you to verify or suppress verification by clicking a link in the email.

  my $msg = 'Please Verify Me!!!!';
  $v->requestVerification(
        -to => 'myself@you.com',
        -from => 'root@localhost',
        -msg => $msg,
        -subject => 'Verification required!!',

        # optional
        -update => 1, # default
  );

Returns:

  Errstr on failure
  1 on success

update

By default, a call to requestVerification() will update our 'verified' status in the table to 0 (notified, but unverified). If for some reason we need to suppress it, setting -update => 0 (NOT UNDEF!) will do override it for us.

debug

This will print the email to screen will cause our database to NOT be updated (no matter what).

  $v-requestVerification(
        ...,
        ...,
        -debug => 1,
  );

Supported Email Args:

  -to,-from,-cc,-bcc,-subject,-type,-msg

See MIME::Lite for more info

Returns:

  Errstr on failure
  1 on success

isVerified()

Method checks to see the verified status of the VID or keypair (type && type_id).

  my $rv = $v->isVerified(
        # optional override of object properties
        -type => $type,
        -type_id => $type_id,
        -vid => $vid,
  );

Returns:

  Errstr on failure
  verified status on success (see verifiy() for more details)

returnVid()

Returns the vid for a given pair of (type && type_id) assuming $v->vid() is not set.

  my $vid = $v->returnVid(
        # optional override of object properties
        -type => $type,
        -type_id => $type_id,
  );

Returns:

  Errstr on failure
  vid on succeess

load()

Loads a verification record into our object or returns a fully loaded forked object.

  $v->load(
        # optional override of object properties
        -type => $type,
        -type_id => $type_id,
  );

  my $newObject = $v->load(
        # optional override of object properties
        -vid => $vid,
        -fork => 1,
  );

Returns:

  Errstr on failure
  1 on success and not forked
  New Object if forked

verify()

Sets the verification status of the object.

  $v->verify(
        # required
        -action => $action,

        # optional override of object properties
        -type => $type,
        -type_id => $type_id,
        -vid => $vid,
        -verified_by => $verified_by,
        -verified_by_ip => $vip,
  );

Actions [and or status]:

  0 - UNVERIFIED        # unverified but notification has been sent [set status to 'wait']
  1 - VERIFY            # duh
  2 - SUPPRESS          # its what jcmurphy likes to call a 'false positive'
  3 - UNDEFINE          # reset so the notification can be triggered again
  4 - REMOVE            # get rid of the evidence

Actions can be sent as strings or ints, it will figure out which automagically.

Returns:

  Errstr on failure
  1 on success

remove()

Removes the record from our table that this object represents.

  $v->remove(
        # optional override of object properties
        -vid => $vid,
        -type => $type,
        -type_id => $type_id,
  );

Returns:

  Errstr on failure
  1 on success

returnUnverified()

By default this method returns an array of unverified objects from the database. Optionally a parm can override this and force the function to return a raw hashref too. There is a HARD_RETURN_LIMIT on the number of keys that can be accessed. This can also be overridden.

  my @aryOfObjects = $v->returnUnverified(
        # optional overrides
        -type => $type
  );

  my $hashref = $v->returnUnverified(
        -limit => 1000,
        -hashref => 1,
  );

limit: This will override the hard coded limit of 500. Setting -limit => 0 will return ALL records (use with caution on large databases). Because of this, if the hard limit is set, the query will return the data in desc order.
hashref: This will return a raw hashref instead of an array of objects (set to 1).

Returns:

  Errstr on failure
  HASHREF or OBJECT on success

returnUnprocessed()

See returnUnVerified().

This returns anything that has verified set to NULL (ie: no notifications have been sent yet).

OBJECT ACCESSORS and MODIFIERS

dbh()

Sets and Retrieves dbh handle

table()

Sets and Retrieves the default table to use in our lookups

vid()

Sets and Retrieves the Verification ID

type()

Sets and Retrieves the type of data we are working with (usually the other table name).

type_id()

Sets and Retrieves the key id for the type of data we are working with (the key in the other table).

verified()

Sets and Retrieves the objects verification status

dt_added()

Sets and Retrieves the date our vid was added. Returns a Time::Timestamp object

dt_updated()

Sets and Retrieves the date our vid was last updated. Returns a Time::Timestamp object

verified_by()

Sets and Retrieves who last set our verified field

verified_by_ip()

Sets and Retrieves what ip was used to set our last verified field. Returns a Net::IP object. Accepts Big::Int's.

msg()

Sets and Retrieves an optional msg that explains what needs verifying (ie: the body used to be sent in a $self->requestVerification() email.

AUTHOR

Wes Young, <saxguard9-cpan@yahoo.com>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.

To install Database::Schema::Verification, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Database::Schema::Verification

CPAN shell

perl -MCPAN -e shell
install Database::Schema::Verification

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

OBJECT METHODS

new()

check()

insert()

requestVerification()

isVerified()

returnVid()

load()

verify()

remove()

returnUnverified()

returnUnprocessed()

OBJECT ACCESSORS and MODIFIERS

dbh()

table()

vid()

type()

type_id()

verified()

dt_added()

dt_updated()

verified_by()

verified_by_ip()

msg()

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions