pj DataProvider

This package implements the pj DataProvider Framework library under Joomla! CMS. Refer there for detailed description of InfoBase, SearchKey, IDataProvider and MySqlDataProvider.

This documentation is powered by the Dispute component based on the pj DataProvider for Joomla! and pj DataProvider Framework respectively.

Usage:

pj DataProvider Framework package (lib_pj) is an alternative database concept beside of Joomla's JDatabase framework.

The developer designs new classes extending the InfoBase class and registers them at start-up in the singleton DataProviderBase instance. It is not necessary to add any code to bare class declarations, although it is convenient to outsource specific functionality there.

The framework offers full database access for registered InfoBase classes, including retrieving by ID or by queries passed either as string or as SearchKey structure. It recognizes changes of instance data and inserts, updates and deletes instances together with corresponding table rows, optionally in nested transactions. It ensures that at any time, there exists just one unique instance of InfoBase extending class corresponding to one database table row.

The developer has to write an extension of the DataProviderBase class and outsource his/her business layer functions there.

 
DataProviderBase

Encapsulates interface to the actual database.

The DataProviderBase class is located in the file /libraries/pj/DataProvider.php. It implements several concepts:

  • It is the interface between Joomla! CMS and the actual DataProvider (MySqlDataProvider only implemented yet). It reads connection settings from JFactory::getConfig(), instantiates the DataProvider, opens database connection and registers several basic Joomla! and PJ classes1;
  • intermediates general DataProvider functions like retrieving tables and fields information and executing queries;
  • implements basic handling functions for counting, retrieving, listing, updating and deleting of InfoBase objects;
  • implements recursive transaction mechanism;
  • implements the concept of PJVisitorInfo;
  • provides base for development of extension and module specific Joomla! DataProvider classes.

The DataProviderBase class isn't intended for instantiating itself. Instead, the extending class should declare a static instance() function creating a singleton instance. See DataProviderBase API and DataProviderBase Example for further details.

1 The basic registered Joomla! classes are UserInfo, UserProfileInfo, MenuInfo, ModuleInfo, ModuleMenuInfo and ExtensionInfo. Other defined, yet not registered Joomla! classes are CategoryInfo, ContentInfo and LanguageInfo. All predefined Joomla! classes are located in the file /libraries/pj/JoomlaInfo.php. Registered PJ classes are PJVisitorInfo and PJVisitorTcpipInfo, both located in the file /libraries/pj/VisitorInfo.php.

 
DataProviderBase API

DataProviderBase basic functions
protected function __construct (array $knownTables = null, $omit = false)

Protected constructor instantiates DataProvider and opens connection to the Joomla! database.

$knownTables : array ($className => $tableName). If provided, the constructor registers association of classes with tables.

$omit: skips the registering of predefined basic Joomla! and PjVisitor classes. These are: UserInfo, UserProfileInfo, MenuInfo, ModuleInfo, ModuleMenuInfo, ExtensionInfo, PJVisitorInfo, and PJVisitorTcpipInfo.

The DataProviderBase class isn't intended for instantiating. Instead, the enhancing class should declare a static instance () function creating and returning a singleton instance. See DataProviderBase Example for more info.

Throws DataProviderException with error number and description if opening the connection failed.
function GetTables () Returns array of all database table names
function ExecuteQuery ($query, array $args = null)

Executes database query $query replacing its arguments with $args values.

Returns raw database engine response without any interpretation of the content.

Throws DataProviderException if there's no connection.
Throws DataProviderException with resolved query and error description on underlying database engine errors.
Throws underlying database exceptions.
function ExecuteScalar ($query, array $args = null)

Executes database query $query replacing its arguments with $args values.

Throws DataProviderException if there's no connection.
Throws DataProviderException with resolved query and error description on database engine errors.
static function IsAdmin ($assetname, PjVisitorInfo $visitor = null)

Returns true if current user or $visitor respectively has administrator rights for $assetname.

See also PJVisitorInfo.

DataProviderBase register functions
function IsClassRegistered ($cls)

Returns table name associated with the class or false if not registered.

$cls: class name or class instance
function RegisterClass ($cls, $tableName)

Registers the association between $cls and the underlying database table. Ignored if the class is already registered.

$cls: class name or class instance
$tableName: name of the associated table (without event. prefix)

Throws DataProviderException if there's no connection.
function UnregisterClass ($cls)

Removes the association between $cls and the underlying database table.

$cls: class name or class instance

DataProviderBase InfoBase functions
function GetItem ($cls, $id, $forceRetrieve = false)

Returns the $cls instance by its ID or null if it doesn't exists.

$cls: class name or class instance
$id: unique table row identifier of whatever type
$forceRetrieve: sets whether an existing instance's $data should be re-retrieved and $isDirty reset.

Throws DataProviderException if there's no connection.
Throws DataProviderException if $cls isn't registered.
Throws underlying database exceptions.
function CountItems ($cls, $select = null)

