Import/Export

Import data file

Files store data in JSON format with a specific structure. The file holds the objects to be imported. Each object must have its type (@type) and fields with data to be imported. Sample import file with one entry:

{
    "objects": [
        {
            "@type": "Node",
            "type": "page",
            "title": "Homepage"
        }
    ]
}

The file can of course contain many more objects, each in a new element of the objects array.

Some objects contain other objects within them. For example, when importing a Menu, we also import the tabs of that Menu. From the definition of the Menu type, it follows that the Menu items should be in the items field. An example of such nesting looks like this.

{
    "objects": [
        {
            "@type": "Menu",
            "name": "Main menu",
            "items": [
                {
                    "@type": "MenuItem",
                    "name": "Homepage"
                },
                {
                    "@type": "MenuItem",
                    "name": "About us"
                },
                {
                    "@type": "MenuItem",
                    "name": "Contact"
                }
            ]
        }
    ]
}

Object schema configuration

In order to import any object, its schema must be defined so that the system knows how to handle it and save it in the system. The configuration is stored in the config.yaml files in the modules.

Suppose we are making a product catalog. So we have Products. The product has a name, description and visibility on the website. So let's configure such an object.

cms:
    importer:
        objects:
            Product:
                mapping:
                    name: ~
                    description:
                        required: false
                    visible:
                        type: boolean
                        default_value: true

In our case, a description is not required. By default, however, each field is required, so we have to change the requirement manually. We have visibility, but we don't want to have to specify it every time, so we assume that all imported products are visible by default. By default, all fields are also of type string. The available field types are:

Type	Description
string	Text
boolean	Boolean value
integer	Number
scalar	Scalar value
number	Number
array	Array
one_dimension_array	One-dimensional array
uuid	UUID
datetime	Date and time in format Y-m-d H:i:s

Object importer

The last step will be to create the object importer itself. The importer is a class that implements Tulia\Component\Importer\ObjectImporter\ObjectImporterInterface. It should be located in the Infrastructure layer. So let's create an importer for our product catalog.

namespace Tulia\Cms\Products\Infrastructure\Cms\Importer;

use Tulia\Component\Importer\ObjectImporter\ObjectImporterInterface;
use Tulia\Component\Importer\Structure\ObjectData;

class ProductImporter implements ObjectImporterInterface
{
    public function import(ObjectData $objectData): ?string
    {
        $this->creator->create(
            $objectData['name'],
            $objectData['description'] ?? '',
            $objectData['visibility'],
        );
    }
}

The interface requires the import() method, which takes an object of the Tulia\Component\Importer\Structure\ObjectData class as an argument. It stores all the data of the imported object. You access this data by referencing the object as an array.

This object also contains the definition of the imported object (a list of fields and their types). You can access it by calling $objectData->getDefinition().

Now all you have to do is assign the Importer class to the object you want to import. You do this by adding FQCN to your YAML configuration:

cms:
    importer:
        objects:
            Product:
                importer: 'Tulia\Cms\Products\Infrastructure\Cms\Importer\ProductImporter'
                mapping: # Dotychczasowa lista pól...