Table of Contents

1. Requirements
2. Optional Requirements
3. Installation
4. Creating an import
5. Editing an import
6. Deleting an import
7. Running an import
8. Rolling back an import
9. Setting up live logging
10. Creating a Source Driver
11. Creating a Destination Driver

Requirements

• PHP 7.2 or higher

Installation

Install the plugin from CLI using this command:

php artisan plugin:install Vdlp.Import

Or install it from the October Marketplace. And update dependencies from root of your OctoberCMS project.

Creating an import

NOTE: Before creating an import you must have at least one Source Driver and one Destination Driver installed. Please see drivers for possible drivers.

1. Go to the Vdlp.Import tab in the backend.
2. Click the + New Import button.
3. Under the Source field select the Source Driver from which you want data imported.
4. Under the File field, upload the export file corresponding with your source driver.

The Vdlp.Import plugin will now look for all items found in the source file, and display switches for each type when there is atleast one of said type found. Numbers with the amount items with this types is also displayed.

5. Switch all the switches to ON for all the types you wish to import.

Tabs will now be shown for each of the individual types you switched to ON you can further configure per-type options here.

6. Further configure the individual types.
7. Either click Create and run to immediately execute your import or click Create and close to run your import later.

Editing an import

NOTE: You can only edit imports that have not been run.

1. Go to the Vdlp.Import tab in the backend.
2. Click the Edit button next to the import you wish to edit.
3. Edit the import.

Deleting an import

NOTE: You can only delete imports that have not been run.

1. Go to the Vdlp.Import tab in the backend.
2. Click the Delete button next to the import you wish to delete.

Running an import

1. Go to the Vdlp.Import tab in the backend.
2. Click the Run import next to the import you wish to run.
3. Click on the Run import button.
4. Wait until the import finishes.

Rolling back an import

NOTE: You can only roll back imports that have already been run.

1. Go to the Vdlp.Import tab in the backend.
2. Click on the Rollback button on the import you wish to roll back.

Creating a Source Driver

If you wish to create a new source driver for a CMS that does not yet have one, you can do so by following these steps:

1. Create a new class.
2. Make it implement the Vdlp\Import\Classes\Contracts\SourceDriver interface.
3. Implement the methods accordingly:
   • getName Must return the driver name (For example 'WordPress').
   • getDescription Must return a driver description.
   • getIcon Can return an OctoberCMS icon string for displaying a icon in the dropdown and list (For example 'oc-icon-wordpress').
   • getAllowedExportMimeTypes Should return an array of mime types that the export file from the source CMS can be in. For example ['text/xml'].
   • getAllowedExportExtensions Should return an array of extensions that the export file can be in. For example ['xml'].
   • start Can be implemented to do something when the import starts.
   • finish Can be implemented to do something when the import finishes.
   • supportsFoo Must return a boolean that designates whether the source returns an item with the type Foo. For example a Post or Page.
   • getParsed Is the main method that will parse the Source file and return a Source object containing all the Posts, Pages, Categories and Tags that the Source driver provides.
4. Register the Source Driver with the Vdlp.Import plugin:

use System\Classes\PluginBase;
use Vdlp\Import\Classes\Importer;

class Plugin extends PluginBase {
    public function boot() {
        app(Importer::class)->extend('foo', function () {
            return new SourceDriverClass();
        });
    }
}

OR with the Facade:

use System\Classes\PluginBase;
use Vdlp\Import\Classes\Facades\Import;

class Plugin extends PluginBase {
    public function boot() {
        Import::extend('foo', function () {
            return new SourceDriverClass();
        });
    }
}

Creating a Destination Driver

If you wish to create a new destination driver for importing content for a model that does not yet have a driver associated with it, you can do so by following these steps:

1. Create a new class.
2. Make it implement the Vdlp\Import\Classes\Contracts\DestinationDriver interface.
3. Implement the methods accordingly:
   • getName Must return the driver name (For example 'Pages').
   • getDescription Must return a driver description.
   • getIcon Can return an OctoberCMS icon string for displaying a icon in the dropdown and list.
   • supportsFoo Must return a boolean that designates whether the destination can handle an item with the type Foo. For example a Post or Page.
   • insertFoo The actual method for creating the object that the Driver is for. Supplies a Source object that the desired properties can be gathered out of. Must return the created OctoberCMS model.
   • findFoo Finds an existing model depending on a Source object. Must return it if found, otherwise null.
   • associateContentBearerTaxonomy Method for associating a Content Bearer (Post/Page) with a taxonomy (Category/Tag). Returns the status, if the association was made properly. You can return false if your destination does not support associating Content Bearers with taxonomies or does not have taxonomies at all you can return false.
   • associateParentChildTaxonomy Method for associating the parent-child relation of a taxonomy (Category/Tag). Returns the status, if your destination does not support parent-child relations in taxonomies, or does support taxonomies at all you can return false.
   • onRollBack Optional method that gets called when a rollback starts. Can be used to delete additional items in the Import like files.
4. Register the Destination Driver with the Vdlp.Import plugin:

use System\Classes\PluginBase;
use Vdlp\Import\Classes\Importer;

class Plugin extends PluginBase {
    public function boot() {
        app(Importer::class)->extend('bar', function () {
            return new DestinationDriverClass();
        });
    }
}

OR with the Facade:

use System\Classes\PluginBase;
use Vdlp\Import\Classes\Facades\Import;

class Plugin extends PluginBase {
    public function boot() {
        Import::extend('bar', function () {
            return new DestinationDriverClass();
        });
    }
}

5. Extend each of your destination model types with a new morphOne relation to the Vdlp\Import\Models\Destination model class as destinationable.

use System\Classes\PluginBase;
use Vdlp\Import\Models\Destination;

class Plugin extends PluginBase {
    public function boot() {
        DestinationModel::extend(function (DestinationModel $model) {
            $model->morphOne = [
                'destination' => [
                    Destination::class => 'destinationable',
                ],
            ];
        });
    }
}