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

Class BufferedDbStream

Description

database API

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

  • access: public

Located in /includes/class_buffereddbstream.php

Object
   |
   --BufferedDbStream
Method Summary
  • BufferedDbStream BufferedDbStream ([string $filename = ""], [dbServer $server = null])
  • string equals (object $another_object)
  • bool exists ([string $key = ""])
  • boolean 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 $sqlFile)
  • boolean insert (string $key, mixed $value)
  • boolean isEmpty ([string $table = ""])
  • bool isWriteable ()
  • boolean join (string $table1, [string $table2 = ""], [string $key1 = ""], [string $key2 = ""])
  • int length ([string $table = ""], [string|array $search = array()])
  • mixed query (string $sqlStmt)
  • bool remove (string $key, [ $in_where = array()], string|array $where)
  • void reset ()
  • string toString ([string $table = ""])
  • boolean write ()

Direct descendents

Class Description
FileDb simulate a database

Methods

create a new instance
BufferedDbStream BufferedDbStream (
[string $filename = ""], [dbServer $server = null]
)
List of parameters:
Name Type Description
$filename string
$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

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

Returns bool(true) if this object and $another_object 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: $BufferedDbStream->exists('table.5')
export database structure to a file
boolean exportStructure (
string $filename
)
List of parameters:
Name Type Description
$filename string
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: $BufferedDbStream->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 $sqlFile
)
List of parameters:
Name Type Description
$sqlFile string
Description:
  • name: BufferedDbStream::importsql()
  • access: public
  • uses: $BufferedDbStream->importSQL('some_file.sql')
update or insert row
boolean 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 $BufferedDbStream->write().

  • access: public
check wether a certain table has no entries
boolean isEmpty (
[string $table = ""]
)
List of parameters:
Name Type Description
$table string (optional)
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: $BufferedDbStream->isWriteable()
join the resultsets for two tables
boolean join (
string $table1, [string $table2 = ""], [string $key1 = ""], [string $key2 = ""]
)
List of parameters:
Name Type Description
$table1 string
$table2 string (optional)
$key1 string (optional)
$key2 string (optional)
Description:

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

  • 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 (optional)
$search string|array (optional)
Description:
  • access: public
optional API bypass
mixed query (
string $sqlStmt
)
List of parameters:
Name Type Description
$sqlStmt string the SQL statement to execute
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).

  • 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 (optional)
Description:
  • access: public
  • uses: $BufferedDbStream->toString('guestbook')

Redefinition of: Object::toString()

Commit current transaction
boolean write ()
Description:

This writes all changes to the database

  • access: public
inherited from base classes

Inherited From Object

Documentation generated on Wed, 22 Nov 2006 20:19:00 +0100 by phpDocumentor 1.3.1

yana author: Thomas MeyerHomepage: www.all-community.de/pub