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, 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.