• Explanation of terms
  • ImpEx
  • Snapshot
  • Provider
    • Export Provider
    • Import Provider
  • Profile
  • Chunk
  • Slice
  • TransformationContext

Explanation of terms

ImpEx documentation often refers to special terms.

This page will clarify their meaning.

ImpEx

The name of the plugin stands for Import / Export => in short ImpEx.

Snapshot

A snapshot is a copy of the content to be imported/exported.

It resides in a separate WordPress database table managed by the ImpEx plugin.

Attachments/media will be saved in a private sub-directory of the WordPress uploads folder.

You can imagine a snapshot like a server side copy of the content.

You can import / export as many snapshots as you want.

Provider

Provider handle content for ImpEx. They are used to load (import) or extract (export) data for ImpEx.

There exist a set of standard providers brought by ImpEx for common WordPress data like posts, attachments, wp_options and database tables. Custom providers can be registered by the user.

ImpEx provider are basically callback functions called by ImpEx.

A provider gets registered with a unique name. The name is used to reference providers in a ImpEx profile.

There are two types of providers: Import and Export provider.

Export Provider

Export provider expose data as slices to ImpEx.

Because an Export provider may need to produce more than one slice per execution, the callback interface is designed as generator function.

In other words, an Export provider callback function gets called with a configuration and yields as many slices as needed. The configuration controls which data should be exported.

Take a look at the **WpOptionsExporterProviderCallback to see an example.

Import Provider

Import provider consume slices from ImpEx.

They work similarly to Export provider and get called with a configuration (controling what data should be imported from a slice) and a slice as parameter.

Since ImpEx does not know about how to handle a slice by itself, it delegates this task to the Import provider.

So an Import Provider checks if it can handle a slice by introspecting the slice meta-data. If it does, it handles the slice data and returns true if the slice was successfully imported.

In all other cases it returns false. In this case ImpEx will take the next Import provider in charge.

See __WpOptionsImportProviderCallback as an example

Profile

A profile consists of a list of tasks that are executed in the order they are registered.

Each task will reference a provider and it's configuration.

See base Export profile as example.

Profiles are used to programmatically compose the data to export (Export Profile) or to consume the data to import (Import Profile).

Furthermore a profile can configure event handler to be triggered in certain situations (like when the import was finished).

See ImpexImport::EVENT_IMPORT_END event usage for example

Chunk

When exporting a huge WordPress site with hundreds of posts and images, the result would be a directory with hundreds of files. To prevent File managers of crashing due to the amount of files, ImpEx splits the exported slice files into sub-directory chunks.

A chunk is sub-directory keeping a configurable unit of slices below the top level export directory. See an example export directory layout.

Slice

A slice is a self-containing JSON data structure of both data and its description (aka meta-data).

An example: a slice of WordPress posts will contain the posts (=> data) and the information thats needed to import the posts (=> meta-data like post title, author, ...).

The slice meta-data consist of a static part (semantic version, type of slice, ...) and a content related part contributed by the Export provider (entity type, any other meta data relevant for importing the data).

There is one special exception to the rule that a slice is self-contained : Attachment slices. Attachment slices are not self-contained because they contain binary data which cannot effectively stored within JSON.

The slice data are completely contributed by the Export provider.

See the Data files chapter for more information about the structure of a slice.

Slice files are strongly typed JSON structures. See the JSON schema definitions for standard ImpEx slice types in the ImpEx GitHub repository.

TransformationContext

TransformationContext transports contextual information's about the current import/export process. It's used to pass information from ImpEx to the Provider.

A TransformationContext is an internal data structure.