pj DataProvider Framework

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

Basic Concepts:

  • The pj DataProvider is a general usage framework usable in any PHP environment;
  • IDataProvider defines a function set the actual database engine interface must provide;
  • MySqlDataProvider is the IDataProvider layer to the MySql database engine (mysqli).
    Other database layers have only to be developed (e.g. PostgreDataProvider, SqlServerDataProvider, OracleDataProvider etc.) and implemented in the place of MySqlDataProvider with no effects for the application code itself;
  • InfoBase, representing one single database table row, is a base class for extension's classes with specific functionality related to application's database tables.

Usage:

The developer writes own DataProvider class, which instantiates and opens a singleton IDataProvider database connection (MySqlDataProvider) and eventually implemments specific business layer functions.

Then, he/she designs business layer classes extending InfoBase corresponding to the database model and registers them at start-up in the DataProvider. It is not necessary to add any code to bare class declaration, 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 by string or by 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 at most one unique instance of InfoBase class representing one database table row.

 
IDataProvider
 
MySqlDataProvider
 
InfoBase
 
SearchKey

Abstract database query construct.

SearchKey class, together with RelatedKey and SearchRelation classes, are located in the file /libraries/pj/data/SearchKey.php.

The groundwork is based on three member variables: field, value and comparator, representing one simple query condition performed on one database table. Optionally, the member variable orderBy may set the result ordering.

More SearchKey instances can be dynamically chained to a complex query using member variables andKey and orKey, which may contain further SearchKey conditions themselves and so on. Thus it is possible to construct a query of unlimited complexity, passed by just one single root SearchKey instance. Functions AddAndKey (SearchKey $key) and AddOrKey (SearchKey $key) help by creation as they care for chaining the $key on the end of the chain.

RelatedKey class enhances the SearchKey for queries on related database tables.

See SearchKey Properties, Methods and Examples for more details.

 
SearchKey Properties, Methods and Examples

SearchKey Properties
$field

Database table field name

If $field is empty, the condition itself is ignored. The rest of properties is evaluated, anyway.
$value

Value to be compared

Value type should correspond to the database field type, although simple conversions are performed automatically.

String values may contain wildcard character "∗", defined as SearchKey::STRING_WILDCARD constant. These have effect when combined with comparators SearchKey::CMP_LIKE or SearchKey::CMP_NOTLIKE.

A special case is value of type array(). Together with SearchKey::CMP_EQUAL or SearchKey::CMP_NOTEQUAL comparator, it is interpreted as SQL "[field name] IN (...)" or "NOT [field name] IN (...)" respectively.

An empty array will be interpreted as "IN (0)". Handle this case in the caller's code if it is not convenient for you.
$comparator

field : value comparator, one of following constants:

SearchKey::CMP_EQUAL = 0 (default)
SearchKey::CMP_LESS = 1
SearchKey::CMP_LESSEQUAL = 2
SearchKey::CMP_GREATER = 3
SearchKey::CMP_GREATEREQUAL = 4
SearchKey::CMP_NOTEQUAL = 5
SearchKey::CMP_LIKE = 6 (string values only)
SearchKey::CMP_NOTLIKE = 7 (string values only)
$orderBy

Optional ordering field like "created" or "created desc". May also contain expressions like "COUNT(DISTINCT mark_id) desc".

More ordering fields may be concatenated either by comas or in an array.

Multiple $orderBy ordering is given by the SearchKey structure and maybe does not fit the ordering desired. Therefore, it is possible to fix it by explicite setting the $orderBy position like "(1)name", "(2)created desc" etc.
$andKey

Optional another SearchKey related with SQL "AND"
$orKey

Optional another SearchKey related with SQL "OR"

SearchKey Methods
function __construct ($field = '', $value = 0, $cmp = self::CMP_EQUAL, $partial = false)

Constructor

Arguments $field, $value and $cmp set corresponding fields.

The argument $partial is used together with string values and if true, it inserts SearchKey::STRING_WILDCARD before and after the value.
function AddAndKey (SearchKey $key)

Inserts the $key as the last element of the andKey chain
function AddOrKey (SearchKey $key)

Inserts the $key as the last element of the orKey chain

Examples:

(assumed interpretation by MySqlDataProvider)
$key = new SearchKey('occurrence');

interprets to "WHERE 'occurrence'=0"
$key = new SearchKey('created', '2017-01-25 01:30', SearchKey::CMP_GREATEREQUAL);

Case field 'created' is of MySql type

  • date: interprets to "WHERE `created`=>'2017-1-25'"
  • time: interprets to "WHERE `created`=>'01:30:00'"
  • datetime: interprets to "WHERE `created`=>'2017-1-25 01:30:00'"
$key = new SearchKey('id', array(22,28,46)); interprets to "WHERE `id` IN (22,28,46)"

$key1 = new SearchKey('name', 'ann', SearchKey::LIKE, true);

$key1->AddOrKey(new SearchKey('name', 'john', SearchKey::LIKE));

$key = new SearchKey('age', 18, SearchKey::CMP_GREATEREQUAL);

$key->AddAndKey($key1);

$key->orderBy = 'name, age desc';

 $key interprets to "WHERE `age` >=18 AND (`name` LIKE '%ann%" OR `name` LIKE 'john') ORDER BY `name`, `age` desc"

 

 
RelatedKey