Using the data handling

The Shopware 6 Administration allows you to fetch and write nearly everything in the database. This guide will teach you the basics of the data handling.

Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files, as well as the command line and preferably registered module. Of course you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

Considering that the data handling in the administration is remotely operating the Data Abstraction Layer its highly encouraged to read the articles Reading data with the DAL and Writing data with the DAL.

Relevant classes

Repository: Allows to send requests to the server - used for all CRUD operations Entity: Object for a single storage record EntityCollection: Enable object-oriented access to a collection of entities SearchResult: Contains all information available through a search request RepositoryFactory: Allows to create a repository for an entity Context: Contains the global state of the administration (language, version, auth, ...) Criteria: Contains all information for a search request (filter, sorting, pagination, ...)

The repository service

Accessing the Shopware API in the Administration is done by using the repository service, which can be injected with a bottleJs dependency injection container. In the Shopware administration, there's a wrapper that makes bottleJs work with the inject / provide from Vue. In short: You can use the inject key in your component configuration to fetch services from the bottleJs DI container, such as the repositoryFactory, that you will need in order to get a repository for a single entity.

Add those lines to your component configuration:

inject: [
'repositoryFactory'
],

This way the repositoryFactory object is accessible in your component. The create function can be used to create a repository for a single entity, like in this example:

const productRepository = this.repositoryFactory.create('product')

Note: You can also change some options in the repository, with the third parameter:

Component.register('swag-basic-example', {
inject: ['repositoryFactory'],
template,
data: function () {
return {
repository: undefined
}
},
created() {
const options = {
version: 1 // default is the latest api version
};
this.repository = this.repositoryFactory.create('product', null, options);
}
});

Note: The version 1 used in the options is just an example, how to select a version. Then again the default would be the newest version. There are no other options.

Working with the criteria class

To fetch data from the server, the repository has a search function. Each repository function requires the API context and criteria class, witch contains all functionality of the core criteria class. If you want to see all the options take a look at the file src/Administration/Resources/app/administration/src/core/data/criteria.data.js.

Shopware.Component.register('swag-basic-example', {
inject: ['repositoryFactory'],
template,
data: function () {
return {
result: undefined
}
},
computed: {
productRepository() {
// create a repository for the `product` entity
return this.repositoryFactory.create('product');
},
},
created() {
const criteria = new Criteria();
criteria.setPage(1);
criteria.setLimit(10);
criteria.setTerm('foo');
criteria.setIds(['some-id', 'some-id']); // Allows to provide a list of ids which are used as a filter
/**
* Configures the total value of a search result.
* 0 - no total count will be selected. Should be used if no pagination required (fastest)
* 1 - exact total count will be selected. Should be used if an exact pagination is required (slow)
* 2 - fetches limit * 5 + 1. Should be used if pagination can work with "next page exists" (fast)
*/
criteria.setTotalCountMode(2);
criteria.addFilter(
Criteria.equals('product.active', true)
);
criteria.addSorting(
Criteria.sort('product.name', 'DESC')
);
criteria.addAggregation(
Criteria.avg('average_price', 'product.price')
);
criteria.getAssociation('categories')
.addSorting(Criteria.sort('category.name', 'ASC'));
this.productRepository.create('product');
this.productRepository
.search(criteria, Shopware.Context.api)
.then(result => {
this.result = result;
});
}
});

How to fetch a single entity

Since the context of an edit or update form is usually a single root entity, the data handling diverges here from the Data Abstraction Layer and provides loading of a single resource from the Admin API.

Shopware.Component.register('swag-basic-example', {
inject: ['repositoryFactory'],
template,
data: function () {
return {
entity: undefined
}
},
computed: {
productRepository() {
return this.repositoryFactory.create('product');
}
},
created() {
const entityId = 'some-id';
this.productRepository
.get(entityId, Shopware.Context.api)
.then(entity => {
this.entity = entity;
});
}
});

Update an entity

The data handling contains change tracking and sends only changed properties to the Admin API endpoint. Please be aware that in order to be as transparent as possible, updating data will not be handled automatically. A manual update is mandatory.

Shopware.Component.register('swag-basic-example', {
inject: ['repositoryFactory'],
template,
data: function () {
return {
entityId: '1de38487abf04705810b719d4c3e8faa',
entity: undefined
}
},
computed: {
productRepository() {
return this.repositoryFactory.create('product');
}
},
created() {
this.productRepository
.get(this.entityId, Shopware.Context.api)
.then(entity => {
this.entity = entity;
});
},
methods: {
// a function which is called over the ui
updateTrigger() {
this.entity.name = 'updated';
// sends the request immediately
this.productRepository
.save(this.entity, Shopware.Context.api)
.then(() => {
// the entity is stateless, the data has be fetched from the server, if required
this.productRepository
.get(this.entityId, Shopware.Context.api)
.then(entity => {
this.entity = entity;
});
});
}
}
});

