If you are using the generator to create the application from a model (see Model), all necessary code will be generated automatically.

Database tables

Still the most common storage for web applications is a SQL database (e.g. MySQL). It is also wCMF's default storage. Although not strictly necessary it is recommended to use one database table for each persistent class, where each class property maps to one table column and each row stores one instance. The object identity is stored in the primary key column, which is named id by default.

Note

wCMF uses a table called DBSequence for retrieving the next id value used for insertion, since autoincrement columns are not supported on all database servers.

Primary keys

Primary keys are used to clearly identify an object in the database. They can consist of one (simple) or more (compound) columns. The default name for a primary key column is id. wCMF stores the primary key of an object together with it's type name in an ObjectId instance.

Relations

The following two relations types must be considered, when modeling the data tables:

One-To-Many relations are realized by adding a foreign key column to the child table (many-side), which points to the parent table (one-side). This column is named fk _ + parent table name + _ id by default (e.g. fk_author_id).

Many-To-Many relations between two domain classes, are established by defining a connection table. This table contains two primary keys, which point to the two connected tables.

Persistence Mappers

wCMF uses persistence mapper classes to communicate between the application and the persistent storage (see Architecture). These classes implement the PersistenceMapper interface, which defines methods for all persistence actions. By using this pattern wCMF does not make any assumptions about the actual storage, which can be flat files, a database or anything else a mapper is able to handle. This approach also makes it easy to connect an existing storage to a newly created wCMF application.

To simplify the implementation of mapper classes, wCMF already contains a class hierarchy for a common mapping approach, which maps each concrete class to one database table (Concrete Table Inheritance). In this hierarchy AbstractRDBMapper handles the communication with the relational database, while NodeUnifiedRDBMapper defines the actual mapping rules. Application developers simply need to implement one subclass of NodeUnifiedRDBMapper for each persistent domain class, which declares the mapping of the attributes and relations of that class.

These two classes are completely generic, the actual identity of the domain class - that is the properties and the relations - are defined by the related PersistenceMapper.

So if no additional domain logic is required in the domain class, it would be sufficient to use Node as domain class. But in many cases you will want to execute custom code for Persistence Hooks or Validation and therefor create a custom subclass of Node.

Note

All domain classes, that are created by the generator are Node subclasses.

Persistence Hooks

Persistence hooks are methods that are called at certain points of the lifecycle of an instance. The default implementation of these methods is empty - in fact their sole purpose is to be overwritten in subclasses on order to implement special functionality that should be executed at those points. PersistentObject defines the following persistence hooks:

Tags are a special property used on values to group them by certain aspects. For example the edit forms in the default application only display domain class values that are tagged with DATATYPE_ATTRIBUTE and only those attributes are editable in the translation form that are tagged with TRANSLATABLE. Tags are defined in the model using the tagapp_data_type (see ChiValue).

Configuration

Entry point of configuring the persistence layer is PersistenceFacade (see Usage). The configuration mainly tells the facade which mapper classes are responsible for which domain classes. This assignment is defined in the TypeMapping configuration section. The following example shows the appropriate entries for the Author domain class:

1 [PersistenceFacade]

2 __class = wcmf\lib\persistence\impl\DefaultPersistenceFacade

3 mappers = $typeMapping

4 logging = false

5 logStrategy = $auditingLogStragegy

6

7 [AuditingLogStragegy]

8 __class = wcmf\lib\persistence\output\impl\AuditingOutputStrategy

9

10 [TypeMapping]

11 app.src.model.Author = $app_src_model_AuthorRDBMapper

12

13 [app_src_model_AuthorRDBMapper]

14 __class = app\src\model\AuthorRDBMapper

15 connectionParams = $database

16

17 [Database]

18 dbType = sqlite

19 dbHostName = 127.0.0.1

20 dbName = app/test-db.sq3

21 dbUserName =

22 dbPassword =

23 dbCharSet = utf8

Usage

PersistenceFacade is the main entry point to the persistence layer. It is used to create and retrieve PersistentObject instances. The following sections show some basic examples for using the persistence layer.

This PersistenceFacade::loadObjects method provides several parameters that allow to specify which instances should be loaded and how the list should be ordered. The next sections explain these parameters.

Build depth

When loading objects we generally distinguish between eager and lazy loading (see Lazy loading). By default PersistenceFacade performs lazy loading by using virtual proxies (instances of PersistentObjectProxy). That means that related objects are retrieved from the store, only when they are actually accessed. To perform eager loading, a BuildDepth value may be passed in the method calls:

