Constants

SHARE_FIELD_OBJECTS_WITH_ROW

SHARE_FIELD_OBJECTS_WITH_ROW

Constant to clarify behavior of second param to createRow().

NEW_FIELD_OBJECTS_PER_ROW

NEW_FIELD_OBJECTS_PER_ROW

Constant to clarify behavior of second param to createRow().

ADMIN

ADMIN

Properties

$fieldProviders

$fieldProviders : array

Field providers can check for the existence of and create objects for fields of various types (e.g. concrete DB columns or EAV fields).

Type

array

$fields

$fields : array

Any field objects that have been generated for this table.

Type

array

$manyToMany

$manyToMany : array

The ManyToMany relationships that have been added to this table. These relationships integrate with the other aspects of the DB API.

Type

array

$eav

$eav : \Dewdrop\Db\Eav\Definition

If this table has a corresponding set of EAV tables that can be used to define custom fields/attibutes for the model, this variable will be a reference to the EAV definition object.

Type

\Dewdrop\Db\Eav\Definition

$fieldCustomizationCallbacks

$fieldCustomizationCallbacks : array

Callbacks assigned during the init() method of your table sub-class, which will be used to tweak the default field settings away from the defaults inferred from DB metadata.

Type

array

$rowClass

$rowClass : string

The default row class for this table object. If you'd like to use a custom row class for your model, you can set it in your init() method.

Type

string

$db

$db : \Dewdrop\Db\Adapter

The database adapter used by this table

Type

\Dewdrop\Db\Adapter

$tableName

$tableName : string

The name of the DB table represented by this table class.

Type

string

$metadata

$metadata : array

The metadata generated by the db-metadata CLI command or the dbdeploy CLI command for this table. This is used to provide your plugin with information about the columns and constraints on the underlying DB table.

Type

array

$pluralTitle

$pluralTitle : string

A pluralized version of this table's title. If not manually specified, the title will be inflected from teh table name.

Type

string

$singularTitle

$singularTitle : string

A singularized version of this table's title. If not manually specified, the title will be inflected from teh table name.

Type

string

Methods

__construct()

__construct(\Dewdrop\Db\Adapter  $db = null) 

Create new table object with supplied DB adapter

Parameters

\Dewdrop\Db\Adapter $db

init()

init() : void

This method should be used by sub-classes to set the table name, create field customization callbacks, etc.

getActivityLogHandler()

getActivityLogHandler() 

fetchAdminListing()

fetchAdminListing() : array

Return a listing for the admin.

Returns

array

registerEav()

registerEav(array  $options = array()) : \Dewdrop\Db\Table

Register an EAV definition with this table.

Parameters

array $options

Additional options to pass to the EAV definition.

Returns

\Dewdrop\Db\Table

hasEav()

hasEav() : boolean

Check to see if this model has an EAV definition.

Returns

boolean

getEav()

getEav() : \Dewdrop\Db\Eav\Definition

Get the EAV definition associated with this table.

Returns

\Dewdrop\Db\Eav\Definition

hasUniqueConstraint()

hasUniqueConstraint(  $columns, array  $options = array()) 

Parameters

$columns
array $options

getUniqueConstraintsAffectingColumn()

getUniqueConstraintsAffectingColumn(string  $columnName) : array<mixed,\Dewdrop\Db\UniqueConstraint>

Parameters

string $columnName

Returns

array<mixed,\Dewdrop\Db\UniqueConstraint>

hasMany()

hasMany(string  $relationshipName, string  $xrefTableName, array  $additionalOptions = array()) 

Register a many-to-many relationship with this table. This will allow you to retrieve and set the values for this relationship from row objects and also generate field objects representing this relationship.

Generally, supplying the relationship name and the cross-reference table name are all you need to do to register the relationship. However, if Dewdrop cannot determine the additional pieces of information needed to support the relationship, you can specify those manually using the additional options array.

Once registered, you can use the relationship name you supplied as if it was a normal field. So, you can do things like:

$row->field('my_relationship_name');

Or:

$this->insert(
    array(
        'name'                 => 'Concrete DB column value',
        'foo_id'               => 2,
        'my_relationship_name' => array(1, 2, 3)
    )
);

In the latter example, Dewdrop will automatically save the cross-reference table values following the primary INSERT query.

