TIP_Data

Introduction

A generic data provider

Source file
/Type/data.php
Extends
TIP_Type

All the queries are "prepared" accordling to the data engine used. This means the parameters are modified by calling preparedName() and preparedValue() of the TIP_Data_Engine object.

Prepending the at symbol (@) to a name means that name must be passed-throught without modification (a raw name).

Properties

path : string

The data path

access
protected

engine : TIP_Data_Engine

The data engine

access
protected

primary_key : $string

The primary key field

access
protected

Defaults to 'id' but can be changed passing a different 'primary_key' option. The primary key univoquely identifies a single row of data.

fieldset : array

Fields to use in queries

access
protected

An array of field ids used by this object. If left null, all the fields are assumed.

joins : array

Join definitions

access
protected

Methods

checkOptions (&$options) : bool

Check the options

&$options
array
Properties values
lines
86 - 115
static
yes
access
protected

Overridable static method that checks $options for missing or invalid values and eventually corrects its content.

__construct ($options)

Constructor

$options
array
Properties values
lines
131 - 134
access
protected

Initializes a TIP_Data instance.

$options inherits the TIP_Type properties, and add the following: * $options['path']: the path to the data source or the table name

getLastId () : mixed

Get the last id

lines
146 - 149
access
public

Returns the last id as returned by the last call to putRow().

getFieldsRef () : &array

Get the reference of the $_fields internal property

lines
158 - 161
access
public

Mainly used by the data engine to fill the fields structure.

filter ($name, $value, [$condition]) : string

Create a basic filter

$name
string
A field id
$value
mixed
The reference value
$condition
string [ = '=' ]
The condition to apply
lines
175 - 178
access
public

Creates a filter (in the proper engine format) to access the rows that match the specified filter. If $condition is not specified, it defaults to '=' (equal).

addFilter ($connector, $name, $value, [$condition]) : string

Create an appendable filter expression

$connector
string
A boolean expression
$name
string
A field id
$value
mixed
The reference value
$condition
string [ = '=' ]
The condition to apply
lines
192 - 207
access
public

Creates a portion of a filter (in the proper engine format) that can be added to the main filter (generated throught the filter() method).

order ($name, [$descending]) : string

Create a basic order clause

$name
string
A field id
$descending
bool [ = false ]
true for descending order
lines
219 - 233
access
public

Builds the order clause (in the proper engine format) to sort the rows using the specified field. This clause can be appended to a main filter.

limit ($count, [$offset]) : string

Create a limit clause

$count
int
Maximum number of rows
$offset
int|null [ = null ]
Starting row (starting from 0)
lines
244 - 250
access
public

Builds a limit clause (in the proper engine format).

rowFilter ($id) : string

Create a filter to access a single row

$id
mixed
The primary key value
lines
262 - 265
access
public

Shortcut to create a filter (in the proper engine format) to access only the first row with the primary key matching $value. Useful when the primary key is unique to access records by id.

getFields ([$detailed]) : &array|null

Get the fields structure

$detailed
bool [ = true ]
Force a TIP_Data_Engine::fillDetails() call
lines
275 - 292
access
public

Gets the field structure of this data context.

getFieldType ($id) : string|null

Get a field type

$id
mixed
A field identifier
lines
304 - 333
access
public

Gets the field type by updating the internal field structure and searching for $id. If it is not found, a recursive search is performed on the joined TIP_Data objects (if any).

getRow ($id, [$fields]) : &array|null

Read one row

$id
mixed
The row id
$fields
array|null [ = null ]
Fields to get or null for all
lines
345 - 356
access
public

Retrieves the content of the row with the specified $id.

getRows ($filter, [$fields]) : &array|null

Read more rows

$filter
string
The filter conditions
$fields
array|null [ = null ]
Fields to get or null for all
lines
371 - 379
access
public

Gets the rows that satisfy the $filter conditions. The syntax of the filter is data engine dependent: no assumptions are made by the TIP_Data class. Whenever possible, use the filter() and rowFilter() to build a proper filter.

putRow (&$row) : bool

Insert a new row

&$row
array
The row to insert
lines
399 - 429
access
public

Inserts a new row in the data source. If the insert() method returns an autoincrement value, it will be used as the primary key of $row.

If $row is an empty array, a new row with default values will be inserted without errors.

Also, this method is subject to the fieldset: if $fieldset is set, only the fields present in this subset will be inserted.

Instead, if the primary key is defined in $row, this function fails if a row with the same primary key exists.

putRows ($rows) : bool

Insert more rows

$rows
array
An array of rows to insert
lines
445 - 461
access
public

Multiple inserts rows in the data source.

This method, as its single row counterpart, is subject to the fieldset in the same way putRow() is.

The primary keys can be defined, but if someone of them is yet present in the data source, this function will fail.

updateRow ($row, [$old_row]) : bool

Update one row

$row
array
The new row content
$old_row
array [ = null ]
The old row content
lines
479 - 516
access
public

Updates $row. If $old_row is specified, the id of the row to update is get from the primary key of $old_row. If it does not exists (or $old_row is not used) the id will be the primary key of $row. If not found yet, the function will fail because does not know the id to update.

$old_row is used also as filter to remove matching field contents between $row and $old_row. This is done to allow a check between the old and new row content, trying to avoid the update operation.

updateRows ($filter, $row) : bool

Update more rows

$filter
string
The filter conditions
$row
array
A row with the field => value pairs to update
lines
535 - 556
access
public

Updates the rows that match the $filter conditions accordling to the $row array, which must be a collection of "fieldid => value" to change. The syntax of $filter is data engine dependent: no assumptions are made by the TIP_Data class. This also means the $filter parameter must be $filter.

This function must be used to update more than one row: this means $row must not have the primary key defined (a primary key is unique). To update only one row, use updateRow() instead.

deleteRow ($row) : bool

Delete one row

$row
mixed
The row to delete or the row id
lines
567 - 577
access
public

Deletes the specified row. $row could be the row id or the row array to delete.

deleteRows ($filter) : bool

Delete more rows

$filter
string
The row filter
lines
593 - 601
access
public

Deletes the rows matching the $filter conditions. The syntax of $filter is data engine dependent: no assumptions are made by the TIP_Data class. This also means the $filter parameter must be prepared for the engine: use the prepare... primitives provided by the data engine.

Notice empty filter are rejected by the engine to avoid dropping the whole content of a table.

TIP_Data was last modified by TiP on Mon 25 May 2009 06:22:25 PM CEST
Hosted by BerliOS Developer Logo