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.
SEE ALSO
Database::Wrapper,MIME::Lite,Time::Timestamp,Net::IP
AUTHOR
Wes Young, <saxguard9-cpan@yahoo.com>
COPYRIGHT AND LICENSE
Copyright (C) 2006 by Wes Young
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.