Parameters

string $relationshipName
string $xrefTableName
array $additionalOptions

hasManyToManyRelationship()

hasManyToManyRelationship(string  $name) : boolean

Determine if this table has a many-to-many relationship with the given name.

Parameters

string $name

Returns

boolean

getManyToManyRelationship()

getManyToManyRelationship(string  $name) : \Dewdrop\Db\ManyToMany\Relationship

Retrieve the many-to-many relationship with the given name. You should call hasManyToManyRelationship() prior to this to ensure the relationship exists.

Parameters

string $name

Returns

\Dewdrop\Db\ManyToMany\Relationship

getManyToManyRelationships()

getManyToManyRelationships() : array

Return array of all many-to-many relationship assigned to this table.

Returns

array

getRowColumns()

getRowColumns() : array

Get an array representing the valid column names that can be get or set on a row object tied to this table. This will include the concrete columns present in the physical database table and the many-to-many or EAV fields registered with and managed by this table object.

Returns

array

field()

field(string  $name) : \Dewdrop\Db\Field

Retrieve the field object associated with the specified name.

Parameters

string $name

Returns

\Dewdrop\Db\Field

customizeField()

customizeField(string  $name, mixed  $callback) : \Dewdrop\Db\Table

Assign a callback that will allow you to further customize a field object whenever that object is requested using the table's field() method.

Parameters

string $name
mixed $callback

Returns

\Dewdrop\Db\Table

setTableName()

setTableName(string  $tableName) 

Assign a DB table name to this model.

Parameters

string $tableName

getTableName()

getTableName() : string

Get the DB table name assigned to this model.

Returns

string

setRowClass()

setRowClass(string  $rowClass) : \Dewdrop\Db\Table

Allow setting of custom row class for this table.

Parameters

string $rowClass

Returns

\Dewdrop\Db\Table

setSingularTitle()

setSingularTitle(string  $singularTitle) : \Dewdrop\Db\Table

Override the default singular title.

Parameters

string $singularTitle

Returns

\Dewdrop\Db\Table

getSingularTitle()

getSingularTitle() : string

Get a singular title (e.g. "Fruit", not "Fruits") for this model.

If no title is set, we'll pull the inflected version from the table's metadata.

Returns

string

setPluralTitle()

setPluralTitle(string  $pluralTitle) : \Dewdrop\Db\Table

Manually override the inflected plural title for this model.

Parameters

string $pluralTitle

Returns

\Dewdrop\Db\Table

getPluralTitle()

getPluralTitle() : string

Get a singular title (e.g. "Fruits", not "Fruit") for this model.

If no title is set, we'll pull the inflected version from the table's metadata.

Returns

string

getMetadata()

getMetadata(string  $section = null, string  $index = null) : array

Load this table's metadata from the file generated by the db-metadata CLI command. The metadata currently has two sections:

  • titles: Default singular and plural titles for the model.
  • columns: The columns in the table with types, constraints, etc.

You can retrieve the entirety of the metadata information by providing null values to both arguments. You can retrieve an entire section of the metdata by only specifying the first argument. Or, you can specify values for both arguments to retrieve a specific member of a specific section.

For example, to get metadata only for the "name" column, you would call:

$this->getMetadata('columns', 'name');

Parameters

string $section
string $index

Returns

array

getPrimaryKey()

getPrimaryKey() : array

Get the names of the columns in the primary key. This will always return an array of column names, even if there is only one column in the table's primary key.

Returns

array

getAdapter()

getAdapter() : \Dewdrop\Db\Adapter

Get the DB adapter associated with this table object.

Returns

\Dewdrop\Db\Adapter

select()

select() : \Dewdrop\Db\Select

Create a new \Dewdrop\Db\Select object.

Returns

\Dewdrop\Db\Select

selectListing()

selectListing() : \Dewdrop\Db\Select

Generate a listing Select object. A listing attempts to include values for foreign keys, many-to-many relationships for contexts such as admin CRUD components where you intend to display all the information related to a certain set of entities.

Returns

\Dewdrop\Db\Select

selectAdminListing()

selectAdminListing() : \Dewdrop\Db\Select

By default, returns the same value as selectListing(). However, this is here as a placeholder for any admin-area specific listing changes you need to make for this model.

Returns

