yana

Description
  Class trees
  Index of elements
  Todo List
core
  Classes
    FormCreator
    Index
    Language
    Object
    Plugin
    PluginManager
    Singleton
    SmartTemplate
    SmartView
    Utility
    Yana
database
  Classes
    DbBlob
    DbCreator
    DbDesigner4
    DbExtractor
    DbQuery
    DbQueryParser
    DbServer
    DbStream
    DbStructure
    FileDb
error_reporting
  Classes
    Alert
    Error
    ErrorUtility
    Log
    Message
    Report
    Warning
file_system
  Classes
    DatFile
    Dir
    Executeable
    File
    FileReadonly
    FileSystemResource
    SML
javascript
  Classes
    AjaxRequest
  Functions
    preview
    yanaAddEventListener
    yanaAddIcon
    yanaCheckEmbTags
    yanaCloseAll
    yanaGetCookie
    yanaGetElementsByClassName
    yanaMaxLength
    yanaMenu
    yanaMenuCookie
    yanaSetCookie
mail
  Classes
    FormMailer
    Mailer
plugins
  Classes
    plugin_blog
    plugin_check
    plugin_db_admin
    plugin_db_tools
    plugin_default_library
    plugin_diagnostics
    plugin_guestbook
    plugin_guestbook_admin
    plugin_ipblock
    plugin_ipblock_admin
    plugin_rss
    plugin_rss_admin
    plugin_sdk
    plugin_search
    plugin_search_admin
    plugin_user
    plugin_user_admin
utilities
  Classes
    Brush
    Counter
    Hashtable
    Image
    Microsummary
    RSS
    RSSitem
    String
  Functions
    checkArgumentList
    cloneArray
    dirlist
    qSearchArray
    untaintInput
    XMLencode
vdrive
  Classes
    Registry
    VDrive
zip
  Classes
    PclZip

phpDocumentor v 1.4.0

YANA Framework for PHPDocs For Class DbStream

### Class DbStream

#### Description

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

- access: public

    Object
       |
       --DbStream

##### Variable Summary

DbStructure $structure

##### Method Summary

- DbStream DbStream ([string|DbStructure $file = null], [dbServer $server = null])
- bool commit ()
- string equals (object $anotherObject)
- bool exists ([string|DbQuery $key = ""])
- bool exportStructure (string $filename)
- mixed get (array|string|DbQuery $key, [array|string $where = array()], [array $orderBy = array()], int $offset, int $limit, [bool $desc = false])
- array getDsn ()
- string getErrorMessage ()
- string getTable ()
- array getTableInfo (string $table)
- bool importSQL (string|array $sqlFile)
- bool insert (string|DbQuery $key, [mixed $value = array()])
- bool insertOrUpdate (string|DbQuery $key, [mixed $value = array()])
- bool isEmpty ([string $table = ""])
- bool isWriteable ()
- bool join (string $table1, [string $table2 = null], [string $key1 = null], [string $key2 = null])
- int length ([string|DbQuery $table = ""], [string|array $search = array()])
- mixed query (string|DbQuery $sqlStmt, int $offset, int $limit)
- bool remove (string|DbQuery $key, [string|array $where = array()])
- void reset ()
- void rollback ()
- string toString ([string $table = ""])
- bool update (string|DbQuery $key, [mixed $value = array()])
- bool write ()

#### Direct descendents

Class | Description
--- | ---
FileDb | simulate a database

#### Variables

##### DbStructure $structure = null

structure of current database
This gives you access to the db-schema that is used in the current session.
Please note that you should not change this schema unless you REALLY know what you are doing.

- access: public

#### Methods

##### create a new instance

DbStream DbStream (
[string|DbStructure $file = null], [dbServer $server = null]
)

###### List of parameters:

Name | Type | Description
--- | --- | ---
$file | string|DbStructure |
$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 DbStructure.

##### Alias of DbStream::write()

bool commit ()

###### Description:

- see: DbStream::write()
- access: public

##### 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|DbQuery $key = ""]
)

###### List of parameters:

Name | Type | Description
--- | --- | ---
$key | string|DbQuery | 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.
Since version 2.9.3 you may also provide the parameter $key as an object of type DbQuery.

- 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|DbQuery $key, [array|string $where = array()], [array $orderBy = array()], int $offset, int $limit, [bool $desc = false]
)

###### List of parameters:

Name | Type | Description
--- | --- | ---
$key | array|string|DbQuery | the address of the value(s) to retrieve
$where | array|string | a search string
$orderBy | 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 three 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.
- Since version 2.9.3 the argument $key may also be an object of type $dbQuery. If so, no additional parameters need to be present. This is a shortcut, which e.g. allows you to prepare a query as an object and reuse it with multiple arguments.

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 $orderBy has two synopsis.