Delete an entity

The delete method sends a delete request for a provided id. To delete multiple entities at once use the syncDeleted method by passing an array of ids.

Shopware.Component.register('swag-basic-example', {
inject: ['repositoryFactory'],
template,
computed: {
productRepository() {
return this.repositoryFactory.create('product');
}
},
created() {
this.productRepository.delete('1de38487abf04705810b719d4c3e8faa', Shopware.Context.api);
}
});

Create an entity

Although entities are detached from the data handling once retrieved or created they still must be set up through a repository. You can create an entity by using the this.repositoryFactory.create() method, fill it with data and save it as seen below:

Shopware.Component.register('swag-basic-example', {
inject: ['repositoryFactory'],
template,
data: function () {
return {
entity: undefined
}
},
computed: {
manufacturerRepository() {
return this.repositoryFactory.create('product_manufacturer');
}
},
created() {
this.entity = this.manufacturerRepository.create(Shopware.Context.api);
this.entity.name = 'test';
this.manufacturerRepository.save(this.entity, Shopware.Context.api);
}
});

Working with associations

Each association can be accessed via normal property access:

Shopware.Component.register('swag-basic-example', {
inject: ['repositoryFactory'],
template,
data: function () {
return {
product: undefined
}
},
computed: {
productRepository() {
return this.repositoryFactory.create('product');
},
productCriteria() {
return new Criteria()
.addAssociation('manufacturer')
.addAssociation('categories')
.addAssociation('prices');
}
},
created() {
this.repository = this.repositoryFactory.create('product');
const entityId = '66338d4e19f749fd90b59032134ecb74';
this.repository
.get(entityId, Shopware.Context.api, this.productCriteria)
.then(product => {
this.product = product;
// ManyToOne: contains an entity class with the manufacturer data
console.log(this.product.manufacturer);
// ManyToMany: contains an entity collection with all categories.
// contains a source property with an api route to reload this data (/product/{id}/categories)
console.log(this.product.categories);
// OneToMany: contains an entity collection with all prices
// contains a source property with an api route to reload this data (/product/{id}/prices)
console.log(this.product.prices);
});
}
});

Set a ManyToOne

If you have a ManyToOne association, you can write changes as seen below:

Shopware.Component.register('swag-basic-example', {
inject: ['repositoryFactory'],
template,
data: function () {
return {
product: undefined,
};
},
computed: {
productRepository() {
return this.repositoryFactory.create('product');
},
manufacturerRepository() {
return this.repositoryFactory.create('product_manufacturer');
}
},
created() {
this.productRepository
.get('some-product-id', Shopware.Context.api)
.then((product) => {
this.product = product;
this.product.manufacturerId = 'some-manufacturer-id'; // manually set the forign key y
this.productRepository.save(this.product, Shopware.Context.api);
});
},
});

Working with lazy loaded associations

In most cases, ToMany associations can be loaded by adding a the association with the .addAsscoiation() method of the Criteria object.

Shopware.Component.register('swag-basic-example', {
inject: ['repositoryFactory'],
template,
data: function () {
return {
product: undefined
};
},
computed: {
productRepository() {
return this.repositoryFactory.create('product');
},
productCritera() {
const criteria = new Criteria();
criteria.addAssociation('prices');
return criteria;
}
},
created() {
this.productRepository
.get('some-id', Shopware.Context.api, this.productCritera)
.then((product) => {
this.product = product;
});
}
});

Working with OneToMany associations

The following example shows how to create a repository based on associated data. In this case the priceRepository contains associated prices to the product with the id 'some-id'.

Shopware.Component.register('swag-basic-example', {
inject: ['repositoryFactory'],
template,
data: function () {
return {
product: undefined,
prices: undefined
};
},
computed: {
productRepository() {
return this.repositoryFactory.create('product');
},
priceRepository() {
if (!this.product) {
return undefined;
};
return this.repositoryFactory.create(
// `product_price`
this.product.prices.entity,
// `product/some-id/priceRules`
this.product.prices.source
);
}
},
created() {
this.productRepository
.get('some-product-id', Shopware.Context.api)
.then((product) => {
this.product = product;
});
},
methods: {
loadPrices() {
this.priceRepository
.search(new Criteria(), Shopware.Context.api)
.then((prices) => {
this.prices = prices;
});
},
addPrice() {
const newPrice = this.priceRepository.create(Shopware.Context.api);
newPrice.quantityStart = 1;
// Note: there are more things requiered then just the quantityStart
this.priceRepository
.save(newPrice, Shopware.Context.api)
.then(this.loadPrices);
},
deletePrice(priceId) {
this.priceRepository
.delete(priceId, Shopware.Context.api)
.then(this.loadPrices);
},
updatePrice(price) {
this.priceRepository
.save(price, Shopware.Context.api)
.then(this.loadPrices);
}
}
});

