Login   Register  
PHP Classes
elePHPant
Icontem

File: readme_en.txt

Recommend this page to a friend!
Stumble It! Stumble It! Bookmark in del.icio.us Bookmark in del.icio.us
  Classes of Johan Barbier  >  aDB PDO like database abstraction  >  readme_en.txt  >  Download  
File: readme_en.txt
Role: Documentation
Content type: text/plain
Description: English doc
Class: aDB PDO like database abstraction
Database abstraction layer similar to PDO
Author: By
Last change: Added new methods
Date: 7 years ago
Size: 6,783 bytes
 

Contents

Class file image Download
aDB PACKAGE 
@version 20070524

THis package is a DB abstraction package.

It is built with following classes :

/**
* Exceptions management
*/
class aDBException extends Exception
class aDBExceptionIllegalClass extends aDBException 
class aDBExceptionTypesError extends aDBException
class aDBExceptionInvalidClassCalls extends aDBException
class aDBExceptionDbConnectorErrors extends aDBException

/**
* Iterator
*/
class sqlIterator implements Iterator, SeekableIterator, Countable

/**
* Factory
*/
class aDBFactory

/**
* DB abstraction
*/
abstract class aDB
class mssql extends aDB
class mysql extends aDB

This package allows you to switch easily from one db server to another one, from a db connection to another one, keeping the minimum 
objects necessary, with its factory.
It allows a strong errors management thanks to several exception types.
Its methods let you, in addition to usual db classes functionnalities, manage transactions, queries preparation, queries results sets 
limitation... 

Have a look at the code to read a complete documentatio about these methods and properties.
This doc is only here to teach you how to use the package.
Some complex samples can be found in the index.php file.


/************
INSTANCIATION

$aDB = aDBFactory::getInstance (string $type, [array $aConfConf, [array $aOptions]]);

If we already have an instance of $type, the factory will check its configuration and options.
If there is a new configuration or new options, the factory re-connects / "re_options" the existing instance, then return it.
If not, it just returns it.
If there is no such instance, it build one and returns it.
An exception will be thrown (aDBExceptionIllegalClass) if no class of $type type is found.


/**********
UTILISATION

USEFUL METHODS :

aDB::connect ($aConConf)
Needs an array of parametrers for connection with keys HOST, LOGIn, PWD and DB in option.
Connects the objetc to the server.
A connection link is then returned.


aDB::select_db ([$sDbName = null])
Selects $sDbName DB if given, aDB::aConConf['DB'] if not.


aDB::query ($sQuery, [$bOverWriteQry = true])
Execute $sQuery query.
If $bOverWriteQry is true, then private property aDB::sQuery is overwritten by $sQuery.
Created resource is returned.


aDB::set_limit ([$iOffset = 0, [$iCount = null]])
Initialize a limitation for result sets.
$iOffset is the starting position.
$iCount is the number of rows to return.
Note that these parameters are kept by the class; so if you want to cancel them, you must call this method without any parameter.


aDB::next_limit ()
Update limitation previously initialized with aDB::set_limit.
Number or rows to retrieve remains the same.
But starting offset is equal to previous starting offset + number of rows to retrieve.


aDB::fetch ([$aDB_MODE = aDB::BOTH, [$rQry = null, [$bIsSeekable = true]]])
Gets result sets row after row.
If $rQry is null, internal query resource is used.
Returned value is an sqlIterator.
This iterator can have different structures according to the mode $aDB_MODE.
Default mode is aDB::BOTH.
See properties description.
You can loop through the results these ways : 
foreach ($iterator as $val) {
	print_r ($val);
}
Or
$it -> next ();
while ($it -> valid()) {
	print_r ($it -> current ());
	$it -> next ();
}
See sqlIterator code for a more complex use of this class if needed.


aDB::fetchColumn ([$iColumn = 0, [$rQry = null, [$bIsSeekable = true]]])
Gets the value of a column wihch position is specified by $iColumn.


aDB::fetchAll ([$aDB_MODE = aDB::BOTH, [$rQry = null, [$bIsSeekable = true]]])
Gets all the result sets and returns an array.
The structure of the array depends on $aDB_MODE.
default mode is aDB::BOTH.


aDB::count ($rQry = null)
Returns an integer being the total number of rows the query should return (limitation aDB::set_limit() does not apply here).


aDB::prepare ($sQuery)
Prepare a query. 


aDB::bindValue ($sNeedle, $mValue, [$cType = null])
A query must have been prepared first.
Gets $sNeedle in the query, and replaces it by $mValue, according to $cType if given (or type of $mvalue if not).
Ne peut fonctionner que si une requête a été préparée via aDB::prepare ().
$cType must be an aDB parameter such as aDB::PARAM_INT.
Exemple :
If $sQuery = 'SELECT * FROM table WHERE id= :iID'
and :
$aDB -> prepare ($sQuery);
$aDB -> bindValue (':iID', 10, aDB::PARAM_INT);
then $sQuery === 'SELECT * FROM table WHERE id= 10'


aDB::execute ()
Executes a pre^pared query.


aDB::escape ($sString)
Escapes dangerous characters in $sString.
Returns $sString.


aDB::startTransaction ()
Starts a transaction.


aDB::commitTransaction ()
Commits a transaction.


aDB::rollbackTransaction ()
Rolls a transaction back.

aDB::savePoint ($sSavePoint)
Creates a savepoint $sSavePoint.


aDB::rollbackToSavePoint ($sSavePoint)
Rolls back to the savepoint $sSavePoint.


aDB::releaseSavePoint ($sSavePoint)
Releases the savepoint $sSavePoint.


aDB::lastInsertId ()
Returns last inserted ID.


aDB::server_info ([$$rLink = null])
returns availaible db server infos.


aDB::setOption ($sOption, $mValue)
Sets the option $sOption to the value $mValue.


USEFUL PROPERTIES :

**Getable properties : 

aDB::QUERY:
Returns current query.
echo $aDB -> QUERY;


aDB::ERRORS
Returns errors array if the option EXCEPTION_ON_ERROR is unactive.


aDB::LAST_ERROR:
Returns the last error if the option EXCEPTION_ON_ERROR is unactive.


**Options :

AUTOCONNECT:
If true, the object connects to the db in its constructor.
Default value is true.


EXCEPTION_ON_ERROR:
If true, Exception are thrown on errors.
If false, errors are logged in an array.
Default value is true.


**Constants :
FETCH Modes :

aDB::BOTH = 0;
results set returned is structured as an array indexed both numerically and associatively.

aDB::FETCH_ASSOC = 1;
results set returned is structured as an array indexed associatively.


aDB::FETCH_NUM = 2;
results set returned is structured as an array indexed numerically.


aDB::FETCH_GROUP = 4;
Results set is structure as an array like :
array (valeur_colonne_0 => array (valeurs_autres_colonnes)) 
indexes depends on associated mode :
aDB::BOTH, aDB::FETCH_NUM, aDB::FETCH_ASSOC.
If no association, default mode is aDB::BOTH


aDB::FETCH_EXTRACT = 8;
Results set is returned in variables with names like columns.
Exemple :
SELECT user_id, user_nom FROM users
returns values in $user_id et $user_nom, for each loop.
Can only be used with aDB::fetch().


aDB::bindValue() types :
aDB::PARAM_STR = 1000;
String


aDB::PARAM_INT = 1001;
Integer