Quickstart: the first export and its import plan

The shortest way from “the plugin is installed” to “a complete export of the DevOps data is on disk, and you have read the plan for putting it back”. Three steps, about ten minutes. This page is for developers and operators.

The reason to do this now rather than in an emergency: it is what turns “we have backups” into “we have restores”.

• wkdostorage, wkcore and wkstorage are installed and enabled.
• PHP 8.2 or later with the SQLite PDO driver.
• The wiki's save directory is writable.
• Somewhere you can run PHP in the wiki's context — a plugin of your own, or a maintenance script that has loaded inc/init.php.

$core = plugin_load('helper', 'wkcore');
$storage = (is_object($core) && method_exists($core, 'get'))
    ? $core->get('dwdo.storage')
    : null;
 
if ($storage === null) {
    return;   // storage absent — degrade, do not fatal
}

Do not construct the storage classes yourself. The service is a lazy factory, and that is exactly what keeps a request which never touches data from opening a database at all.

$export = $core->get('dwdo.export');
$path = $export->exporter()->exportToFile('/path/to/dwdo-backup.jsonl');

The result is JSONL: one record per line. That is not a stylistic choice. The file can be read with ordinary line tools, split, appended to and diffed line by line — and a truncated file loses its last record rather than becoming unreadable.

$importer = $export->importer();
 
$plan = $importer->plan($jsonl);     // reports, changes nothing
// inspect $plan

plan() exists because an import is needed precisely when you are least able to absorb a surprise.

• The file is at the given path and holds one complete JSON object per line. wc -l therefore counts records.
• The plan for that same file against that same running installation describes no surprises — it should announce nothing you did not expect. If it deviates, you have found a question before it became expensive.

• wkstorage — the layer below: migrations, prepared statements, transactions.
• wkdocore — the project model whose data lives here.
• wkdostorage (German) — the package page: services, typed models, repositories and the export format.