Module id: gm-backup - translation category: GmBackupModule.base - namespace: humhub\modules\gmBackup.

Queue a backup from your own code

Backups and restores are meant to run as queue jobs. Only one operation can run at a time; the state is kept in @runtime/gm-backup/state.json (not in the database, because a restore replaces the database).

use humhub\modules\gmBackup\components\OperationState;
use humhub\modules\gmBackup\jobs\BackupJob;

if (OperationState::start(OperationState::TYPE_BACKUP)) {
    Yii::$app->queue->push(new BackupJob());
}

Use the BackupManager directly

createBackup() throws a \RuntimeException on failure and returns the file name on success. Parts that could not be included are available via getWarnings().

use humhub\modules\gmBackup\components\BackupManager;

$manager = new BackupManager();
$file = $manager->createBackup();
$warnings = $manager->getWarnings();

inspectBackup($file) describes what a restore would replace; verifyBackup($file) checks the signature (BackupSigner::STATUS_*); restoreBackup($file, $allowUnsigned = false) refuses archives without a valid signature unless $allowUnsigned is true (never for modified archives) and returns ['success', 'changesMade', 'restored', 'failed', 'warnings'].

Archive format (version 3)

backup-info.json            manifest (format_version, humhub_version, components[...status...], warnings);
                            components.modules.paths[] maps each slug to the configured module path
database/db_dump.sql        (database/db_dump.sql.bz2 with bzip2 compression)
database/db_info.json
files/modules/<slug>/...    one directory per module path from moduleAutoloadPaths (without @humhub/modules)
                            or files/modules/<slug>.tar.gz|.tar.bz2 with solid compression
files/config/...            @config
files/uploads/...           uploads directory
files/themes/<name>/...     @themes/<name> (or files/themes/<name>.tar.gz|.tar.bz2)

Packaging

Running the tests creates files that must not be part of the package: tests/error_log, the logs in tests/codeception/_output/ and the generated actions in tests/codeception/_support/_generated/ (codecept build creates them). Run the tests in a copy of the module, or remove these files before building the zip.

Signatures

BackupSigner signs archives (HMAC-SHA256, sidecar file <archive>.sig, key from params['gmBackupSigningKey'] or @runtime/gm-backup/signing.key). Statuses: valid, unsigned, foreign (other key), modified (own key, content differs) and invalid. unsigned, foreign and invalid can be overridden by an administrator, modified never.

Solid compression

components/solid/ contains a small streaming tar writer and reader (SolidWriter, SolidReader, SolidCompression). The archives are standard ustar tar files compressed with gzip or bzip2 and are stored uncompressed (CM_STORE) inside the backup ZIP. The reader verifies every header checksum and accepts only regular files and directories with plain relative paths. Compressed parts are unpacked into @runtime before a restore changes anything.

Cron

The module listens to humhub\commands\CronController::EVENT_ON_HOURLY_RUN (see config.php and Events.php).

Tests

Codeception unit tests live in tests/. Install the module in protected/modules/gm-backup of a HumHub installation (with the Codeception dev dependencies) and run:

cd protected/modules/gm-backup/tests
php ../../../vendor/bin/codecept build   # once: creates the generated actor classes
php ../../../vendor/bin/codecept run unit

The bootstrap finds the installation by itself. If the module is installed somewhere else, set HUMHUB_PATH to the root directory of the installation, the directory that contains protected/humhub (the path of protected/humhub itself is accepted too). If no installation is found, the test run stops with a message that lists the paths it tried.

The tests create files that must not be part of the package, see "Packaging" below.