FORMfields


FORMfields.FfDbHelper

Class FfDbHelper

FfDbHelper

public class FfDbHelper

FfDbHelper contains helper rountines for accessing a database.

Since:
FORMfields v3.0

Field Summary
mixed

$dbLink

A handle to the database connection.

mixed

$dbName

The database name.

mixed

$host

The database hostname or IP.

mixed

$password

The database username's password.

mixed

$user

The database username.

Method Summary
void

connect(boolean ignoreError)

Attempts to connect to the database using a persistent connection and if this fails attempts using a non-persitent connection.

resource

delete(array assocArray, string tableName, boolean ignoreError)

Uses an associative array to delete data in a database table.

void

getDbArray(array values)

Returns an array of database values processed with getDbValue().

string

getDbValue(mixed value)

Escapes the string and then wraps it in single quotes value for easy use in an SQL query.

array

getList(string sql, boolean ignoreError)

Returns an array of values or a "column" or values from the database.

array

getRows(string sql, boolean ignoreError)

Returns an array of rows of data from the database.

string

getSelectClause(mixed attrs, array an)

Returns the parameter section of the SQL select clause generated from an associative array.

string

getSimpleValue(string sql, boolean ignoreError)

Returns a single value of data from the database.

array

getSimpleValues(string sql, boolean ignoreError)

Returns an array of values or a "row" of values from the database.

resource

insert(array assocArray, string tableName, boolean ignoreError)

Uses an associative array to insert data in a database table.

void

insertAttrChanges(string tableName, array changes, string primaryKey, string attrChangesTableName, string userId, boolean ignoreError)

Uses a database table to record changes to a row of data and create an audit trail.

void

printServerDownError()

Echos a error message page explaining that there was a problem connecting to the database and to try back later.

resource

query(string sql, boolean ignoreError)

Executes an SQL query.

array

select(array assocArray, string tableName, string whereClause, boolean ignoreError)

Uses an associative array to select a row of data from a database table.

array

splitResultSet(mixed rs)

Retrieves separate columns of data from a result set.

resource

update(array assocArray, string tableName, string whereClause, boolean ignoreError)

Uses an associative array to update data in a database table.

Field Detail

public mixed $dbLink

A handle to the database connection.

Since:
FORMfields v3.0

dbName

public mixed $dbName

The database name.

Since:
FORMfields v3.0

host

public mixed $host

The database hostname or IP.

Since:
FORMfields v3.0

password

public mixed $password

The database username's password.

Since:
FORMfields v3.0

user

public mixed $user

The database username.

Since:
FORMfields v3.0

Method Detail

connect

public void connect(boolean ignoreError)

Attempts to connect to the database using a persistent connection and if this fails attempts using a non-persitent connection. After the connectio has been established the specified database is selected.

Parameters:
ignoreError - true if SQL error messages should be ignored and execution should remain uninterrupted. Defaulted to false.
Since:
FORMfields v3.0

delete

public resource delete(array assocArray, string tableName, boolean ignoreError)

Uses an associative array to delete data in a database table.

Parameters:
assocArray - an array of database attributes indexed by the attribute name
tableName - the database table where the data will be inserted
ignoreError - true if SQL error messages should be ignored and execution should remain uninterrupted. Defaulted to false.
Returns:
the resource associated with the insert query
Since:
FORMfields v3.0

getDbArray

public void getDbArray(array values)

Returns an array of database values processed with getDbValue().

Parameters:
values - array of values
Returns:
array of database values processed with getDbValue().
Since:
FORMfields v3.0

getDbValue

public string getDbValue(mixed value)

Escapes the string and then wraps it in single quotes value for easy use in an SQL query. Furthermore, if the field value is null then the database value will be "null" and not "'null'".

Returns:
the database value of the field wrapped in single quotes or "null"
Since:
FORMfields v1.0

getList

public array getList(string sql, boolean ignoreError)

Returns an array of values or a "column" or values from the database. For example, this method can be used with "SELECT username FROM users"

Parameters:
sql - an SQL query requesting a row of data
ignoreError - true if SQL error messages should be ignored and execution should remain uninterrupted. Defaulted to false.
Returns:
an array of strings
Since:
FORMfields v3.0

getRows

public array getRows(string sql, boolean ignoreError)

Returns an array of rows of data from the database. This method is useful for quickly grabbing a sizeable chunk of table data in an array, however it can be a waste if all the data is not going to be used. For better efficiency (data storage) you may want to use query(). For example, this method can be used with "SELECT username,first_name,last_name FROM users"

