DataSource

The DataSource component allows unified access to different kinds of data. It is used by DataAccess which provides security and output modules to access data as a RESTful API.

Structure

A DataSource consists of an identifier and a type. Together they identify the underlying source to get data from. Additionally some options can be set. A DataSource basically provides the following methods:

• get(array $elementId = array(), array $filter = array(), array $order = array(), int $limit = 0, int $offset = 0, array $fieldList = array())
• add(array $data)
• update(array $elementId, array $data)
• remove(array $elementId)

Therefore all CRUD-operations are possible through fully implemented DataSources. Additionally, if supported by the DataSource type, it can filter, sort and limit.

An element is identified by a set of key/value pairs. This for example allows using composite keys for database sources.

Filter

Filter is a two dimensional array as follows: array(<field> => array(<operation> => <value>))

• <field> is the DataSource field to apply the filter to.
• <operation> is one of the operations listed in the following table. Not all DataSources support all operations.
• <value> is the value the operation compares with the field.

If multiple filters are applied, only elements that match all filters are returned.

Operation	Name	Description	Supported DataSource types
eq	Equals	Field must be equal to <value>	All
lt	Lower than	Field value needs to be lower than <value>	DoctrineRepository
gt	Greater than	Field value needs to be greater than <value>	DoctrineRepository
lte	Lower than or equal	Field value needs to be lower than or equal to <value>	DoctrineRepository
gte	Greater than or equal	Field value needs to be greater than or equal to <value>	DoctrineRepository
in	In	Field value needs to be one of the comma separated values in <value>	DoctrineRepository
not	Not	Field value must not be equal to <value>	DoctrineRepository

DataSource types

The following types are available. Some only provide limited support for some features:

DoctrineRepository

Allows full CRUD access to Doctrine repositories.

LegacyDatabaseRepository

Allows read-only access to non-Doctrine (/legacy) database tables.

JsonDataSource

Allows access to JsonData adapters. Not implemented yet.

YmlRepository

Allows full CRUD access to YamlRepositories. Not implemented yet.

MediaSource

Allows full CRUD access to MediaSources. This is only partially implemented: get, add, remove and update work. Chunked upload does not yet work. Parallel upload do work yet. This is currently BETA.

For more info about what this can be used for, see MediaSource.

Options

Options are a PHP serialized array.

Recursion

By default no associated entities are added to the result.

If the flag "recurse" is set to "true", all relations of type "many to many" and "* to one" are followed and added to the result.

Additionally the options "forcedRecursions" and "skippedRecursions" can be used to follow "one to many" relations or to skip individual relations. Relations need to be specified as a chain of relation field names split by a colon.

Example: To allow recursions on the entity \Cx\Core\User\Model\Entity\UserAttributeValue but not show user's groups you need to specify the following:

array(
    'recurse' => true,
    'skippedRecursions' => array('user.groups')
);

// this leads to the following serialized value to put in the database field <code>options</code>
'a:2:{s:7:"recurse";b:1;s:17:"skippedRecursions";a:1:{i:0;s:11:"user.groups";}}';

The following table shows the current behavior if recursion is turned on or off without any skipped or forced recursions:

Relation	Non-recursive read	Non-recursive write	Recursive read	Recursive write
1:1	skipped	set existing entry if owning side only	followed	not yet possible
1:n	skipped	ignored	skipped	not yet possible
n:1	skipped	set existing entry only	followed	not yet possible
m:n	skipped	set existing entries only	followed	not yet possible

Limitation: Recursion is currently only suppored by the DataSource type DoctrineRepository.

Date and time format handling

Compound formats are returned as ISO 8601. Date without time are returned in the form "YYYY-MM-DD", time without date is returned in the form "HH:MM:SS".

Currently the dates are returned in the system's default user timezone.