- $orderBy is the name of the column in the current table to order the resultset by.
- $orderBy 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 DSN

array getDsn ()

###### Description:

This function returns an associative array containing information on the current connection or bool(false) on error.
See DbServer::getDsn() for more details.

- since: 2.9.8
- access: public
- name: DbStream::getDsn()

##### get last reported error message

string getErrorMessage ()

###### Description:

Returns the last report error string or bool(false) if there is none.

- since: 2.9.8
- access: public

##### get the most recently queried table

string getTable ()

###### Description:

- access: public

##### get table information

array getTableInfo (
string $table
)

###### List of parameters:

Name | Type | Description
--- | --- | ---
$table | string | name of table

###### Description:

This function returns detailed information on a table and it's columns.
It returns an associative array containing the following keys:

- primarykey: Name of primary key column
- foreignkeys: Array, listing all foreign keys (MySQL only), with the following values:
  - column: Name of column in this table
  - foreigntable: Name of referenced foreign table
  - foreigncolumn: Name of referenced column in foreign table
- length: Number of columns in current table
- The columns are arrays, numbered 0 through N, with each of them having the following values:
  - table: Name of current table
  - name: Name of column
  - type: Data type of column
  - length: Maximum length
  - nullable: True, when the column may contain NULL as value, false otherwise
  - primarykey: True, when the column is the primary key, false otherwise
  - foreignkey: True, when the column is a foreign key, false otherwise
  - references: If column is a foreign key, this is a numeric array with the following values:
    - table: name of referenced foreign table
    - column: name of referenced column in foreign table
  - unique: True, when the column must not contain duplicate values, false otherwise
  - index: True, when there is an index on this column, false otherwise (MySQL only)
  - auto: True, when the column uses auto increment or auto number, false otherwise
  - default: Default value of this column, or NULL if there is none (MySQL only)
  - unsigned: True, when the column is an unsigned number type, false otherwise
  - zerofill: True, when the column has the zerofill flag set, false otherwise
  - comment: The comment on this column, or NULL if there is none (MySQL only)
  - select: True, if SELECT statements are allowed on this column and false otherwise (MySQL only)
  - update: True, if UPDATE/DELETE statements are allowed on this column and false otherwise (MySQL only)
  - insert: True, if INSERT statements are allowed on this column and false otherwise (MySQL only)

Example:

1. $db = new DbStream();
2. print_r($db->getTableInfo('foo'));

The output may look something like:

     Array
     (
         [length] => 6
         [primarykey] => foo_id
         [foreignkeys] => Array
             (
                 [0] => Array
                     (
                         [column] => bar_id
                         [foreigntable] => bar
                         [foreigncolumn] => bar_id
                     )

             )
         [0] => Array
             (
                 [table] => foo
                 [name] => foo_id
                 [type] => int
                 [nullable] =>
                 [primarykey] => 1
                 [unique] =>
                 [index] =>
                 [auto] => 1
                 [default] =>
                 [unsigned] =>
                 [zerofill] =>
                 [comment] => id
                 [length] => 8
                 [foreignkey] =>
                 [references] =>
                 [update] => 1
                 [insert] => 1
                 [select] => 1
             )

         [...]

         [5] => Array
             (
                 [table] => foo
                 [name] => bar_id
                 [type] => int
                 [nullable] =>
                 [primarykey] =>
                 [unique] =>
                 [index] => 1
                 [auto] =>
                 [default] =>
                 [unsigned] =>
                 [zerofill] =>
                 [comment] => some label
                 [length] => 10
                 [foreignkey] => 1
                 [references] => Array
                     (
                         [0] => bar
                         [1] => bar_id
                     )
                 [update] => 1
                 [insert] => 1
                 [select] => 1
             )
     )

- since: 2.9.6
- access: public

Redefined in descendants as:

- FileDb::getTableInfo() : get table information

##### 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

- access: public
- name: DbStream::importsql()
- uses: $DbStream->importSQL('some_file.sql')

##### insert row

bool insert (
string|DbQuery $key, [mixed $value = array()]
)

###### List of parameters:

Name | Type | Description
--- | --- | ---
$key | string|DbQuery |
$value | mixed |

###### Description:

