Adding data associations

Search…
Overview
In this guide you'll learn how to add associations to your entities. Every possible kind of association will be covered here, so "One to One", "Many to One" or "One to Many" respectively, and "Many to many" associations.
In every example we'll be working with two example entities, that we want to connect with an association: FooEntity and BarEntity.
They are not created in this guide though!
Prerequisites
This guide is built upon the Plugin Base Guide, but any plugin will work here. Just note that all examples are using the plugin mentioned above.
In order to add data associations you need an existing entity, as this guide is based on the Adding custom complex data guide, you should have a look at it first.
Associations
In the following paragraphs, there will be examples for each kind of association. Those are simplified, which means that this guide will not cover how to create entities in the first place. Head over to our guide regarding Adding custom complex data.
Example entity definitions
As already mentioned, this guide will always use the same two example entities for each type of association. They both contain only an ID field, nothing else. For the sake of clarity, here are those example entity definitions:
<plugin root>/src/Core/Content/Bar/BarDefinition.php
1
<?php declare(strict_types=1);
2
​
3
namespace Swag\BasicExample\Core\Content\Bar;
4
​
5
use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
6
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
7
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
8
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
9
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
10
​
11
class BarDefinition extends EntityDefinition
12
{
13
    public const ENTITY_NAME = 'bar';
14
​
15
    public function getEntityName(): string
16
    {
17
        return self::ENTITY_NAME;
18
    }
19
​
20
    protected function defineFields(): FieldCollection
21
    {
22
        return new FieldCollection([
23
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
24
            // Other fields here
25
        ]);
26
    }
27
}
Copied!
<plugin root>/src/Core/Content/Foo/FooDefinition.php
1
<?php declare(strict_types=1);
2
​
3
namespace Swag\BasicExample\Core\Content\Foo;
4
​
5
use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
6
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
7
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
8
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
9
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
10
​
11
class FooDefinition extends EntityDefinition
12
{
13
    public const ENTITY_NAME = 'foo';
14
​
15
    public function getEntityName(): string
16
    {
17
        return self::ENTITY_NAME;
18
    }
19
​
20
    protected function defineFields(): FieldCollection
21
    {
22
        return new FieldCollection([
23
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
24
            // Other fields here
25
        ]);
26
    }
27
}
Copied!
One to One associations
One to One associations require you to define a foreign key for one of the two connected associations. E.g. the bar table has to contain a foo_id column, or the other way around: A bar_id column in the foo table. In this example it will be foo_id in the BarDefinition.
Let's have a look at the defineFields methods of both entity definitions:
<plugin root>/src/Core/Content/Bar/BarDefinition.php
1
protected function defineFields(): FieldCollection
2
{
3
    return new FieldCollection([
4
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
5
        (new FkField('foo_id', 'fooId', FooDefinition::class))->addFlags(new Required()),
6
        (new StringField('name', 'name'))->addFlags(new Required()),
7
​
8
        new OneToOneAssociationField('foo', 'foo_id', 'id', FooDefinition::class, false)
9
    ]);
10
}
Copied!
Note the new FkField, which basically is the mentioned foo_id column. Its parameters are the name of the column in your database(snake_case), the property name in your definition (lowerCamelCase) and the respective definition class.
Additional to that, we've got the OneToOneAssociationField. Here you supply the name of the property, which should contain the associated entity, in your respective definition, e.g. in this case we want the FooDefinition to appear in the foo property of our entity. Following are foo_id, which is the name of the column in the database, id as the ID column in the referenced database (foo in this case) and the referenced definition. The last parameter defines, if you want to automatically load this association every time you load a bar entity. We've set this to false.
For the sake of completion, here is the respective defineFields method of the FooDefinition:
<plugin root>/src/Core/Content/Foo/FooDefinition.php
1
protected function defineFields(): FieldCollection
2
{
3
    return new FieldCollection([
4
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
5
        (new StringField('name', 'name'))->addFlags(new Required()),
6
​
7
        (new OneToOneAssociationField('bar', 'id', 'foo_id', BarDefinition::class, false))
8
    ]);
9
}
Copied!
Note, that in here there is no FkField necessary.
One to Many / Many to One
In "One To Many" / "Many To One" associations, you need to define a foreign key column for the "Many to One" side. E.g. your bar entity comes with multiple foo's. Therefore, you have to add a bar_id column in your foo table. In this example it will be bar_id in the FooDefinition.
Let's have a look at the defineFields methods of both entity definitions:
<plugin root>/src/Core/Content/Bar/BarDefinition.php
1
protected function defineFields(): FieldCollection
2
{
3
    return new FieldCollection([
4
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
5
​
6
        new OneToManyAssociationField('foos', FooDefinition::class, 'bar_id')
7
    ]);
8
}
Copied!
Next to the IdField, you only have to define the OneToManyAssociationField in your BarDefinition. Its paremeter are foos, which is the property that will contain all FooEntity's, the class name of FooDefinition and the name of the column in the referenced table, which points to the definition itself.
Let's have a look at the FooDefinition now:
<plugin root>/src/Core/Content/Foo/FooDefinition.php
1
protected function defineFields(): FieldCollection
2
{
3
    return new FieldCollection([
4
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
5
        (new FkField('bar_id', 'barId', BarDefinition::class))->addFlags(new Required()),
6
​
7
        new ManyToOneAssociationField('bar', 'bar_id', BarDefinition::class, 'id'),
8
    ]);
9
}
Copied!
Next to the IdField, you can see a new FkField, which is the field for the new bar_id column. Its parameters are the name of the column in your database (snake_case), the property name in your definition (lowerCamelCase) and the respective definition class.
Instead of adding a OneToManyAssociationField here now, we have to use the reverse side, which is ManyToOneAssociationField. Here you have to apply the name of the property, which will contain the single BarDefinition instance, the name of the column, which references to the inverse side entity (bar_id), the class of the referenced definition and the name of the ID column in the definition's database table itself. You could add another boolean parameter here, which would define whether or not you want this association to always automatically be added and be loaded. This defaults to false, since enabling this could come with performance issues.
Many to Many associations
ManyToMany associations require another, third entity to be available. It will be called FooBarMappingDefinition and is responsible for connecting both definitions. It also needs an own database table.
Mapping definition
Let's create this one first:
<plugin root>/src/Core/Content/FooBarMappingDefinition.php
1
<?php declare(strict_types=1);
2
​
3
namespace Swag\BasicExample\Core\Content;
4
​
5
use Shopware\Core\Framework\DataAbstractionLayer\Field\CreatedAtField;
6
use Shopware\Core\Framework\DataAbstractionLayer\Field\FkField;
7
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
8
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
9
use Shopware\Core\Framework\DataAbstractionLayer\Field\ManyToOneAssociationField;
10
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
11
use Shopware\Core\Framework\DataAbstractionLayer\MappingEntityDefinition;
12
use Swag\BasicExample\Core\Content\Bar\BarDefinition;
13
use Swag\BasicExample\Core\Content\Foo\FooDefinition;
14
​
15
class FooBarMappingDefinition extends MappingEntityDefinition
16
{
17
    public const ENTITY_NAME = 'foo_bar';
18
​
19
    public function getEntityName(): string
20
    {
21
        return self::ENTITY_NAME;
22
    }
23
​
24
    protected function defineFields(): FieldCollection
25
    {
26
        return new FieldCollection([
27
            (new FkField('bar_id', 'barId', BarDefinition::class))->addFlags(new PrimaryKey(), new Required()),
28
            (new FkField('foo_id', 'fooId', FooDefinition::class))->addFlags(new PrimaryKey(), new Required()),
29
            new ManyToOneAssociationField('bars', 'bar_id', BarDefinition::class, 'id'),
30
            new ManyToOneAssociationField('foos', 'foo_id', FooDefinition::class, 'id')
31
        ]);
32
    }
33
}
Copied!
The mapping definition has to extend from the MappingEntityDefinition, instead of the EntityDefinition like in other entity definitions. The rest is quite the same: Your entity definitions needs an entity name, saved in ENTITY_NAME, as well as the method defineFields, which has to return a FieldCollection.
First of all there are two FkField's. Its parameters are the name of the column in your database(snake_case), the property name in your definition (lowerCamelCase) and the respective definition class.
Additional to that, you need the ManyToOneAssociationField's. Here you have to supply the name of the property in your entity, which should contain the entries, again the name of the column in the database and the definition again. The last parameter is most likely id, which is the column name of the connected table. You could add another boolean parameter here, which would define whether or not you want this association to always automatically be added and be loaded. This defaults to false, since enabling this could come with performance issues.
Of course, you have to add both mentioned fields for each definition you want to connect, so two times that is.
Adjusting the main definitions
The last thing to do, is to add a ManyToManyAssociationField to each of your definitions themselves, like in the following example:
<plugin root>/src/Core/Content/Bar/BarDefinition.php
1
protected function defineFields(): FieldCollection
2
{
3
    return new FieldCollection([
4
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
5
​
6
        new ManyToManyAssociationField(
7
            'foos',
8
            FooDefinition::class,
9
            FooBarMappingDefinition::class,
10
            'bar_id',
11
            'foo_id'
12
        ),
13
    ]);
14
}
Copied!
Its parameters are the following:
propertyName: The name of the property in your entity, that will contain the associated entities.
referenceDefinition: The class of the associated definition.
mappingDefinition: The class of the mapping definition.
mappingLocalColumn: The name of the id column for the current entity, bar_id if you're in the BarDefinition.
mappingReferenceColumn: The name of the id column for the referenced entity.
For the sake of completion, here is the respective FooDefinition:
<plugin root>/src/Core/Content/Foo/FooDefinition.php
1
protected function defineFields(): FieldCollection
2
{
3
    return new FieldCollection([
4
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
5
​
6
        new ManyToManyAssociationField(
7
            'bars',
8
            BarDefinition::class,
9
            FooBarMappingDefinition::class,
10
            'foo_id',
11
            'bar_id'
12
        ),
13
    ]);
14
}
Copied!
And that's it, your ManyToMany association is now set up properly.
Next steps
One type of association you'll often stumble upon are translations. If you wonder how to add translations to your entity, this is the place to go.
Otherwise you may want to update some data, for this you can look at our Writing data and Replacing data guide. If you plan to remove associated data from entities, you can head over to our Remove associated data guide.
Removing associated data
Adding data translations
Last modified 18d ago
Copy link
Edit on GitHub
Contents
Overview
Prerequisites
Associations
Example entity definitions
One to One associations
One to Many / Many to One
Many to Many associations
Next steps