Parameters:
sql - an SQL query requesting a row of data
ignoreError - true if SQL error messages should be ignored and execution should remain uninterrupted. Defaulted to false.
Returns:
an array of rows where each row contains data indexed by the attribute name or SQL alias if specified in the query
Since:
FORMfields v3.0

getSelectClause

public string getSelectClause(mixed attrs, array an)

Returns the parameter section of the SQL select clause generated from an associative array.

Parameters:
an - associative array indexed by the attribute name and containing the alias values
Returns:
the parameter section of the SQL select clause generated from the associative array
Since:
FORMfields v3.0

getSimpleValue

public string getSimpleValue(string sql, boolean ignoreError)

Returns a single value of data from the database. For example, this method can be used with, "SELECT username FROM users WHERE id='1'"

Parameters:
sql - an SQL query requesting a single value of data
ignoreError - true if SQL error messages should be ignored and execution should remain uninterrupted. Defaulted to false.
Returns:
a single value of data from the database
Since:
FORMfields v3.0

getSimpleValues

public array getSimpleValues(string sql, boolean ignoreError)

Returns an array of values or a "row" of values from the database. For example, this method can be used with, "SELECT username,first_name,last_name FROM users WHERE id='1'"

Parameters:
sql - an SQL query requesting a row of data
ignoreError - true if SQL error messages should be ignored and execution should remain uninterrupted. Defaulted to false.
Returns:
an array of strings indexed by the attribute name or SQL alias if specified in the query
Since:
FORMfields v3.0

insert

public resource insert(array assocArray, string tableName, boolean ignoreError)

Uses an associative array to insert data in a database table.

Parameters:
assocArray - an array of database attributes indexed by the attribute name
tableName - the database table where the data will be inserted
ignoreError - true if SQL error messages should be ignored and execution should remain uninterrupted. Defaulted to false.
Returns:
the resource associated with the insert query
Since:
FORMfields v3.0

insertAttrChanges

public void insertAttrChanges(string tableName, array changes, string primaryKey, string attrChangesTableName, string userId, boolean ignoreError)

Uses a database table to record changes to a row of data and create an audit trail.

Parameters:
tableName - the database table where the data will be inserted
changes - an array of rows indexed by the attribute name where the 1st element in the row is the old value and the 2nd element is the new value
primaryKey - the primary key of tableName. Defaulted to "ff_id"
attrChangesTableName - the name of the table where to store the attribute changes. Defaulted to ff_attr_changes.
userId - the unique identifier of the user who made the changes or null if the user is not identified. Defaulted to null.
ignoreError - true if SQL error messages should be ignored and execution should remain uninterrupted. Defaulted to false.
Since:
FORMfields v3.0

printServerDownError

public void printServerDownError()

Echos a error message page explaining that there was a problem connecting to the database and to try back later.

Since:
FORMfields v3.0

query

public resource query(string sql, boolean ignoreError)

Executes an SQL query. If an error is detected and ignoreError is false, an error message page is echoed to the screen and script execution is halted. Note: This method automatically connects to the database when needed.

Parameters:
sql - an SQL query
ignoreError - true if SQL error messages should be ignored and execution should remain uninterrupted. Defaulted to false.
Returns:
the SQL result resource or result set
Since:
FORMfields v3.0

select

public array select(array assocArray, string tableName, string whereClause, boolean ignoreError)

Uses an associative array to select a row of data from a database table.

Parameters:
assocArray - an array of database attributes indexed by the attribute name
tableName - the database table where the data will be inserted
whereClause - an SQL where clause like, "WHERE id='1'"
ignoreError - true if SQL error messages should be ignored and execution should remain uninterrupted. Defaulted to false.
Returns:
an array of strings indexed by the attribute name or SQL alias if specified in the query
Since:
FORMfields v3.0

splitResultSet

public array splitResultSet(mixed rs)

Retrieves separate columns of data from a result set. For example, when applying this method to the result set returned from "SELECT username,users FROM users", this method will return username and users arrays with corresponding indices.

Returns:
a result set created by executing a query
an array of 2 elements. The 1st element is an array of the 1st column of data and the 2nd element is an array of the 2nd column of data.
Since:
FORMfields v3.0

update

public resource update(array assocArray, string tableName, string whereClause, boolean ignoreError)

Uses an associative array to update data in a database table.

Parameters:
assocArray - an array of database attributes indexed by the attribute name
tableName - the database table where the data will be inserted
whereClause - an SQL where clause like, "WHERE id='1'"
ignoreError - true if SQL error messages should be ignored and execution should remain uninterrupted. Defaulted to false.
Returns:
the resource associated with the update query
Since:
FORMfields v3.0

FORMfields