>> YANA 4 PHP Framework >> Docs For Class DbStream

Class DbStream

Description

database API

this class is a database abstraction api, that uses pear db

  • access: public

Located in /includes/class_dbstream.php

Object
   |
   --DbStream
Method Summary
  • DbStream DbStream ([string|StructureFile $file = ""], [dbServer $server = null])
  • string equals (object $anotherObject)
  • bool exists ([string $key = ""])
  • bool exportStructure (string $filename)
  • mixed get (array|string $key, [array|string $where = array()], [array $order_by = array()], int $offset, int $limit, [bool $desc = false])
  • string getTable ()
  • bool importSQL (string|array $sqlFile)
  • bool insert (string $key, mixed $value)
  • bool isEmpty ([string $table = ""])
  • bool isWriteable ()
  • bool join (string $table1, [string $table2 = null], [string $key1 = null], [string $key2 = null])
  • int length ([string $table = ""], [string|array $search = array()])
  • mixed query (string $sqlStmt, int $offset, int $limit)
  • bool remove (string $key, [ $in_where = array()], string|array $where)
  • void reset ()
  • string toString ([string $table = ""])
  • bool write ()
  • void _checkProfile ( $queryType,  $returnedType,  &$where,  &$value,  $table, [ $row = ""], [ $column = ""])

Direct descendents

Class Description
BufferedDbStream Alias of DbStream (deprecated)
FileDb simulate a database

Methods

create a new instance
DbStream DbStream (
[string|StructureFile $file = ""], [dbServer $server = null]
)
List of parameters:
Name Type Description
$file string|StructureFile
$server dbServer
Description:

Each database connection depends on a structure file describing the database. Therefore you have to provide a $filename of such structure file (without path or extension)