Working with ManyToMany associations

The following example shows how to create a repository based on associated data. In this case the categoryRepository contains associated categories to the product with the id 'some-id'.

Shopware.Component.register('swag-basic-example', {
inject: ['repositoryFactory'],
template,
data: function () {
return {
product: undefined,
categories: undefined
};
},
computed: {
productRepository() {
return this.repositoryFactory.create('product');
},
categoryRepository() {
if (!this.product) {
return undefined;
};
return this.repositoryFactory.create(
// `product_categories`
this.product.categories.entity,
// `product/some-id/categories`
this.product.categories.source
);
}
},
created() {
this.productRepository
.get('some-product-id', Shopware.Context.api)
.then((product) => {
this.product = product;
});
},
methods: {
loadCategories() {
this.categoryRepository
.search(new Criteria(), Shopware.Context.api)
.then((categories) => {
this.categories = categories;
});
},
addCategoryToProduct(category) {
this.categoryRepository
.assign(category.id, Shopware.Context.api)
.then(this.loadCategories);
},
removeCategoryFromProduct(categoryId) {
this.categoryRepository
.delete(categoryId, Shopware.Context.api)
.then(this.loadCategories);
}
}
});

Working with local associations

In case of a new entity, the associations can not be sent directly to the server using the repository, because the parent entity isn't saved yet. For example: You can not add prices to a product which is not even saved in the database yet.

For this case the association can be used as storage as well and will be updated with the parent entity. In the following examples, this.productRepository.save(this.product, Shopware.Context.api) will send the prices and category changes.

Notice: It is mandatory to add entities to collections in order to get reactive data for the UI.

Working with local OneToMany associations

The following example shows how to create a repository based on associated data. In this case the priceRepository contains associated prices to the product with the id 'some-id'.

Shopware.Component.register('swag-basic-example', {
inject: ['repositoryFactory'],
template,
data: function () {
return {
product: undefined
};
},
computed: {
productRepository() {
return this.repositoryFactory.create('product');
},
priceRepository() {
if (!this.product) {
return undefined;
};
this.priceRepository = this.repositoryFactory.create(
// `product_price`
this.product.prices.entity,
// `product/some-id/priceRules`
this.product.prices.source
);
}
},
created() {
this.productRepository
.get('some-id', Shopware.Context.api)
.then(product => {
this.product = product;
});
},
methods: {
loadPrices() {
this.prices = this.product.prices;
},
addPrice() {
const newPrice = this.priceRepository
.create(Shopware.Context.api);
newPrice.quantityStart = 1;
// update some other fields
this.product.prices.add(newPrice);
},
savePrice() {
this.productRepository.save(this.product)
},
deletePrice(priceId) {
this.product.prices.remove(priceId);
},
updatePrice(price) {
// price entity is already updated and already assigned to product, no sources needed
}
}
});

Working with local ManyToMany associations

The following example shows how to create a repository based on associated data. In this case the categoryRepository contains associated categories to the product with the id 'some-id'.

Shopware.Component.register('swag-basic-example', {
inject: ['repositoryFactory'],
template,
data: function () {
return {
product: undefined,
prices: undefined
};
},
computed: {
productRepository() {
return this.repositoryFactory.create('product');
},
priceRepository() {
if (!this.product) {
return undefined;
};
return this.repositoryFactory.create(
// `product_price`
this.product.prices.entity,
// `product/some-id/priceRules`
this.product.prices.source
);
}
},
created() {
this.productRepository
.get('some-id', Shopware.Context.api)
.then(product => {
this.product = product;
});
},
methods: {
loadPrices() {
this.prices = this.product.prices;
},
addPrice() {
const newPrice = this.priceRepository
.create(Shopware.Context.api);
newPrice.quantityStart = 1;
// update some other fields
this.product.prices.add(newPrice);
},
savePrice() {
this.productRepository.save(this.product)
},
deletePrice(priceId) {
this.product.prices.remove(priceId);
},
updatePrice(price) {
// price entity is already updated and already assigned to product, no sources needed
}
}
});

Next steps

As this is very similar to the DAL it might be interesting to learn more about that. For this, head over to the section about the data handling in PHP.