|
|
# 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:
|
|
|
|
|
|
![image](uploads/c773d45909137f3facdc23105a5b66a4/image.png)
|
|
|
|
|
|
# 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
|
|
|
<?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:
|
|
|
|
|
|
![image](uploads/fabc31b41cd8d436ef7ae5b65dff6584/image.png)
|
|
|
|
|
|
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 are my source CMS pages, each with a unique identifier i can use to identify things!")
|
|
|
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!")
|
|
|
|
|
|
```php
|
|
|
<?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
|
|
|
);
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
Unique identifiers
|
|
|
|
|
|
### 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. |
|
|
\ No newline at end of file |