YANA 4 PHP Framework
Docs For Class DbStream
database API
this class is a database abstraction api, that uses pear db
Located in /includes/class_dbstream.php
Object | --DbStream
Class | Description |
---|---|
BufferedDbStream | Alias of DbStream (deprecated) |
FileDb | simulate a database |
Name | Type | Description |
---|---|---|
$file | string|StructureFile | |
$server | dbServer |
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.
Name | Type | Description |
---|---|---|
$anotherObject | object |
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.
Redefinition of: Object::equals()
Name | Type | Description |
---|---|---|
$key | string | adress to check |
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.
Name | Type | Description |
---|---|---|
$filename | string | relative path to output-file |
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'.
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 |
This returns the values at adress $key starting from $offset and limited to $limit results.
The $key parameter has two synopsis.
The array $key can have the following values
Since version 2.8.5 the parameter $order_by has two synopsis.
Since version 2.8.5 the parameter $where has two synopsis.
column1=value1,column2=value2,...,columnN=valueNNote 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 '='.
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 '=')
Note: The $desc parameter became available in version 2.8.5
Name | Type | Description |
---|---|---|
$sqlFile | string|array |
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:
Name | Type | Description |
---|---|---|
$key | string | |
$value | mixed |
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().
Name | Type | Description |
---|---|---|
$table | string | name of a table |
Note: if no table is provided, the most recently used table will be tested instead.
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) |
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:
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.
Name | Type | Description |
---|---|---|
$table | string | name of a table |
$search | string|array | optional where clause |
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 |
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
Name | Type | Description |
---|---|---|
$key | string | the address of the row that should be removed |
$where | string|array | a search string |
$in_where |
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.
column1=value1,column2=value2,...,columnN=valueNNote 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 '='.
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 '=')
Resets the history for the last selected table, resets the queue of pending SQL statements and resets the database cache.
Name | Type | Description |
---|---|---|
$table | string | name of a table |
Redefinition of: Object::toString()
This writes all changes to the database
Name | Type | Description |
---|---|---|
$queryType | ||
$returnedType | ||
&$where | ||
&$value | ||
$table | ||
$row | ||
$column |
Inherited From Object
Documentation generated on Sun, 11 Mar 2007 15:02:28 +0100 by phpDocumentor 1.3.1