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

Represents one database table row. The framework ensures that there's all time only one single instance of InfoBase class for one data row, even after repeated retry.

InfoBase class is located in the file /libraries/pj/data/InfoBase.php.

The key property is the member array $data, which is dynamically filled by fields from the underlying database table row when retrieved and written to the row when inserted or updated. The __get ($name) and __set ($name) functions access named elements of this array. Further more, the setter function checks whether the new value differs from the current one and sets the $isDirty flag if so.

Classes extending InfoBase typically serve as representations of one database table row. Basically, they don't need to implement any code but an empty class declaration.

It is necessary to register associations between the class and the underlying table before first database operation occurs, preferably at application start-up. Class instances can be retrieved from the database individually by their ID or in batch by queries passed either as a string or as a SearchKey structure.

See InfoBase API and InfoBase Examples for further details.

 
InfoBase API

InfoBase Properties
$data

Array (named keys) of instance's data, through __get ($ name) and __set ($name) accessible as instance's properties.

$data array is filled with column names and values when the instance is retrieved from the underlying database row.
$isDirty

Flag signaling that $data has been changed. Read and write.

$isDirty is set by instantiating or by setting $data different from the original value. It is reset when the instance is retrieved from the database or when it has been updated to the underlying table row.

InfoBase Methods
__construct ()

There is no constructor in the base class. Constructors in extending classes expecting arguments must provide default values for all of them.

It is recommended to implement constructor in extending classes in order to

  • setting the unique identifier field name as the first $data element (see ID() function);
  • providing default values for table fields not allowing null;
  • setting initial values and conditions like created etc.

The constructor is useful when new instances are to be inserted into the database. When retrieved, $data set by constructor will be overwritten.
ID ()

The instance's ID. Read only.

The base class assumes that the instance contains an unique identifier in the first data element corresponding to the first column of the underlying table. If it's not the case, either overwrite the ID() function, or in the constructor, set dummy value (null, 0) as first element with actual ID field name key.

Tables with no unique row identifier can be used with compromised functionality, more or less just for retrieving or inserting of new rows. It is recommended to implement at least some kind of ID () function (e.g. timestamp) to enable distinguishing between various instances.
IsNew ()

Returns true if the instance was not saved yet. Read only.

The base class implementation relies on ID () function and returns true if it is null or <= 0.

Negative ID ()s, still recognized as IsNew (), enable clusters of new related instances. First at save time, negative identifiers and relations shall be replaced by actual values.
Update (array $newData)

Updates the instance's $data array by corresponding values from $newData while maintaining the $isDirty flag. Only existing keys are updated.

 

 
InfoBase Examples
 
SearchKey