\Dewdrop\Db\Select

getFieldProviders()

getFieldProviders() : array

Get all the field providers added to this table.

Returns

array

insert()

insert(array  $data) : integer|null

Insert a new row.

Data should be supplied as key value pairs, with the keys representing the column names.

We return the ID of the inserted row because if we do not return it from insert(), it will be impossible to retrieve it, if we have many-to-many or EAV fields that also inserted rows before this method returns.

Parameters

array $data

Returns

integer|null —

Last insert ID, if the table has auto-incrementing key.

update()

update(array  $data, string  $where) : integer

Update an existing row.

Data should be supplied as key value pairs, with the keys representing the column names. The where clause should be an already assembled and quoted string. It should not be prefixed with the "WHERE" keyword.

Parameters

array $data
string $where

Returns

integer —

The number of rows affected.

delete()

delete(array|string  $where) : integer

Deletes existing rows.

Parameters

array|string $where

SQL WHERE clause(s).

Returns

integer —

The number of rows deleted.

find()

find() : \Dewdrop\Db\Row|null

Find a single row based upon primary key value.

Returns

\Dewdrop\Db\Row|null

findRowRefreshData()

findRowRefreshData(array  $args) : array

Find the data needed to refresh a row object's data based upon its primary key value.

Parameters

array $args

Returns

array

createRow()

createRow(array  $data = array(), boolean  $shareFieldObjectsWithRow = self::SHARE_FIELD_OBJECTS_WITH_ROW) : \Dewdrop\Db\Row

Create a new row object, assigning the provided data as its initial state.

By default, rows share the same field objects that were instantiated on the table itself. This makes it easy to customize fields prior to the row being available. However, in some rare cases, you want to edit multiple rows created from the same model instance. To do so, you'll need new field objects per-row. To achieve this separation, you can call this method with Table::NEW_FIELD_OBJECTS_PER_ROW as the second parameter.

Parameters

array $data
boolean $shareFieldObjectsWithRow

Returns

\Dewdrop\Db\Row

fetchRow()

fetchRow(string|\Dewdrop\Db\Select  $sql, array  $bind = array()) : null|\Dewdrop\Db\Row

Fetch a single row by running the provided SQL. If no matching row is found, null will be returned.

Parameters

string|\Dewdrop\Db\Select $sql
array $bind

Returns

null|\Dewdrop\Db\Row

assembleFindWhere()

assembleFindWhere(array  $args) : string

Assemble WHERE clause for for finding a row by its primary key.

Parameters

array $args

The primary key values

Returns

string

augmentInsertedDataArrayWithWhenAndByWhom()

augmentInsertedDataArrayWithWhenAndByWhom(array  $data) : array

If this table has date_created or datetime_created columns, supply a value for them automatically during insert(). It also will assign the current user ID as the creator if possible.

Parameters

array $data

Returns

array

augmentUpdatedDataArrayWithWhenAndByWhom()

augmentUpdatedDataArrayWithWhenAndByWhom(array  $data) : array

If this table has date_updated or datetime_updated columns, supply a value for them automatically during update(). It also will assign the current user ID as the updater if possible.

Parameters

array $data

Returns

array

assembleFindSql()

assembleFindSql(array  $args) : string

Assemble SQL for finding a row by its primary key.

Parameters

array $args

The primary key values

Returns

string

filterDataArrayForPhysicalColumns()

filterDataArrayForPhysicalColumns(array  $data) : array

Filter the data array that was passed to either insert() or update() so that it only has keys that match physical database columns, not many-to-many relationships managed by this table.

Parameters

array $data

Returns

array —

The filtered version of the data array.

saveManyToManyRelationships()

saveManyToManyRelationships(array  $data, integer  $pkeyValue = null) : \Dewdrop\Db\Table

Save any many-to-many relationship values that were passed to insert() or update().

Parameters

array $data
integer $pkeyValue

Returns

\Dewdrop\Db\Table

saveEav()

saveEav(array  $data, integer  $pkeyValue = null) : \Dewdrop\Db\Table

Save any EAV attributes matching keys in the supplied data array. We can only save EAV attributes, if there is a primary key value available, either via the $data array itself or the lastInsertId().

Parameters

array $data
integer $pkeyValue

Returns

\Dewdrop\Db\Table