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

• $options['engine']: the TIP_Data_Engine options to use
• $options['primary_key']: the primary key field
• $options['fieldset']: fields to use in queries
• $options['join']: join definitions

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.