NAME
FWS::Lite - Lightweight access to FWS methodologies and installations
VERSION
Version 0.001
SYNOPSIS
use FWS::Lite;
#
# Create FWS with MySQL connectivity
# (GUIDNameSpace is not required for non-enterprise level installs)
#
my $fws = FWS::Lite->new( DBName => "theDBName",
DBUser => "myUser",
DBPassword => "myPass",
DBHost => "localhost",
GUIDNameSpace => "www.domain.com");
#
# create FWS with SQLite connectivity
#
my $fws = FWS::Lite->new( DBType => "SQLite",
DBName => "/home/user/your.db",
GUIDNameSpace => "www.domain.com");
DESCRIPTION
This module provides basic input and output to a FrameWork Sites installation or can be used independently using the methodologies of FrameWork Sites data structures and file handling.
CONSTRUCTOR
Most uses of the FWS in the context of using FWS::Lite are accessing data from live FWS installations and do not require: filePath, secureFilePath or siteId. These can be set for completeness or for the ability to run native FWS Code via FWS::Lite for testing that needs these set to determine location and site context. GUIDNameSpace is only used when you have Data::UUID installed and even then isn't required unless you are doing migrations with enterprise level data.
new
my $fws->new(
DBName => "DBNameOrSQLitePathAndFile", #required
DBUser => "myDBUser", #required
DBPassword => "myDBPassword", #required
DBHost => "somePlace.somewhere.com", #default: localhost
DBType => "MySQL", #default: MySQL
GUIDNameSpace => "url.NameSpaceDomain.com"); #optional unless enterprise
#default: www.frameworksites.com
DATA METHODS
FWS methods that connect, read, write, reorder or alter the database itself.
connectDBH
Do the initial database connection via MySQL or SQLite.
$fws->connectDBH();
runSQL
Return an reference to an array that contains the results of the SQL ran.
#
# retrieve a reference to an array of data we asked for
#
my $dataArray = $fws->runSQL(SQL=>"select id,type from id_and_type_table"); # Any SQL statement or query
#
# loop though the array
#
while (@$dataArray) {
#
# collect the data each row at a time
#
my $id = shift(@$dataArray);
my $type = shift(@$dataArray);
#
# display or do something with the data
#
print "ID: ".$id." - ".$type."\n";
}
alterTable
Alter a table to conform to the given definition without restriction. The key will describe its index type and lesser definitions of field type will be applied without error or fault. The return will give back any statement that was used to alter the table definition or table creation statement. Use with caution on existing fields as its primary use is for new table creation or programmatic adding of new fields to a table that might not have a field that is needed.
#
# retrieve a reference to an array of data we asked for
#
# Note: It is not recommended to change the data structure of
# FWS default tables
#
print $fws->alterTable( table =>"table_name", # case sensitive table name
field =>"field_name", # case sensitive field name
type =>"char(255)", # Any standard cross platform type
key =>"", # MUL, PRIMARY KEY, FULL TEXT
default =>""); # '0000-00-00', 1, 'this default value'...
tableFieldHash
Return a multi-dimensional hash of all the fields in a table with its properties. This usually isn't used by anything but internal table alteration methods, but it could be useful for someone making conditionals to determine the data structure before adding or changing data.
$tableFieldHashRef = $fws->tableFieldHash('the_table');
#
# the return dump will have the following structure
#
$hash->{field}{type}
$hash->{field}{key}
$hash->{field}{ord}
$hash->{field}{null}
$hash->{field}{default}
$hash->{field}{extra}
$hash->{field_2}{type}
$hash->{field_2}{key}
$hash->{field_2}{ord}
$hash->{field_2}{null}
$hash->{field_2}{default}
$hash->{field_2}{extra}
...
FORMAT METHODS
FWS methods that use or manipulate text either for rendering or default population.
createGUID
Return a Globally Unique Identifier to be used to populate the guid field that is default on all FWS tables.
#
# retrieve a guid to use with a new record
#
my $guid = $fws->createGUID();
createPassword
Return a random password or text key that can be used for temp password or unique configurable small strings.
#
# retrieve a password that is 6-8 characters long and does not contain commonly mistaken letters
#
my $tempPassword = $fws->createPassword(
composition => "qwertyupasdfghjkzxcvbnmQWERTYUPASDFGHJKZXCVBNM23456789"
lowLength => 6,
highLength => 8);
FILE METHODS
FWS methods that access the file system for its results.
fileArray
Return a directory listing into a FWS hash array reference.
#
# retrieve a reference to an array of data we asked for
#
my $fileArray = $fws->fileArray( directory =>"/home/directory" );
#
# loop though the array printing the files we found
#
for my $i (0 .. $#$fileArray) {
print $fileArray->[$i]{"file"}. "\n";
}
SAFETY METHODS
FWS Safety methods are used for security when using unknown parameters that could be malicious. When ever data is passed to another method it should be wrapped in its appropriate safety method under the guidance of each method.
safeDir
All directories should be wrapped in this method before being applied. It will remove any context that could change its scope to higher than its given location. When using directories ALWAYS prepend them with $fws->{"fileDir"} or $fws->{"secureFileDir"} to ensure they root path is always in a known location to further prevent any tampering. NEVER use a directory that is not prepended with a known depth!
#
# will return //this/could/be/dangerous
#
print $fws->safeDir("../../this/could/be/dangrous");
#
# will return this/is/fine
#
print $fws->safeDir("this/is/fine");
safeFile
All files should be wrapped in this method before being applied. It will remove any context that could change its scope to a different directory.
#
# will return ....i-am-trying-to-change-dir.ext
#
print $fws->safeDir("../../i-am-trying-to-change-dir.ext");
safeSQL
All fields and dynamic content in SQL statements should be wrapped in this method before being applied. It will add double tics and escape any escapes so you can not break out of a statement and inject anything not intended.
#
# will return this '' or 1=1 or '' is super bad
#
print $fws->safeSQL("this ' or 1=1 or ' is super bad");
AUTHOR
Nate Lewis, <nlewis at gnetworks.com>
BUGS
Please report any bugs or feature requests to bug-fws-lite at rt.cpan.org
, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=FWS-Lite. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc FWS::Lite
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
LICENSE AND COPYRIGHT
Copyright 2012 Nate Lewis.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.