Document user migration API

Signed-off-by: Christopher Ng <chrng8@gmail.com>

developer_manual/digging_deeper/index.rst

@@ -31,3 +31,4 @@ Digging deeper
    status
    security
    profile
+   user_migration

developer_manual/digging_deeper/user_migration.rst

@@ -0,0 +1,154 @@
+==============
+User Migration
+==============
+
+The `User Migration app <https://apps.nextcloud.com/apps/user_migration>`_ may
+be installed to allow migration of user data.
+
+App developers can integrate into User Migration and provide ways to export
+and import the app data of a user.
+
+Register a migrator
+-------------------
+
+A migrator is represented by a class implementing the
+``OCP\\UserMigration\\IMigrator`` interface. This class is instantiated
+whenever a user export or import begins.
+
+.. code-block:: php
+
+  <?php
+
+  declare(strict_types=1);
+
+  namespace OCA\MyApp\UserMigration;
+
+  use OCA\MyApp\AppInfo\Application;
+  use OCA\MyApp\IMyAppManager;
+  use OCP\IL10N;
+  use OCP\IUser;
+  use OCP\UserMigration\IExportDestination;
+  use OCP\UserMigration\IImportSource;
+  use OCP\UserMigration\IMigrator;
+  use OCP\UserMigration\TMigratorBasicVersionHandling;
+  use OCP\UserMigration\UserMigrationException;
+  use Symfony\Component\Console\Output\OutputInterface;
+  use Throwable;
+
+  class MyAppMigrator implements IMigrator {
+    use TMigratorBasicVersionHandling;
+
+    private IMyAppManager $myAppManager;
+
+    private IL10N $l10n;
+
+    private const PATH_ROOT = Application::APP_ID . '/';
+
+    private const PATH_MYAPP_FILE = MyAppMigrator::PATH_ROOT . 'myapp.json';
+
+    public function __construct(
+      IMyAppManager $myAppManager,
+      IL10N $l10n
+    ) {
+      $this->myAppManager = $myAppManager;
+      $this->l10n = $l10n;
+    }
+
+    /**
+     * Export user data
+     *
+     * @throws UserMigrationException
+     * @since 24.0.0
+     */
+    public function export(IUser $user, IExportDestination $exportDestination, OutputInterface $output): void {
+      $output->writeln('Exporting myapp information in ' . MyAppMigrator::PATH_MYAPP_FILE . '…');
+
+      try {
+        $data = $this->myAppManager->getUserData($user);
+        $exportDestination->addFileContents(MyAppMigrator::PATH_MYAPP_FILE, json_encode($data));
+      } catch (Throwable $e) {
+        throw new UserMigrationException('Could not export myapp information', 0, $e);
+      }
+    }
+
+    /**
+     * Import user data
+     *
+     * @throws UserMigrationException
+     * @since 24.0.0
+     */
+    public function import(IUser $user, IImportSource $importSource, OutputInterface $output): void {
+      if ($importSource->getMigratorVersion($this->getId()) === null) {
+        $output->writeln('No version for ' . static::class . ', skipping import…');
+        return;
+      }
+
+      $output->writeln('Importing myapp information from ' . MyAppMigrator::PATH_MYAPP_FILE . '…');
+
+      $data = json_decode($importSource->getFileContents(MyAppMigrator::PATH_MYAPP_FILE), true, 512, JSON_THROW_ON_ERROR);
+
+      try {
+        $this->myAppManager->setUserData($user, $data);
+      } catch (Throwable $e) {
+        throw new UserMigrationException('Could not import myapp information', 0, $e);
+      }
+    }
+
+    /**
+      * Returns the unique ID
+      *
+      * @since 24.0.0
+      */
+    public function getId(): string {
+      return 'myapp';
+    }
+
+    /**
+      * Returns the display name
+      *
+      * @since 24.0.0
+      */
+    public function getDisplayName(): string {
+      return $this->l10n->t('My App');
+    }
+
+    /**
+      * Returns the description
+      *
+      * @since 24.0.0
+      */
+    public function getDescription(): string {
+      return $this->l10n->t('My App information');
+    }
+  }
+
+The ``MyAppMigrator`` class needs to be registered during the :ref:`app bootstrap<Bootstrapping>`
+
+.. code-block:: php
+
+  <?php
+
+  declare(strict_types=1);
+
+  namespace OCA\MyApp\AppInfo;
+
+  use OCA\MyApp\UserMigration\MyAppMigrator;
+  use OCP\AppFramework\App;
+  use OCP\AppFramework\Bootstrap\IBootContext;
+  use OCP\AppFramework\Bootstrap\IBootstrap;
+  use OCP\AppFramework\Bootstrap\IRegistrationContext;
+
+  class Application extends App implements IBootstrap {
+    public const APP_ID = 'myapp';
+
+    public function __construct(array $urlParams = []) {
+        parent::__construct(self::APP_ID, $urlParams);
+    }
+
+    public function register(IRegistrationContext $context): void {
+        $context->registerUserMigrator(MyAppMigrator::class);
+    }
+
+    public function boot(IBootContext $context): void {
+    }
+  }