$oid = new ObjectId('Author', 1);

// load the Author instance with id 1 together with all related objects

In this example the Author instance with id 1 is loaded together with all related objects recursively.

Instead of a BuildDepth value, an integer number may be passed indicating the depth of relations to load. The following image illustrates the build depth parameter for a simple model.

Build depth

If using a build depth value of 1 the Author instance Author A will be loaded together with it's related Articles instances (Article A, Article B). A value of 2 will also load the Chapter instances (Chapter A1, Chapter A2). The default value is BuildDepth::SINGLE, which means that only the Author A instance is loaded. In the above illustration the value of 2 is equal to passing BuildDepth::INFINITE.

A list of already loaded Node instances may be sorted by using NodeComparator in the following way:

$nodeList = [...];

// set up a comparator for node type and created date

$sortCriteria = [

NodeComparator::ATTRIB_TYPE => NodeComparator::SORTTYPE_ASC,

'created' => NodeComparator::SORTTYPE_DESC

];

$comparator = new NodeComparator($sortCriteria);

// sort node list

usort($nodeList, [$comparator, 'compare']);

Pagination

To reduce the response time of your application when displaying large lists of objects, pagination may be used. This technique splits the list into smaller parts (pages) that are displayed one by one. In wCMF the class PagingInfo implements the concept.

The following code shows how to load 25Author instances starting from position 50:

PersistentIterator allows to traverse object graphs as well, but it's state may be persisted to split the iteration of large lists into smaller parts.

// traverse 10 nodes starting from $oid

$counter = 0;

$it = new PersistentIterator($oid);

while($it->valid() && $counter < 10) {

echo "current object: ".$it->currentNode();

$it->next();

$counter++;

}

// save iterator state in the session

$iterId = $it->save();

// load the iterator state later and traverse the remaining nodes

$it = PersistentIterator::load($iterId);

while($it->valid()) {

echo "current object: ".$it->currentNode();

$it->next();

}

Creating / Modifying objects

Domain class instances are created by calling the PersistenceFacade::create method or simply the class constructor, where the first approach is preferred over the second because it also sets the default values on attributes.

Changes on instances are persisted automatically, when the current transaction is committed (see Transactions). Objects are removed from the store by calling the PersistentObject::delete method.

Validation types

The actual validation is delegated to the Validator::validate method, which gets a validation description string passed. This string defines a single ValidateType or a combination of those. The ValidateType::validate method accepts an associative array of configuration options, that is encoded into a JSON string when being used in the validation description string. An additional validation context might be passed to the method (e.g. the entity instance and the currently validated entity attribute), when validation entity values.

To define which validation should be applied to a domain class attribute, the tagrestrictions_match is used in the model (see ChiValue).

Currently the following validation types exist (the examples show their usage in a validation description string):

Unique checks if the value is unique regarding the given entity attribute e.g.

// explicitly define Keyword.name as being unique ...

unique:{"type":"Keyword","value":"name"}

// ... or implicitly when used in the entity validation context of the Keyword.name

unique

Note

The validation type is derived from the part of the configuration string, that precedes the first colon.

Custom validation types may be added in the configuration. For example after adding myValidator (implemented in MyValidator class):

1 [Validators]

2 regexp = $regexpValidator

3 filter = $filterValidator

4 image = $imageValidator

5 myValidator = $myValidator

6

7 [MyValidator]

8 __class = path\to\MyValidator

it may be used in the following way:

myValidator:custom_configuration_string_passed_by_MyValidator

Complex validation

The described validation types only operate on one attribute. If more complex validation is required, e.g. if dependencies between several attributes exist, the method PersistentObject::validateValue may be overriden in the appropriate domain class.

Concurrency

When two or more users try to access the same object at the same time problems like lost updates might occur. These issues are avoided by concurrency control mechanisms, typically object locking.

Locking

wCMF provides two locking strategies:

Pessimistic locking: An explicit lock is obtained by one user, that blocks write access to the object for other users until the lock is released.

Optimistic locking: A copy of the initial object data is stored for each user and checked against later, when the user tries to store the object. The operation fails, if another user has updated the object data in the meantime.

Even if not obtained explicitely, there is always a transaction existing in the background, to which objects loaded from the store are attached. But to persist changes when doing a commit, the transaction has to be set activebefore loading or creating the object.

There are situations where you want to let the current transaction ignore changes made to newly created objects or objects loaded from the store. In these cases you can use the method Transaction::detach to disconnect the object from the transaction.