class Table extends JObject implements JObservableInterface, JTableInterface

Abstract Table class

Parent class to all tables.

Methods

__construct( string $table, mixed $key, JDatabaseDriver $db)

Object constructor to set table and key fields. In most cases this will be overridden by child classes to explicitly set the table and key fields for a particular database table.

void
attachObserver( JObserverInterface $observer)

Implement \JObservableInterface: Adds an observer to this instance.

JTableObserver|null
getObserverOfClass( string $observerClass)

Gets the instance of the observer of class $observerClass

mixed
getFields( bool $reload = false)

Get the columns from database table.

static  Table|boolean
getInstance( string $type, string $prefix = 'JTable', array $config = array())

Static method to get an instance of a Table class if it can be found in the table include paths.

static  array
addIncludePath( array|string $path = null)

Add a filesystem path where Table should search for table class files.

void
appendPrimaryKeys( JDatabaseQuery $query, mixed $pk = null)

Method to append the primary keys for this table to a query.

string
getTableName()

Method to get the database table name for the class.

mixed
getKeyName( boolean $multiple = false)

Method to get the primary key field name for the table.

getDbo()

Method to get the \JDatabaseDriver object.

boolean
setDbo( JDatabaseDriver $db)

Method to set the \JDatabaseDriver object.

void
setRules( mixed $input)

Method to set rules for the record.

JAccessRules
getRules()

Method to get the rules for the record.

void
reset()

Method to reset class properties to the defaults set in the class definition. It will ignore the primary key as well as any private class properties (except $_errors).

boolean
bind( array|object $src, array|string $ignore = array())

Method to bind an associative array or object to the Table instance.This method only binds properties that are publicly accessible and optionally takes an array of properties to ignore when binding.

boolean
load( mixed $keys = null, boolean $reset = true)

Method to load a row from the database by primary key and bind the fields to the Table instance properties.

boolean
check()

Method to perform sanity checks on the Table instance properties to ensure they are safe to store in the database.

boolean
store( boolean $updateNulls = false)

Method to store a row in the database from the Table instance properties.

boolean
save( array|object $src, string $orderingFilter = '', array|string $ignore = '')

Method to provide a shortcut to binding, checking and storing a Table instance to the database table.

boolean
delete( mixed $pk = null)

Method to delete a row from the database table by primary key value.

boolean
checkOut( integer $userId, mixed $pk = null)

Method to check a row out if the necessary properties/fields exist.

boolean
checkIn( mixed $pk = null)

Method to check a row in if the necessary properties/fields exist.

boolean
hasPrimaryKey()

Validate that the primary key has been set.

boolean
hit( mixed $pk = null)

Method to increment the hits for a row if the necessary property/field exists.

boolean
isCheckedOut( integer $with, integer $against = null)

Method to determine if a row is checked out and therefore uneditable by a user.

integer
getNextOrder( string $where = '')

Method to get the next ordering value for a group of rows defined by an SQL WHERE clause.

array
getPrimaryKey( array $keys = array())

Get the primary key values for this table using passed in values as a default.

mixed
reorder( string $where = '')

Method to compact the ordering values of rows in a group of rows defined by an SQL WHERE clause.

boolean
move( integer $delta, string $where = '')

Method to move a row in the ordering sequence of a group of rows defined by an SQL WHERE clause.

boolean
publish( mixed $pks = null, integer $state = 1, integer $userId)

Method to set the publishing state for a row or list of rows in the database table.

string
getColumnAlias( string $column)

Method to return the real name of a "special" column such as ordering, hits, published etc etc. In this way you are free to follow your db naming convention and use the built in \Joomla functions.

void
setColumnAlias( string $column, string $columnAlias)

Method to register a column alias for a "special" column.

Details

__construct( string $table, mixed $key, JDatabaseDriver $db)

Object constructor to set table and key fields. In most cases this will be overridden by child classes to explicitly set the table and key fields for a particular database table.

Parameters

string $table Name of the table to model.
mixed $key Name of the primary key field in the table or array of field names that compose the primary key.
JDatabaseDriver $db \JDatabaseDriver object.

void attachObserver( JObserverInterface $observer)

Implement \JObservableInterface: Adds an observer to this instance.

This method will be called fron the constructor of classes implementing \JObserverInterface which is instanciated by the constructor of $this with \JObserverMapper::attachAllObservers($this)

