Updates, migrations and backups

Basehim updates itself from the admin. A site checks the update hub, downloads a verified package, takes a snapshot, applies it and runs any database migrations. This page explains each step, so you know what is safe to change on a site and how your own apps and themes get updated.

One-click updates

Go to Admin → Updates. Core, app and theme updates are listed there, with each version's release notes. The sidebar shows a count when something is waiting. Update all applies everything in order.

For a core update, the updater:

1. Downloads the package from the hub (https://www.cloudhim.com unless UPDATE_HUB_URL says otherwise).
2. Verifies its SHA-256 checksum when the release carries one, and refuses a mismatch.
3. Snapshots every file it is about to overwrite into storage/updates/backup-….
4. Extracts the files. It refuses paths that try to escape the install folder. If extraction fails part-way, the snapshot is put back.
5. Checks that the version really advanced. If not, it rolls back.
6. Runs pending migrations and clears caches.

The snapshot is deleted after a successful update. Older snapshots are removed after a day.

What an update never touches

Warning: Don't edit the bundled default theme in place. Copy it to a new folder with a new slug and edit the copy, or an update may replace your changes.

Patches add and replace files; they don't delete them. A file that core no longer uses can stay on a site that was updated by patches. That is harmless, because nothing loads it.

Database migrations

Schema changes ship as numbered .sql files in database/migrations/. They are applied in filename order, and each one is recorded so it runs once.

• The installer runs them all on a fresh site.
• The updater runs the new ones after each core update.
• Admin → System → Database shows pending migrations and has a button to run them. Use it after updating files by hand.

Migrations use {table} tokens, which become prefixed, quoted table names, so they work with any DB_PREFIX:

CREATE TABLE IF NOT EXISTS {rate_limits} (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    bucket VARCHAR(64) NOT NULL
);

Write migrations for MySQL 5.7 and MariaDB. For example, ADD COLUMN IF NOT EXISTS is MariaDB-only. To make a step conditional, check information_schema and run it through PREPARE/EXECUTE. Never edit a migration that has shipped; add a new file instead.

Updating a git checkout

If you run Basehim from a clone, update with git and then apply migrations:

git pull
# then open Admin → System → Database and run pending migrations

Git ignores .env, the contents of storage/, and every app and theme folder except the bundled ones, so a pull leaves your own work alone.

Updating your own apps

An app's version lives in its app.json. When the files on disk carry a new version, however they got there, Basehim calls the app's onUpgrade($from, $to) once. The files may arrive through the marketplace, a ZIP upload, FTP, or a core patch. Use onUpgrade() to migrate your own tables and settings:

public function onUpgrade(string $from, string $to): void
{
    if (version_compare($from, '1.1.0', '<')) {
        $this->schema("ALTER TABLE `{$this->table('votes')}` ADD COLUMN source VARCHAR(20) NULL");
    }
}

It also fires on downgrades, so compare versions rather than assume the number went up. A throw is logged and swallowed, so a bad handler can't lock anyone out of the Apps screen.

Apps published through the marketplace (CloudHim) show up on Admin → Updates on every site that has them installed. An update replaces the app's files as a whole and keeps its settings, tables and active state. If the new version asks for more permissions, it keeps running with the ones it already had until the site owner approves the new ones. See App permissions.

Updating your own themes

Bump version in theme.json and ship the new folder (ZIP upload or the marketplace). Themes have no upgrade hook: they hold no data of their own. Customizer values are stored by core and survive the update.

Backups

The updater's snapshot is a safety net for one update, not a backup. Before major changes, back up:

• the database (your host's backup tool, or mysqldump);
• storage/uploads/ (your media);
• .env;
• content/apps/ and content/themes/ if you changed them.

Restoring is the reverse: put the files back, import the database, and keep the same .env. DB_PREFIX and APP_KEY must match the database you restore.