These files are to be found in config/db/*.config

Since version 2.8.7 the argument $file can also be an instance of class StructureFile.

compare with another object
string equals (
object $anotherObject
)
List of parameters:
Name Type Description
$anotherObject object
Description:

Returns bool(true) if this object and $anotherObject are equal and bool(false) otherwise.

Two instances are considered equal if and only if they are both objects of the same class and they both refer to the same structure file and use equal database connections.

  • access: public

Redefinition of: Object::equals()

Check wether a certain key exists
bool exists (
[string $key = ""]
)
List of parameters:
Name Type Description
$key string adress to check
Description:

Returns bool(true), if the adress $key (table, row, column) is defined, and otherwise bool(false). If no argument is provided, the function returns bool(true) if a database connection exists and bool(false) if not.

  • access: public
  • uses: $DbStream->exists('table.5')
export database structure to a file
bool exportStructure (
string $filename
)
List of parameters:
Name Type Description
$filename string relative path to output-file
Description:

Note: if the specified file already exists it will get overwritten.

Structure files need to have the extension '.config' and are to be stored at the directory 'config/db/*.config'.

  • access: public
  • uses: $DbStream->exportStructure('some_file.config')
get values from the database
mixed get (
array|string $key, [array|string $where = array()], [array $order_by = array()], int $offset, int $limit, [bool $desc = false]
)
List of parameters:
Name Type Description
$key array|string the address of the value(s) to retrieve
$where array|string a search string
$order_by array a list of columns to order the resultset by
$offset int the number of the first result to be returned
$limit int maximum number of results to return
$desc bool if true results will be ordered in descending, otherwise in ascending order
Description:

This returns the values at adress $key starting from $offset and limited to $limit results.

The $key parameter has two synopsis.

  • If $key is a string, this parameter is interpreted as the address of the values you want to retrieve.
  • If $key is an associative array, it overwrites any of the paramters you provide, without the need to enter default parameters - this might come in handy in certain situations.

The array $key can have the following values

  • $key = the address of the value(s) to retrieve (mandatory)
  • $where = a search string (optional)
  • $search = alias of $where (deprecated)
  • $order_by = array of columns to order the resultset by (optional)
  • $desc = boolean, if true results will be ordered in descending, otherwise in ascending order (optional)
  • $offset = integer, the number of the first result to be returned (optional)
  • $limit = integer, maximum number of results to return (optional)

Since version 2.8.5 the parameter $order_by has two synopsis.

  • $order_by is the name of the column in the current table to order the resultset by.
  • $order_by is a numeric array of strings, where each element is the name of a column in the current table. The resultset will get ordered by the values of these columns in the direction in which they are provided. This feature became available in version 2.8.5

Since version 2.8.5 the parameter $where has two synopsis.

  • $where is a comma seperated list of column-value pairs using the following syntax:
    column1=value1,column2=value2,...,columnN=valueN
    Note that comparison takes place using the SQL operator 'LIKE', except for columns that are keys (either a primary key or a foreign key), which are compared using the SQL operator '='.
  • $where is a two-dimensional numeric array and its entries follow this syntax:
    array(array(0=>column1,1=>value1,2=>operator1),...)
    The "column" name is mandatory and needs to be a string. The "value" is mandatory and needs to be a scalar value. The "operator" is optional and defaults to 'LIKE'. It needs to be a string and can be one of the following:
     '=', 'LIKE', '<', '>', '!=', '<=', '>=', '==' (alias of '=')
The second alternative offers more flexibility and should be prefered over the first one.

Note: The $desc parameter became available in version 2.8.5

  • access: public
get the most recently queried table
string getTable ()
Description:
  • access: public
import SQL from a file
bool importSQL (
string|array $sqlFile
)
List of parameters:
Name Type Description
$sqlFile string|array
Description:

The input parameter $sqlFile can wether be filename, or a numeric array of SQL statements.

Returns bool(true) on success or bool(false) on error. Note that the statements are executed within a transaction. If the function fails,

An error is encountered and an E_USER_NOTICE is issued, if:

  • the file does not exist or is not readable
  • the $sqlFile parameter is empty
  • the database connection is not available
  • the parameter "readonly" on the database structure file is set to "true"
  • at least one database statement failed (does not issue an E_USER_NOTICE)
  • there are uncommited statements in the queue

  • name: DbStream::importsql()
  • access: public
  • uses: $DbStream->importSQL('some_file.sql')
update or insert row
bool insert (
string $key, mixed $value
)
List of parameters:
Name Type Description
$key string
$value mixed
Description:

insert $value at position $key

If $key already exists, the previous value gets updated, else the value is created

This function returns bool(true) on success and bool(false) on error. Note, that this function does not auto-commit. This means, changes to the database will NOT be saved unless you call $DbStream->write().

  • access: public
check wether a certain table has no entries
bool isEmpty (
[string $table = ""]
)
List of parameters:
Name Type Description
$table string name of a table
Description:

Note: if no table is provided, the most recently used table will be tested instead.

  • access: public
check wether the current database is readonly
bool isWriteable ()
Description:
  • access: public
  • uses: $DbStream->isWriteable()
join the resultsets for two tables
bool join (
string $table1, [string $table2 = null], [string $key1 = null], [string $key2 = null]
)
List of parameters:
Name Type Description
$table1 string name of the table to join another one with
$table2 string name of another table to join table1 with (when omitted will remove all previously set joins from table1)
$key1 string name of the foreign key in table1 that references table2 (when omitted the API will look up the key in the structure file)
$key2 string name of the key in table2 that is referenced from table1 (may be omitted if it is the primary key)
Description:

Results in an INNER JOIN $table1, $table2 WHERE $table1.$key1 = $table2.$key2 .

Note that if you ommit the parameters $key1 and $key2, the API will try to determine the foreign key and target key itself by looking up the foreign key in the database's structure file. The first foreign key association that matches will be used.

Also note that two tables may only be joined via one pair of columns - not two or more. Instead if you may add additional rules to the where clause as you see fit.

Note that joins are permanent. So in opposition to what you might have learned from common SQL statements and other APIs, you do not need to repeat joins for each query. Instead, this API "remembers" what it was told and once set your joins will automatically be used each time you query the table until you explicitly remove it.

To remove all perviously set joins from a table, use the following function call:

  1.  $dbStream->join('myTable');
As you can see above, if the second argument ($table2) is ommited, all joins bound to 'myTable' are released.

Also note, that the wildcard '*' may be used to refer to the "least recently used" table. This is a shortcut that you may use in your scripts.

  • access: public
get the number of entries inside a table
int length (
[string $table = ""], [string|array $search = array()]
)
List of parameters:
Name Type Description
$table string name of a table
$search string|array optional where clause
Description:
  • access: public
optional API bypass
mixed query (
string $sqlStmt, int $offset, int $limit
)
List of parameters:
Name Type Description
$sqlStmt string one SQL statement to execute
$offset int the row to start from
$limit int the maximum numbers of rows in the resultset
Description:

Send a sql-statement directly to the PEAR database API, bypassing this API.

Note: for security reasons this only sends one single SQL statement at a time. This is done by checking the input for a semicolon followed by anything but whitespace. If such input is found, an E_USER_WARNING is issued and the function will return bool(false).

While bypassing the API leaves nearly all of the input checking to you, this is meant to prevent at least a minimum of the common SQL injection attacks. A known attack is to try to terminate a current statement with ';' and afterwards "inject" their own stuff as a second statement. The common attack vector usually is unchecked form data.

If you want to send a sequence of statements, call this function multiple times.

The function will return bool(false) if the database connection or the PEAR API is not available and otherwise will whatever PEAR sends back as the result of your statement.

Note: when database usage is disabled via the administrator's menu, the PEAR-DB API can not be used and this function will return bool(false).

The $offset and $limit arguments became available in version 2.8.8

  • access: public
remove one row
bool remove (
string $key, [ $in_where = array()], string|array $where
)
List of parameters:
Name Type Description
$key string the address of the row that should be removed
$where string|array a search string
$in_where
Description:

For security reasons all delete queries will automatically be limited to 1 row at a time. While this might be seen as a limitation the far more valueable advantage is, no user is able to destroy a whole table - wether by intention or by accident - in only one query. (At least not via this API.)

The function returns bool(true) on success and bool(false) on error.

Since version 2.8.5 the parameter $where has two synopsis.

  • $where is a comma seperated list of column-value pairs using the following syntax:
    column1=value1,column2=value2,...,columnN=valueN
    Note that comparison takes place using the SQL operator 'LIKE', except for columns that are keys (either a primary key or a foreign key), which are compared using the SQL operator '='.
  • $where is a two-dimensional numeric array and its entries follow this syntax:
    array(array(0=>column1,1=>value1,2=>operator1),...)
    The "column" name is mandatory and needs to be a string. The "value" is mandatory and needs to be a scalar value. The "operator" is optional and defaults to 'LIKE'. It needs to be a string and can be one of the following:
     '=', 'LIKE', '<', '>', '!=', '<=', '>=', '==' (alias of '=')
The second alternative offers more flexibility and should be prefered over the first one.

  • access: public
Reset the object to default values
void reset ()
Description:

Resets the history for the last selected table, resets the queue of pending SQL statements and resets the database cache.

  • access: public
get CSV string from a table
string toString (
[string $table = ""]
)
List of parameters:
Name Type Description
$table string name of a table
Description:
  • access: public
  • uses: $DbStream->toString('guestbook')

Redefinition of: Object::toString()

Commit current transaction
bool write ()
Description:

This writes all changes to the database

  • access: public
void _checkProfile (
 $queryType,  $returnedType,  &$where,  &$value,  $table, [ $row = ""], [ $column = ""]
)
List of parameters:
Name Type Description
$queryType
$returnedType
&$where
&$value
$table
$row
$column
Description:
inherited from base classes

Inherited From Object

Documentation generated on Sun, 11 Mar 2007 15:02:28 +0100 by phpDocumentor 1.3.1

yana author: Thomas MeyerHomepage: www.yanaframework.net