Returns the count of $cls (name or instance) rows selected by $select.

$select: SQL string or a SearchKey structure. If string, tokens "#_" are replaced by dbprefix. If not provided, the function returns total count of the underlying table rows.

Throws DataProviderException if there's no connection.
Throws DataProviderException if $cls isn't registered.
function ListItems ($cls, $select = null, $orderBy = null, array $fields = null, $startPos = -1, $count = PHP_INT_MAX)

Returns an array of $cls instances selected by $select and ordered by $orderBy. Already retrieved instances are not overwritten.

$cls: class name or class instance;

$select: SQL string or a SearchKey structure. If string, tokens "#_" are replaced by dbprefix and the rest of arguments is ignored. If not provided, the function returns all $cls instances from the underlying table.

$orderBy: if provided, it contains one or more sorting field names separated by comma or collected in an array.

$fields: if provided, it limits $cls retrieved fields. The table's primary id field will be included anyway. Instances previously or subsequently retrieved otherwise contain full field set.

$count: Limits the number of instances retrieved starting at $startPos (zero based). If $startPos < 0, both arguments are ignored.

Throws DataProviderException if there's no connection.
Throws DataProviderException if $cls isn't registered.
Throws DataProviderException if $select is of other type than string, SearchKey or null.
Throws underlying database exceptions.
function ListIDs ($cls, $select = null, $orderBy = null)

Returns an array of $cls's table primary keys of whatever type selected by $select and ordered by $orderBy. Returns an empty array if the table has no primary key.

$cls: class name or class instance;

$select: SQL string or a SearchKey structure. If string, tokens "#_" are replaced by dbprefix and the rest of arguments is ignored. If not provided, the function returns all primary keys from the underlying table.

$orderBy: if provided, it contains one or more sorting field names separated by comma or collected in an array.

Throws DataProviderException if there's no connection.
Throws DataProviderException if $cls isn't registered.
Throws DataProviderException if $select is of other type than string, SearchKey or null.
Throws underlying database exceptions.
function UpdateItem (InfoBase $item)

Inserts or updates values from $item->data array into the database table row.

When inserting new row, the $item->ID() is set to the row's unique identifier.

The $item->isDirty is reset.

Throws DataProviderException if there's no connection.
Throws DataProviderException if $cls isn't registered.
Throws underlying database exceptions.
function DeleteItem (InfoBase $item)

Deletes the item's corresponding row from the underlying database table. The $item instance remains, but subsequent calls to UpdateItem have no effect.

Throws DataProviderException if there's no connection.
Throws DataProviderException if the $item class isn't registered.
Throws underlying database exceptions.
function DeleteItems ($cls, $select)

Deletes items' corresponding rows from the underlying database table. Eventual class instances remain, but subsequent calls to UpdateItem have no effect.

$cls: class name or class instance
$select: one of

  • SearchKey
  • Array of either IDs or $cls class instances (mixing allowed). For tables having no singular primary key, only instances are allowed;
  • String containing the SQL WHERE specification (like id IN (10,11,12) OR crit_id IS NULL)

Throws DataProviderException if there's no connection.
Throws DataProviderException if $cls isn't registered.
Throws DataProviderException if the $select is of improper data type or if $select array contains other elements types then integers (tables with singular primary key) or appropriate InfoBase instance.
Throws underlying database exceptions.

DataProviderBase Transaction functions
function BeginTransaction ()

Begins the database transaction mode and returns a transaction variable used for subsequent call to either CommitTransaction() or RollbackTransaction().

BeginTransaction can be called from inside a transaction block recursively, but on each level, it must terminate by either CommitTransaction() or RollbackTransaction() with the corresponding transaction variable. Only the topmost level block actually begins and terminates the underlying database transaction.

Throws DataProviderException if there's no connection.
Throws DataProviderException if called from inside a transaction block already rolled back.
Throws underlying database exceptions.
function CommitTransaction ($trans)

Commits the transaction $trans returned by previous call to BeginTransaction.

If called recursively, only the topmost level block actually commits the underlying database transaction.

Throws DataProviderException if there's no connection.
Throws DataProviderException if calledfrom inside a transaction block already rolled back.
Throws DataProviderException if $trans doesn't correspond with current recursion level (i.e. nested transaction wasn't terminated).
Throws underlying database exceptions.
function RollbackTransaction ($trans)

Rolls back the transaction $trans returned by previous call to BeginTransaction.

If called recursively, only the topmost level block actually rolls back the underlying database transaction.

After rollback, all updated InfoBase's data are reset to the state as they entered the Update call. This ensures that ID field of new item has its previous value and its isNew() is set.

Throws DataProviderException if there's no connection.
Throws DataProviderException if $trans doesn't correspond with current recursion level (i.e. nested transaction wasn't terminated).
Throws underlying database exceptions.
 
DataProviderBase Example
 
ScriptProvider
 
PJVisitorInfo
 
UTF8Helper
 
PjTools