General

A "QUIQQER CMS Import Provider" describes a special QUIQQER package that reads data and structural information from any source and formats it in a way that quiqqer/cms-import can understand it. quiqqer/cms-import is then able to parse the information and import it as accurately as possible into an existing QUIQQER system. In most cases the source will be a filesystem and/or database of another CMS (e.g. Wordpress, Drupal etc.).

The following image shows how this works in principle:

Developing steps

The following sections describe what you as a developer have to do in order to provide a fully functional Import Provider.

The main class

Build a class that implements the \QUI\CmsImport\ImportProviderInterface interface OR (and this is the easiest way) extends the \QUI\CmsImport\AbstractImportProvider class.

<?php

class MyImportProvider extends \QUI\CmsImport\AbstractImportProvider
{
  // ...
}

The whole import process is designed as a CLI tool (or "console tool" in QUIQQER terms). Thus it may be important to ouput information or prompt for user input. The easiest way to do this is to use the write* methods provided in the abstract class.

Import Provider configuration

Depending on the source your Import Provider is reading from, you may want to ask the user for configuration details like file system paths or database credentials of the source system.

Before anything is imported, the main Import class calls the promptForConfig() method of your Import Provider. This is (usually) the place where you can collect any information needed.

Alternatively your Import Provider can pull its configuration from a separate config file (e.g. {QUIQQER_ROOT}/etc/plugins/{IMPORT_PROVIDER_NAMESPACE}/{IMPORT_PROVIDER_PACKAGE}.ini.php

Entity identification

Any entity that is imported is required to have a unique identifier on the source system side. This is due to the communication process during an import:

1. Meta information is fetched from the Import Provider in form of a list or hierarchy. This list provides structural information for a certain class (or "area") of import entities (e.g. the hiearchy of sites). Entities in the list have the aforementioned unique identifier.
2. The meta information is parsed and each entity is fetched as an ImportEntity individually by unique identifier from the Import Provider. All of these entities extend \QUI\CmsImport\Entities\AbstractImportEntity.

Example

The source system of your Import Provider has a simple database table where webpages are stored. Each webpage has an ID in the database.

For the import process you can use this ID as a unique identifier for your import objects because it is unique and you know exactly which entity is requested.

1. Your ImportProvider tells the CMS Import the structural attributes of a group of entities (e.g. sites). ("Hey QUIQQER, these is the hierarchy of my source CMS pages, each with a unique identifier i can use to identify them!")
2. Each MetaEntity is then fetched as an ImportEntity which contains all the necessary data to create this entity as an object in the QUIQQER system. ("Hey ImportProvider - give me the ImportEntity with unique identifier XYZ from your source CMS so i can import it to QUIQQER!")

<?php

class MyImportProvider extends \QUI\CmsImport\AbstractImportProvider
{
    /**
     * Get a site that should be imported
     *
     * @param string $siteIdentifier - A unique ImportSite identifier
     * @param string $projectIdentifier - A unique ImportProject identifier
     * @param string $lang - Project lang
     * @return ImportSite
     */
    public function getSite($siteIdentifier, $projectIdentifier, $lang)
    {
        $webpageData = // SELECT * FROM `my_webpage_table` WHERE `id` = $siteIdentifier;

        return new \QUI\CmsImport\Entities\ImportSite(
            $siteIdentifier,
            $projectIdentifier,
            $lang,
            $webpageData
        );
    }
}

Keeping entity IDs in QUIQQER

You may want to keep IDs from you source system in QUIQQER. For this purpose some ImportEntity classes implement \QUI\CmsImport\Entities\CustomQuiqqerIdInterface which allows to set a (unique) ID for the QUIQQER system.

IDs set in this way have to be of type integer and are usually restricted to BIGINT(20) in the QUIQQER database.

Registering as an ImportProvider

In the package.xml of your package you have to register the ImportProvider.

Ideally all ImportProviders should share the namespace \QUI\CmsImport\Provider\{SOURCE_SYSTEM_NAME} as the root namespace.

Example

<quiqqer>
    <package>
        
        <!-- Other package.xml stuff ... -->

        <provider>
            <cms-import src="\QUI\CmsImport\Provider\MyProvider\ImportProvider"/>
        </provider>

    </package>
</quiqqer>

Executing the Import

The import can be executed via console command.

$ cd QUIQQER_ROOT_DIR
$ php quiqqer.php --username=USERNAME --password=PASSWORD --tool="quiqqer:cms-import"

# Follow instructions and choose your ImportProvider from the list