Insert $value at position $key.
This function returns bool(true) on success and bool(false) on error. If $key already exists, the function will return bool(false).
Note, that this function does not auto-commit. This means, changes to the database will NOT be saved unless you call $DbStream->write().
Since version 2.9.3 the argument $key may also be an object of type $dbQuery. If so, no additional parameters need to be present. This is a shortcut, which e.g. allows you to prepare a query as an object and reuse it with multiple arguments.
Compatibility note: As of version 2.9.5, the behaviour of this function has changed. In version 2.9.4 and earlier, when a row already existed, it was updated automatically and no error was thrown. If you need to simulate this behaviour, to get an older plugin working, please set the global constant YANA_DB_COMPAT_INSERT to the value true (Default is false) in file "library.php".

- see: DbStream::update()
- see: DbStream::insertOrUpdate()
- since: 2.9.5
- access: public
- name: DbStream::insert()

##### update or insert row

bool insertOrUpdate (
string|DbQuery $key, [mixed $value = array()]
)

###### List of parameters:

Name | Type | Description
--- | --- | ---
$key | string|DbQuery |
$value | mixed |

###### Description:

insert $value at position $key
If $key already exists, the previous value gets updated, else the value is created. If you do not like this behaviour, take a look at the functions update() and insert() instead, which let you set the operation you want.
Note that, as this function has to determine which of both operations to take, it is somewhat slower (approx. 5%) then calling the appropriate function explicitly.
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().
Since version 2.9.3 the argument $key may also be an object of type $dbQuery. If so, no additional parameters need to be present. This is a shortcut, which e.g. allows you to prepare a query as an object and reuse it with multiple arguments.

- see: DbStream::update()
- see: DbStream::insert()
- since: 2.9.5
- access: public
- name: DbStream::insertOrUpdate()

##### 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:

This returns bool(false) if the database does not exist, or the database property "readonly" is set to bool(true) in the database's structure file. Otherwise the function returns bool(true).

- 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|DbQuery $table = ""], [string|array $search = array()]
)

###### List of parameters:

Name | Type | Description
--- | --- | ---
$table | string|DbQuery | name of a table
$search | string|array | optional where clause

###### Description:

Counts and returns the rows of $table. If no table is provided, the least recently used table will be selected instead.
Since version 2.9.3 you may also provide the parameter $table as an object of type DbQuery. This offers you more flexibility. In this case the second argument should not be provided. Instead you may add a where clause to your query object.

- access: public

##### optional API bypass

mixed query (
string|DbQuery $sqlStmt, int $offset, int $limit
)

###### List of parameters:

Name | Type | Description
--- | --- | ---
$sqlStmt | string|DbQuery | one SQL statement (or a query object) 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
Since version 2.9.3 this function has a second synopsis: You may provide a DbQuery object instead of the SQL statement.

1. $dbStream->query($sqlStmt, $offset, $limit);
2. // 2nd synopsis
3. $dbStream->query($dbQuery);

Note that when providing the DbQuery object, the $limit and $offset arguments are ignored.

- access: public

##### remove one row

bool remove (
string|DbQuery $key, [string|array $where = array()]
)

###### List of parameters:

Name | Type | Description
--- | --- | ---
$key | string|DbQuery | the address of the row that should be removed
$where | string|array | a search string

###### 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.
Since version 2.9.3 the argument $key may also be an object of type $dbQuery. If so, no additional parameters need to be present. This is a shortcut, which e.g. allows you to prepare a query as an object and reuse it with multiple arguments.

- 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
- name: DbStream::reset()

##### Alias of DbStream::reset()

void rollback ()

###### Description:

- see: DbStream::reset()
- 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:

This exports the data of $table as a comma-seperated list of values. If $table is not provided, the least recently used table is chosen instead.
This function returns bool(false) on error.

- access: public
- uses: $DbStream->toString('foo')

Redefinition of: Object::toString()

##### update a row or cell

bool update (
string|DbQuery $key, [mixed $value = array()]
)

###### List of parameters:

Name | Type | Description
--- | --- | ---
$key | string|DbQuery |
$value | mixed |

###### Description:

update $value at position $key
If $key does not exist, bool(false) is returned.
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 until you call $DbStream->write().
The argument $key may also be an object of type $dbQuery. If so, no additional parameters need to be present. This is a shortcut, which e.g. allows you to prepare a query as an object and reuse it with multiple arguments.

- see: DbStream::insert()
- see: DbStream::insertOrUpdate()
- since: 2.9.5
- access: public
- name: DbStream::update()

##### Commit current transaction

bool write ()

###### Description:

This writes all changes to the database

- access: public
- name: DbStream::write()

##### inherited from base classes

Inherited From Object

- Object::cloneObject()
- Object::equals()
- Object::getClass()
- Object::serialize()
- Object::toString()

Documentation generated on Sun, 04 Jan 2009 03:48:54 +0100 by phpDocumentor 1.4.0

yana author: Thomas Meyerwww.yanaframework.net