TIP_Data_Engine

Introduction

Base class for data engines

Source file

/Type/data_engine.php

Extends

TIP_Type

abstract

yes

Provides a common interface to access any data requested by TIP.

Properties

Methods

startTransaction () : bool

Start a transaction

lines

40 - 48

access

public

If a transaction is yet started, simply returns true without starting a new transaction (nested transactions are not allowed).

endTransaction ($commit) : bool

End a transaction

$commit

bool
Commit (if true) or rollback (if false)

lines

66 - 80

access

public

End the current transaction. If there's no active transaction, raise an error and return false.

The transaction is really ended when the last started transaction is closed. For instance, if you call startTransaction() twice and endTransaction() once, the data will be never committed.

The error flag indicates if the transaction must be rolled back ($commit = true) of committed ($commit = false).

preparedName ($name, [$domain]) : string

Prepare names for a query

$name

string|array
The name or array of names to prepare

$domain

string|null [ = null ]
The domain $name is part of

lines

104 - 104

abstract

yes

access

public

Prepares one or more identifiers to be inserted in a query. The TIP_Mysql::preparedName() method, for example, backticks $name if $name does not start yet with a backtick.

If $name is an array, the preparedName() process is applied recursively for every item and a comma separated string of prepared names is returned.

The $domain value is a engine depended feature to identify the context where $name is significant. In SQL based engines, for instance, it is the table name.

preparedValue ($value) : string

Prepare values for a query

$value

mixed|array
The value or array of values to prepare

lines

119 - 119

abstract

yes

access

public

Prepares one or more values to be inserted in a query. The TIP_Mysql engine, for instance, escapes the values throught mysql_real_escape_string(). Also, if $value is null, 'NULL' is returned.

If $value is an array, a comma separated string of prepared values is returned.

query () : resource

Perform a query

lines

130 - 130

abstract

yes

access

public

This is the core function of a database engine. Any list of arguments should be accepted, usually imploding their string representation using a space as glue.

fillFields (&$data) : bool

Fill the fields structure

&$data

lines

141 - 141

abstract

yes

access

public

Fills the $_fields internal property of the TIP_Data object: read the TIP_Data documentation for further details.

select (&$data, $filter, $fields) : &array|null

Read data

&$data

TIP_Data
The data context

$filter

string
The filter conditions

$fields

array|null
An array of field ids to get, or null for all fields

lines

160 - 160

abstract

yes

access

public

Gets the rows that satisfy the $filter conditions. Only the fields specified by $data->_fieldset must be read. If this fieldset is null, all the fields are assumed.

The result must be an empty array if there's no matching rows. The type of the field values is not important: the resulting array will be casted to the proper type in the TIP_Data object.

insert (&$data, &$rows) : int|null

Insert new rows

&$data

TIP_Data
The data context

&$rows

array
An array of rows

lines

181 - 181

abstract

yes

access

public

Inserts new rows. The autoincrement value of the last row is returned. If the primary keys are specified in $rows and a row with any primary key yet exists, this function must fail.

The rows must be homogeneus: if the first row has five fields, all the other rows must have the same five fields (obviously, with different values).

Notice $rows can be an empty array, in which case a new empty row must be added without errors. In this case, the row must be filled with its default values.

update (&$data, $filter, &$row) : bool

Update data

&$data

TIP_Data
The data context

$filter

string
The filter conditions

&$row

array
The field=>value pairs to update

lines

195 - 195

abstract

yes

access

public

Updates the rows that match the $filter conditions using the new $row contents. To leave the fields untouched, simply do not specify these fields in $row.

delete (&$data, $filter) : bool

Delete data

&$data

TIP_Data
The data context

$filter

string
The filter conditions

lines

206 - 206

abstract

yes

access

public

Removes the rows that match the $filter conditions.

dump ($root) : bool

Dump a whole database content

$root

string
The base path where to store the result

lines

214 - 214

abstract

yes

access

public

transaction ($action) : bool

Start a transaction

$action

TIP_TRANSACTION_...
The action to perform

lines

222 - 222

abstract

yes

access

protected