Fieldcollection

General Usage

Object field collections are predefined sets of data and layout fields, that can be added to objects at an arbitrary amount.

An object field collection is very similar to an object itself. It has a class or in this case field definition which needs to be made first, and then different field collection definitions can be used to add sets of fields to an object.

So with some restrictions you could say, a field collection is an object within an object.

When adding a field collection field to an object's class definition, the developer needs to specify the allowed field definition types for this field.

The user can then decide which and how many of the available field definitions shall be added to the object.

[!IMPORTANT] Review the limitations related to blocks and fieldcollections when creating the data model. More Information about Limitations

Data Storage

Field definition data is stored in a separate table for each field definition and object class. The naming convention for these tables is: object_collection_COLLECTION-NAME_OBJECT-ID. Such a table contains all the field data, the concrete object's id, field name and index of the field collection within the field collection data field. To fully understand the data structure of objects and field collections, enter some example data and inspect the tables created by Pimcore.

Working with PHP API

Set field collection data programmatically as shown below. This example uses an object class collectiontest with a fieldcollection called MyCollection. There is an object field called collectionitems which is of the type field collection.

$object = new DataObject\Collectiontest();
  
$object->setParentId(1);
$object->setUserOwner(1);
$object->setUserModification(1);
$object->setCreationDate(time());
$object->setKey(uniqid() . rand(10, 99));

$items = new DataObject\Fieldcollection();

for ($i = 0; $i < 5; $i++) {
    $item = new DataObject\Fieldcollection\Data\MyCollection();
    $item->setMyinput("This is a test " . $i);
    $items->add($item);
}

$object->setCollectionitems($items);
$object->save();

When using localized fields inside field collections, set the object before calling any localized field-related methods.

$item = new DataObject\Fieldcollection\Data\MyCollection();
$item->setObject($object);

Inheritance

Field collections do not support inheritance out of the box because currently field collection data does not get saved to a query table (so you would not be able to query for inherited data).

Nevertheless, you can use inheritance for field collections for data maintenance by overriding the class which contains the field collection field and adding a custom getter method to this overriding class:

// custom getter for field collection field named 'fieldCollection'
public function getFieldCollection(): mixed
{
    $data = parent::getFieldCollection();

    $inheritedData = DataObject\Service::useInheritedValues(true, function() use ($data) {
        if (\Pimcore\Model\DataObject::doGetInheritedValues($this) && $this->getClass()->getFieldDefinition("fieldCollection")->isEmpty($data)) {
            try {
                return $this->getValueFromParent("fieldCollection");
            } catch (\Pimcore\Model\DataObject\Exception\InheritanceParentNotFoundException $e) {
                // no data from parent available, continue ... 
                return null;
            }
        }
        return null;
    });

    return $inheritedData ?? $data;
}

Beware that only complete field collection containers can be inherited. As soon as you change the order of the field collection items or any field value in a child object, the whole field collection will get assigned to that child object.

There could also be some UI quirks in Pimcore Studio.