Exponent v2.4.3 » \database

subpackage	Database
package	Subsystems

__construct

__construct( $username,  $password,  $hostname,  $database,  $new = false)

abstract

Arguments

$username

$password

$hostname

$database

$new

adjustNestedTreeBetween

adjustNestedTreeBetween( $table,  $lft,  $rgt,  $width) : void

Arguments

$table

$lft

$rgt

$width

adjustNestedTreeFrom

adjustNestedTreeFrom( $table,  $start,  $width) : void

Arguments

$table

$start

$width

Alter an existing table

alterTable(string $tablename, array $newdatadef, array $info, boolean $aggressive = false) : array

abstract

Alters the structure of an existing database table to conform to the passed data definition.

This function abides by the Exponent Data Definition Language, and interprets its general structure for databases.

Arguments

$tablename

string

The name of the table to alter

$newdatadef

array

The new data definition for the table. This is expressed in the Exponent Data Definition Language

$info

array

Information about the table itself.

$aggressive

boolean

Whether or not to aggressively update the table definition. An aggressive update will drop columns in the table that are not in the Exponent definition.

Response

array

Update a column in all records in a table

columnUpdate( $table,  $col,  $val, integer|null $where = 1) : void

abstract

Arguments

$table

$col

$val

$where

integer|null

Count Objects matching a given criteria

countObjects(string $table, string $where = null, boolean $is_revisioned = false, boolean $needs_approval = false, null $user = null) : integer

abstract

Arguments

$table

string

The name of the table to count objects in.

$where

string

Criteria for counting.

$is_revisioned

boolean

$needs_approval

boolean

$user

null

Response

integer

Count Objects matching a given criteria using raw sql

countObjectsBySql(string $sql) : integer

abstract

Arguments

$sql

string

The sql query to be run

Response

integer

Create a new Table

createTable(string $tablename, array $datadef, array $info) : array

abstract

Creates a new database table, according to the passed data definition.

This function abides by the Exponent Data Definition Language, and interprets its general structure for databases.

Arguments

$tablename

string

The name of the table to create

$datadef

array

The data definition to create, expressed in the Exponent Data Definition Language.

$info

array

Information about the table itself.

Response

array

Returns table information for all tables in the database.

databaseInfo() : array

abstract

This function effectively calls tableInfo() on each table found.

Response

array

Decrement a numeric table field in a table.

decrement(string $table, string $field, integer $step, string $where = null)

Arguments

$table

string

The name of the table to decrement in.

$field

string

The field to decrement.

$step

integer

The step value. Usually 1. This can be negative, to increment, but the increment() method is preferred, for readability.

$where

string

Optional criteria to determine which records to update.

Delete one or more objects from the given table.

delete(string $table, string $where = null) : mixed

abstract

Arguments

$table

string

The name of the table to delete from.

$where

string

Criteria for determining which record(s) to delete.

Response

mixed

deleteNestedNode

deleteNestedNode( $table,  $lft,  $rgt) : void

Arguments

$table

$lft

$rgt

describeTable

describeTable( $table)

Arguments

$table

Drop a table from the database

dropTable(string $table) : boolean

abstract

Removes an existing table from the database. Returns true if the table was dropped, false if there was an error returned by the database server.

Arguments

$table

string

The name of the table to drop.

Response

boolean

Returns an error message from the database server. This is intended to be used by the implementers of the database wrapper, so that certain cryptic error messages can be reworded.

error() : string

abstract

Response

string

Escape a string based on the database connection

escapeString( $string) : string

abstract

Arguments

$string

Response

string

Build a data definition from a pre-existing table. This is used to intelligently alter tables that have already been installed.

getDataDefinition(string $table) : array|null

abstract

Arguments

$table

string

The name of the table to get a data definition for.

Response

array|null

Get a list of all tables in the database. Optionally, only the tables in the current logical database (tables with the same prefix) can be retrieved.

getTables(boolean $prefixed_only = true) : array

abstract

Arguments

$prefixed_only

boolean

Whether to return only the tables for the logical database, or all tables in the physical database.

Response

array

This function returns all the text columns in the given table

getTextColumns( $table) : array

abstract

Arguments

$table

Response

array

Increment a numeric table field in a table.

increment(string $table, string $field, integer $step, string $where = null) : mixed

abstract

Arguments

$table

string

The name of the table to increment in.