Parameters

JObserverInterface $observer The observer to attach to $this observable subject

Return Value

void

JTableObserver|null getObserverOfClass( string $observerClass)

Gets the instance of the observer of class $observerClass

Parameters

string $observerClass The observer class-name to return the object of

Return Value

JTableObserver|null

mixed getFields( bool $reload = false)

Get the columns from database table.

Parameters

bool $reload flag to reload cache

Return Value

mixed An array of the field names, or false if an error occurs.

Exceptions

UnexpectedValueException

static Table|boolean getInstance( string $type, string $prefix = 'JTable', array $config = array())

Static method to get an instance of a Table class if it can be found in the table include paths.

To add include paths for searching for Table classes see Table::addIncludePath().

Parameters

string $type The type (name) of the Table class to get an instance of.
string $prefix An optional prefix for the table class name.
array $config An optional array of configuration values for the Table object.

Return Value

Table|boolean A Table object if found or boolean false on failure.

static array addIncludePath( array|string $path = null)

Add a filesystem path where Table should search for table class files.

Parameters

array|string $path A filesystem path or array of filesystem paths to add.

Return Value

array An array of filesystem paths to find Table classes in.

void appendPrimaryKeys( JDatabaseQuery $query, mixed $pk = null)

Method to append the primary keys for this table to a query.

Parameters

JDatabaseQuery $query A query object to append.
mixed $pk Optional primary key parameter.

Return Value

void

string getTableName()

Method to get the database table name for the class.

Return Value

string The name of the database table being modeled.

mixed getKeyName( boolean $multiple = false)

Method to get the primary key field name for the table.

Parameters

boolean $multiple True to return all primary keys (as an array) or false to return just the first one (as a string).

Return Value

mixed Array of primary key field names or string containing the first primary key field.

JDatabaseDriver getDbo()

Method to get the \JDatabaseDriver object.

Return Value

JDatabaseDriver The internal database driver object.

boolean setDbo( JDatabaseDriver $db)

Method to set the \JDatabaseDriver object.

Parameters

JDatabaseDriver $db A \JDatabaseDriver object to be used by the table object.

Return Value

boolean True on success.

void setRules( mixed $input)

Method to set rules for the record.

Parameters

mixed $input A \JAccessRules object, JSON string, or array.

Return Value

void

JAccessRules getRules()

Method to get the rules for the record.

Return Value

JAccessRules object

void reset()

Method to reset class properties to the defaults set in the class definition. It will ignore the primary key as well as any private class properties (except $_errors).

Return Value

void

boolean bind( array|object $src, array|string $ignore = array())

Method to bind an associative array or object to the Table instance.This method only binds properties that are publicly accessible and optionally takes an array of properties to ignore when binding.

Parameters

array|object $src An associative array or object to bind to the Table instance.
array|string $ignore An optional array or space separated list of properties to ignore while binding.

Return Value

boolean True on success.

Exceptions

InvalidArgumentException

boolean load( mixed $keys = null, boolean $reset = true)

Method to load a row from the database by primary key and bind the fields to the Table instance properties.

Parameters

mixed $keys An optional primary key value to load the row by, or an array of fields to match. If not set the instance property value is used.
boolean $reset True to reset the default values before loading the new row.

Return Value

boolean True if successful. False if row not found.

Exceptions

InvalidArgumentException
RuntimeException
UnexpectedValueException

boolean check()

Method to perform sanity checks on the Table instance properties to ensure they are safe to store in the database.

Child classes should override this method to make sure the data they are storing in the database is safe and as expected before storage.

Return Value

boolean True if the instance is sane and able to be stored in the database.

boolean store( boolean $updateNulls = false)

Method to store a row in the database from the Table instance properties.

If a primary key value is set the row with that primary key value will be updated with the instance property values. If no primary key value is set a new row will be inserted into the database with the properties from the Table instance.

Parameters

boolean $updateNulls True to update fields even if they are null.

Return Value

boolean True on success.

boolean save( array|object $src, string $orderingFilter = '', array|string $ignore = '')

Method to provide a shortcut to binding, checking and storing a Table instance to the database table.

The method will check a row in once the data has been stored and if an ordering filter is present will attempt to reorder the table rows based on the filter. The ordering filter is an instance property name. The rows that will be reordered are those whose value matches the Table instance for the property specified.

