The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.


FWS::Lite - Version independent access to Framework Sites installations and common methods


Version 0.004


        use FWS::Lite;

        # Create FWS with MySQL connectivity
        my $fws = FWS::Lite->new(       DBName          => "theDBName",
                                        DBUser          => "myUser",
                                        DBPassword      => "myPass");

        # create FWS with SQLite connectivity
        my $fws2 = FWS::Lite->new(      DBType          => "SQLite",
                                        DBName          => "/home/user/your.db");


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 in a small package.


Most uses of FWS::Lite are accessing data from live FWS installations and do not require anything but the database credentials. All non-required settings 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.


        my $fws = $fws->new(
                DBName          => "DBNameOrSQLitePathAndFile", # MySQL required
                DBUser          => "myDBUser",                  # MySQL required
                DBPassword      => "myDBPassword",              # MySQL required
                DBHost          => "",   # default: localhost
                DBType          => "MySQL")                     # default: MySQL

Depending on if you are connecting to a MySQL or SQLite a combination of the following are required.

  • DBName (MySQL and SQLite Required)

    For MySQL this is the DB Name. For SQLite this is the DB file path and file name. MySQL example: user_fws SQLite example: /home/user/secureFiles/user_fws.db

  • DBUser (MySQL Required)

    Required for MySQL and is the database user that has full grant access to the database.

  • DBPassword (MySQL Required)

    The DBUser's password.

  • DBHost (MySQL Required if your database is not on localhost)

    The DBHost will default to 'localhost' if not specified, but can be what ever is configured for the database environment.

  • DBType (SQLite Required)

    The DBType will default to 'MySQL' if not specified, but needs to be added if you are connecting to SQLite.

Non-required parameters for FWS installations can be added, but depending on the scope of your task they usually are not needed unless your testing code, or interacting with web elements that display rendered content from a stand alone script.

  • domain

    Full domain name with http prefix. Example:

  • filePath

    Full path name of common files. Example: /home/user/www/files

  • fileSecurePath

    Full path name of non web accessible files. Example: /home/user/secureFiles

  • fileWebPath

    Web path for the same place filePath points to. Example: /files

  • secureDomain

    Secure domain name with https prefix. For non-secure sites that do not have an SSL cert you can use the http:// prefix to disable SSL. Example:


FWS methods that connect, read, write, reorder or alter the database itself.


Do the initial database connection via MySQL or SQLite. This method will return back the DBH it creates, but it is only here for completeness and would normally never be used. For FWS database routines this is not required as it will be implied when executing those methods..



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";


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


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


FWS methods that use or manipulate text either for rendering or default population.


Return a non repeatable 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();


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);


FWS methods that access the file system for its results.


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";


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.


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");


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");


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");


Nate Lewis, <nlewis at>


Please report any bugs or feature requests to bug-fws-lite at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

    perldoc FWS::Lite

You can also look for information at:


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 for more information.