$field

string

The field to increment.

$step

integer

The step value. Usually 1. This can be negative, to decrement, but the decrement() method is preferred, for readability.

$where

string

Optional criteria to determine which records to update.

Response

mixed

Checks whether the database connection has experienced an error.

inError() : boolean

abstract

Response

boolean

Attempt to prevent a sql injection

injectProof( $string) : string

Arguments

$string

Response

string

Insert an Object into some table in the Database

insertObject(object $object, string $table) : integer|void

abstract

This method will return the ID assigned to the new record by database. Note that object attributes starting with an underscore ('_') will be ignored and NOT inserted into the table as a field value.

Arguments

$object

object

The object to insert.

$table

string

The logical table name to insert into. This does not include the table prefix, which is automagically prepended for you.

Response

integer|void

Checks to see if the connection for this database object is valid.

isValid() : boolean

Response

boolean

True if the connection can be used to execute SQL queries.

Create a SQL "limit" phrase

limit( $num,  $offset) : string

Arguments

$num

$offset

Response

string

lockTable

lockTable( $table, string $lockType = "WRITE") : mixed

abstract

Arguments

$table

$lockType

string

Response

mixed

Find the maximum value of a field. This is similar to a standard SELECT MAX(field) .

max(string $table, string $attribute, string $groupfields = null, string $where = null) : mixed

abstract

.. query.

Arguments

$table

string

The name of the table to select from.

$attribute

string

The attribute name to find a maximum value for.

$groupfields

string

A comma-separated list of fields (or a single field) name, used for a GROUP BY clause. This can also be passed as an array of fields.

$where

string

Optional criteria for narrowing the result set.

Response

mixed

Runs whatever table optimization routines the database engine supports.

optimize(string $table) : boolean

abstract

Arguments

$table

string

The name of the table to optimize.

Response

boolean

Count Objects matching a given criteria using raw sql

queryRows(string $sql) : integer|void

Arguments

$sql

string

The sql query to be run

Response

integer|void

selectAndJoinObjects

selectAndJoinObjects(null $colsA = null, null $colsB = null,  $tableA,  $tableB,  $keyA, null $keyB = null, null $where = null, null $orderby = null)

Arguments

$colsA

null

$colsB

null

$tableA

$tableB

$keyA

$keyB

null

$where

null

$orderby

null

Select a record from the database as an array Selects a set of arrays from the database. Because of the way Exponent handles objects and database tables, this is akin to SELECTing a set of records from a database table. Returns an array of arrays, in any random order.

selectArray(string $table, string $where = null, null $orderby = null, boolean $is_revisioned = false, boolean $needs_approval = false, null $user = null) : array|void

abstract

Arguments

$table

string

The name of the table/object to look at

$where

string

Criteria used to narrow the result set. If this is specified as null, then no criteria is applied, and all objects are returned

$orderby

null

$is_revisioned

boolean

$needs_approval

boolean

$user

null

Response

array|void

Select an array of arrays

selectArrays(string $table, string $where = null, string $orderby = null, boolean $is_revisioned = false, boolean $needs_approval = false, null $user = null) : array

abstract

Selects a set of arrays from the database. Because of the way Exponent handles objects and database tables, this is akin to SELECTing a set of records from a database table. Returns an array of arrays, in any random order.

Arguments

$table

string

The name of the table/object to look at

$where

string

Criteria used to narrow the result set. If this is specified as null, then no criteria is applied, and all objects are returned

$orderby

string

$is_revisioned

boolean

$needs_approval

boolean

$user

null

Response

array

Select an array of arrays

selectArraysBySql(string $sql) : array

abstract

Selects a set of arrays from the database. Because of the way Exponent handles objects and database tables, this is akin to SELECTing a set of records from a database table. Returns an array of arrays, in any random order.

Arguments

$sql

string

The name of the table/object to look at

Response

array

selectColumn

selectColumn( $table,  $col, null $where = null, null $orderby = null, boolean $distinct = false) : array

abstract

Arguments

$table

$col

$where

null

$orderby

null

$distinct

boolean

Response

array

selectDropdown

selectDropdown( $table,  $col, null $where = null, null $orderby = null) : array

abstract

Arguments

$table

$col

$where

null

$orderby

null

Response

array

Instantiate objects from selected records from the database