Parameters

array|object $src An associative array or object to bind to the Table instance.
string $orderingFilter Filter for the order updating
array|string $ignore An optional array or space separated list of properties to ignore while binding.

Return Value

boolean True on success.

boolean delete( mixed $pk = null)

Method to delete a row from the database table by primary key value.

Parameters

mixed $pk An optional primary key value to delete. If not set the instance property value is used.

Return Value

boolean True on success.

Exceptions

UnexpectedValueException

boolean checkOut( integer $userId, mixed $pk = null)

Method to check a row out if the necessary properties/fields exist.

To prevent race conditions while editing rows in a database, a row can be checked out if the fields 'checkedout' and 'checkedout_time' are available. While a row is checked out, any attempt to store the row by a user other than the one who checked the row out should be held until the row is checked in again.

Parameters

integer $userId The Id of the user checking out the row.
mixed $pk An optional primary key value to check out. If not set the instance property value is used.

Return Value

boolean True on success.

Exceptions

UnexpectedValueException

boolean checkIn( mixed $pk = null)

Method to check a row in if the necessary properties/fields exist.

Checking a row in will allow other users the ability to edit the row.

Parameters

mixed $pk An optional primary key value to check out. If not set the instance property value is used.

Return Value

boolean True on success.

Exceptions

UnexpectedValueException

boolean hasPrimaryKey()

Validate that the primary key has been set.

Return Value

boolean True if the primary key(s) have been set.

boolean hit( mixed $pk = null)

Method to increment the hits for a row if the necessary property/field exists.

Parameters

mixed $pk An optional primary key value to increment. If not set the instance property value is used.

Return Value

boolean True on success.

Exceptions

UnexpectedValueException

boolean isCheckedOut( integer $with, integer $against = null)

Method to determine if a row is checked out and therefore uneditable by a user.

If the row is checked out by the same user, then it is considered not checked out -- as the user can still edit it.

Parameters

integer $with The user ID to preform the match with, if an item is checked out by this user the function will return false.
integer $against The user ID to perform the match against when the function is used as a static function.

Return Value

boolean True if checked out.

integer getNextOrder( string $where = '')

Method to get the next ordering value for a group of rows defined by an SQL WHERE clause.

This is useful for placing a new item last in a group of items in the table.

Parameters

string $where WHERE clause to use for selecting the MAX(ordering) for the table.

Return Value

integer The next ordering value.

Exceptions

UnexpectedValueException

array getPrimaryKey( array $keys = array())

Get the primary key values for this table using passed in values as a default.

Parameters

array $keys Optional primary key values to use.

Return Value

array An array of primary key names and values.

mixed reorder( string $where = '')

Method to compact the ordering values of rows in a group of rows defined by an SQL WHERE clause.

Parameters

string $where WHERE clause to use for limiting the selection of rows to compact the ordering values.

Return Value

mixed Boolean True on success.

Exceptions

UnexpectedValueException

boolean move( integer $delta, string $where = '')

Method to move a row in the ordering sequence of a group of rows defined by an SQL WHERE clause.

Negative numbers move the row up in the sequence and positive numbers move it down.

Parameters

integer $delta The direction and magnitude to move the row in the ordering sequence.
string $where WHERE clause to use for limiting the selection of rows to compact the ordering values.

Return Value

boolean True on success.

Exceptions

UnexpectedValueException

boolean publish( mixed $pks = null, integer $state = 1, integer $userId)

Method to set the publishing state for a row or list of rows in the database table.

The method respects checked out rows by other users and will attempt to checkin rows that it can after adjustments are made.

Parameters

mixed $pks An optional array of primary key values to update. If not set the instance property value is used.
integer $state The publishing state. eg. [0 = unpublished, 1 = published]
integer $userId The user ID of the user performing the operation.

Return Value

boolean True on success; false if $pks is empty.

string getColumnAlias( string $column)

Method to return the real name of a "special" column such as ordering, hits, published etc etc. In this way you are free to follow your db naming convention and use the built in \Joomla functions.

Parameters

string $column Name of the "special" column (ie ordering, hits)

Return Value

string The string that identify the special

void setColumnAlias( string $column, string $columnAlias)

Method to register a column alias for a "special" column.

Parameters

string $column The "special" column (ie ordering)
string $columnAlias The real column name (ie foo_ordering)

Return Value

void