Why use it? Examples Downloads Manual Plug-ins Other tools Support Forum Testimonials Your sites
Français 
Skrol29, 2009-12-08

TbsSQL 2.6

 

TbsSQL is a PHP class for SQL abstraction.
The goal of this tool is to reduce the code when working with SQL through PHP.
The TbsSQL is available for the following databases:
- MySQL
- MySQLi
- SQL-Server (via Ms ODBC or UnixODBC)
- PostgreSQL (version 7.2 or higher)
- ODBC Generic (available since TbsSQL version 2.6)


• Coding
The main asset of TbsSQL is the habitably to merge in the SQL statement a variable number of arguments and protect them against Sql Injection.

Example:
$id = 29;
$name = "boby";
$Db->Execute('UPDATE table1 SET name=@2@ WHERE (id=%1%)', $id, $name);

In this example, the SQL statement sent to the database will be: UPDATE table1 SET name='boby' WHERE (id=29)

TbsSQL supports the following jokers in your SQL statements:
    (n must be the number of the place of the argument in the TbsSQL command)
- %n% The argument will be protected against Sql Injection. Example: %1%
- @n@ The argument will be protected against Sql Injection and delimited as a string value with the relevant format for the database. Example: @1@
- #n# The argument will be converted as a date value without time with the relevant format for the database. Example: #1#
- ~n~ The argument will be converted as a date and time value with the relevant format for the database. Example: ~1~

Managing NULL values:
You can also use jokers %[n]% , @[n]@ , #[n]# and ~[n]~ to replace the value by the SQL keyword 'NULL' when the value to merge is the PHP value {false} or {null}. Please note that empty string {''} will not be replaced with the SQL keyword 'NULL'.
Example:
$id = 29;
$date = false;
$Db->Execute('UPDATE table1 SET fd=[#2#] WHERE (id=%1%)', $id, $date);

In this example, the SQL statement sent to the database will be: UPDATE table1 SET fd=NULL WHERE (id=29)
Versioning: Jokers for nullable values are supported since TbsSQL version 2.5.

• Hook
TbsSQL is compatible with the TinyButStrong Template Engine.
Use the property $Db->TbsKey in order to have the MergeBlock() method using your TbsSQL instance.
Example : $TBS->MergeBlock('b',$Db->TbsKey,'SELECT * FROM table1');
Versioning: before version 2.5, property $Db->TbsKey doesn't exist and the TBS key is the same for all TbsSQL instance. You must use the keyword 'tbssql' instead of $Db->TbsKey.

• License
TbsSQL is a free and open source. It is published under the LGPL license.

• Synopsis
$Db = new clsTbsSQL($srv='',$uid='',$pwd='',$db='',$drv='',$mode=TBSSQL_NORMAL); Instantiates the class. Giving connection information is optional.
Versioning: optional argument $mode is supported since TbsSQL version 2.6.
$Db->Connect($srv,$uid,$pwd,$db,$drv='',$mode=TBSSQL_NORMAL)
  or
$Db->Connect('glob_var');

Arguments:
$srv: server (or connection string for some database type)
$uid: user id
$db: database name
$drv: driver (optional, needed for some database type)
$mode: TbsSQL warning mode (see property Mode)
Open a connection to the database.
Syntax 1 example:
$Db->Connect('localhost','root','xxx','db_prod');
The argument $drv is needed only for some Dabase Systems.
Syntax 2 example:
$glob_var = array('srv'=>'localhost','uid'=>'root','pwd'=>'xxx','db'=>'db_prod');
$Db->Connect('glob_var');

'glob_var' must be the name of a global variable beeing a PHP array with the keys described above.
The global variable is destroyed just after the connection.
Versioning: syntax2 is available since TbsSQL version 2.0. Optional argument $mode is supported since TbsSQL version 2.6.
Note: You don't need to call this method if your connection has already been opened before. In this case, you just have to assign the connection id to property ->Id. (example: $Db->Id = $mycn). You don't have to do this assignation when PHP can work automatically with the last opened connection. This is the case for MySQL for example.
ODBC: (and SQL server with ODBC)
Argument $srv can be a server name, or a connection string. You can define a DSN (Data Source Name) using the connection string: 'DSN=my_dsn'.
Examples:
$srv = 'my_server';
$srv = 'DSN=my_dsn'
$srv = 'DRIVER={SQL Server};SERVER=my_server'
$srv = 'Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\mydatabase.mdb;'
Note: the FreeTDS UnixOdbc driver for MsSQL seems to ignore arguments user and password given to function odbc_connect(). Therefore, you must defines parameter UID and PWD in a connection string.
$Db->Close() Close the current connection to the database.
$Db->Execute($sql,...*...) Execute the Sql statement.
$Db->GetVal($sql,...*...) Returns the value of the first column in the first record of the query.
If no record is returned by the query, then the function returns False.
$Db->GetRow($sql,...*...) Returns an associative PHP array which is the first record returned by the query.
$Db->GetRows($sql,...*...) Returns a PHP array of all records returned by the query.
$Db->GetList($sql,...*...) Returns a PHP array with first column as keys and second column as values. If only one columns is given by the query then they the values of the array.
Example: $Db->GetList('SELECT id,name FROM t_people');
will return something like: array(1=>'Peter', 2=>'Dave', 3=>'Jane' ,...)
$Db->GetSql($sql,...*...) Returns the SQL statement with merged arguments.
$Db->LastRowId() Returns the value of the identifier generated by the last INSERT query of your connection.
Note: This method is not available for ODBC Generic.
$Db->AffectedRows() Returns the number of rows affected by the last UPDATE or DELETE query of your connection.
Note: This method is not available for ODBC Generic.
$Db->Id (read/write) The resource Id of your connection.
$Db->Mode (read/write) default value is TBSSQL_NORMAL.
TBSSQL_SILENT: silent mode, no database error message is displayed.
TBSSQL_NORMAL: normal mode, the database error message is displayed when an error occurs.
TBSSQL_DEBUG: debug mode, the full SQL statement is also recalled when an error occurs.
TBSSQL_TRACE: trace mode, all queries are displayed.
Versioning: the constants TBSSQL_* are supported since TbsSQL version 2.5
$Db->TbsKey (read) Return the TinyButStrong key string for the current connection (see chapter Hook above). This property has always a default value which is unique for each new instance.
Most of the time there is no need know the value of this property, since you can use the property directly with TBS.
Example: $TBS->MergeBlock('b',$Db->TbsKey,'SELECT * FROM table1');
Versioning: this property is available since TbsSQL version 2.5
$Db->SetTbsKey($key) Change the value of property $Db->TbsKey. Most of the time, there is no need to use this method because property TbsKey has always a default value which is unique. Use this method only if your application do need a customized key value for the TinyButStrong merging.
Example:
$Db->SetTbsKey('myconnection');
$TBS->MergeBlock('b', 'myconnection', 'SELECT * FROM table1');
Versioning: this method is available since TbsSQL version 2.5
   
...*... means a variable number of arguments that will be merged in the SQL statement.

• Deprecated
$Db->Row1($sql,...*...) Same as $Db->GetRow()
$Db->Rows($sql,...*...) Same as $Db->GetRows()
$Db->Value($default,$sql,...*...) Same as $Db->GetVal() but with a default value.