selectExpObjects(string $table, string $where = null,  $classname, boolean $get_assoc = true, boolean $get_attached = true, array $except = array(), boolean $cascade_except = false, null $order = null, null $limitsql = null, boolean $is_revisioned = false, boolean $needs_approval = false, null $user = null) : array

abstract

Arguments

$table

string

The name of the table/object to look at

$where

string

Criteria used to narrow the result set. If this is specified as null, then no criteria is applied, and all objects are returned

$classname

$get_assoc

boolean

$get_attached

boolean

$except

array

$cascade_except

boolean

$order

null

$limitsql

null

$is_revisioned

boolean

$needs_approval

boolean

$user

null

Response

array

Instantiate objects from selected records from the database

selectExpObjectsBySql(string $sql, string $classname, boolean $get_assoc = true, boolean $get_attached = true)

Arguments

$sql

string

The sql statement to run on the model/classname

$classname

string

Can be $this->baseclassname Returns an array of fields

$get_assoc

boolean

$get_attached

boolean

selectFormattedNestedTree

selectFormattedNestedTree( $table)

Arguments

$table

selectNestedBranch

selectNestedBranch( $table, null $node = null) : array

Arguments

$table

$node

null

Response

array

selectNestedNodeChildren

selectNestedNodeChildren( $table, null $node = null) : array

Arguments

$table

$node

null

Response

array

selectNestedNodeParent

selectNestedNodeParent( $table, null $node = null) : array

Arguments

$table

$node

null

Response

array

selectNestedTree

selectNestedTree( $table) : array

Arguments

$table

Response

array

Select a single object.

selectObject(string $table, string $where) : object|null|void

abstract

Selects an objects from the database. Because of the way Exponent handles objects and database tables, this is akin to SELECTing a single record from a database table. Returns the first record/object found (in the case of multiple-result queries, there is no way to determine which of the set will be returned). If no record(s) match the query, null is returned.

Arguments

$table

string

The name of the table/object to look at

$where

string

Criteria used to narrow the result set.

Response

object|null|void

Select a single object by sql

selectObjectBySql( $sql) : null|void

abstract

Arguments

$sql

Response

null|void

Select a series of objects

selectObjects(string $table, string $where = null, null $orderby = null, boolean $is_revisioned = false, boolean $needs_approval = false, null $user = null) : array

abstract

Selects a set of objects from the database. Because of the way Exponent handles objects and database tables, this is akin to SELECTing a set of records from a database table. Returns an array of objects, in any random order.

Arguments

$table

string

The name of the table/object to look at

$where

string

Criteria used to narrow the result set. If this is specified as null, then no criteria is applied, and all objects are returned

$orderby

null

$is_revisioned

boolean

$needs_approval

boolean

$user

null

Response

array

Select a series of objects by sql

selectObjectsBySql( $sql) : array

abstract

Arguments

$sql

Response

array

This function takes an array of indexes and returns an array with the objects associated with each id

selectObjectsInArray( $table, array $array = array(), null $orderby = null) : array

Arguments

$table

$array

array

$orderby

null

Response

array

Select a series of objects, and return by ID

selectObjectsIndexedArray(string $table, string $where = null, null $orderby = null) : array

abstract

Selects a set of objects from the database. Because of the way Exponent handles objects and database tables, this is akin to SELECTing a set of records from a database table. Returns an array of objects, in any random order. The indices of the array are the IDs of the objects.

Arguments

$table

string

The name of the table/object to look at

$where

string

Criteria used to narrow the result set. If this is specified as null, then no criteria is applied, and all objects are returned

$orderby

null

Response

array

selectPathToNestedNode

selectPathToNestedNode( $table, null $node = null) : array

Arguments

$table

$node

null

Response

array

selectSearch

selectSearch( $terms, null $where = null)

Arguments

$terms

$where

null

selectSum

selectSum( $table,  $col, null $where = null)

Arguments

$table

$col

$where

null

selectValue

selectValue( $table,  $col, null $where = null) : null

abstract

Arguments

$table

$col

$where

null

Response

null

selectValueBySql

selectValueBySql( $sql) : null

Arguments

$sql

Response

null

setUniqueFlag

setUniqueFlag( $object,  $table,  $col, integer|null $where = 1) : boolean

Arguments

$object

$table

$col

$where

integer|null

Response

boolean

Run raw SQL. Returns true if the query succeeded, and false if an error was returned from the database server.

sql(string $sql, boolean $escape = true) : mixed

abstract

If you can help it, do not use this function. It presents Database Portability Issues.

Runs a straight SQL query on the database. This is not a very portable way of dealing with the database, and is only provided as a last resort.

Arguments

$sql

string

The SQL query to run

$escape

boolean

Response

mixed

Connect to the database by PDO

sql_connect_pdo() : \PDO

abstract

Response

\PDO

Database connection handle

Switch field values between two entries in a Table

switchValues( $table,  $field,  $a,  $b, null $additional_where = null) : boolean

Switches values between two table entries for things like swapping rank, etc...

Arguments

$table

$field

$a

$b

$additional_where

null

Response

boolean

Check to see if the named table exists in the database.

tableExists(string $table) : boolean

abstract

Returns true if the table exists, and false if it doesn't.

Arguments

$table

string

Name of the table to look for.

Response

boolean

Retrieve table information for a named table.

tableInfo( $table) : null

Returns an object, with the following attributes:

rows -- The number of rows in the table.
average_row_length -- The average storage size of a row in the table.
data_total -- How much total disk space is used by the table.
data_overhead -- How much storage space in the table is unused (for compacting purposes)

Arguments

$table

Response

null

Check whether or not a table in the database is empty (0 rows).

tableIsEmpty(string $table) : boolean

Returns tue of the specified table has no rows, and false if otherwise.

Arguments

$table

string

Name of the table to check.

Response

boolean

Test the privileges of the user account for the connection.

testPrivileges() : array

Tests run include:

CREATE TABLE
INSERT
SELECT
UPDATE
DELETE
ALTER TABLE
DROP TABLE

These tests must be performed in order, for logical reasons. Execution terminates when the first test fails, and the status flag array is returned then. Returns an array of status flags. Key is the test name. Value is a boolean, true if the test succeeded, and false if it failed.

Response

array

Toggle a boolean value in a Table Entry

toggle( $table,  $col, null $where = null) : void

Arguments

$table

$col

$where

null

Reduces table item revisions to a passed total

trim_revisions(string $table, integer $id, integer $num, integer|string $workflow = ENABLE_WORKFLOW)

Arguments

$table

string

The name of the table to trim

$id

integer

The item id

$num

integer

The number of revisions to retain

$workflow

integer|string

is workflow turned on (or force)

unlockTables

unlockTables() : mixed

abstract

Response

mixed

Update one or more objects in the database.

updateObject(object $object, string $table, string $where = null, string $identifier = 'id', boolean $is_revisioned = false) : boolean|integer|void

abstract

This function will only update the attributes of the resulting record(s) that are also member attributes of the $object object.

Arguments

$object

object

An object specifying the fields and values for updating. In most cases, this will be the altered object originally returned from one of the select* methods.

$table

string

The table to update in.

$where

string

Optional criteria used to narrow the result set.

$identifier

string

$is_revisioned

boolean

Response

boolean|integer|void

Database connection string

connection : string

var	Database connection string

Type(s)

string

havedb

havedb : boolean

var

Type(s)

boolean

Database prefix

prefix : string

var	Database prefix

Type(s)

string

database

Methods

__construct

Arguments

$username

$password

$hostname

$database

$new

adjustNestedTreeBetween

Arguments

$table

$lft

$rgt

$width

adjustNestedTreeFrom

Arguments

$table

$start

$width

Alter an existing table

Arguments

$tablename

$newdatadef

$info

$aggressive

Response

Update a column in all records in a table

Arguments

$table

$col

$val

$where

Count Objects matching a given criteria

Arguments

$table

$where

$is_revisioned

$needs_approval

$user

Response

Count Objects matching a given criteria using raw sql

Arguments

$sql

Response

Create a new Table

Arguments

$tablename

$datadef

$info

Response

Returns table information for all tables in the database.

Response

Decrement a numeric table field in a table.

Arguments

$table

$field

$step

$where

Delete one or more objects from the given table.

Arguments

$table

$where

Response

deleteNestedNode

Arguments

$table

$lft

$rgt

describeTable

Arguments

$table

Drop a table from the database

Arguments

$table

Response

Returns an error message from the database server. This is intended to be used by the implementers of the database wrapper, so that certain cryptic error messages can be reworded.

Response

Escape a string based on the database connection

Arguments