Updating Scriptor

What this covers

How to update an existing Scriptor install to a newer release. Scriptor itself, iManager (the storage layer Scriptor depends on), and any plugins all live in vendor/; the update is a composer update plus, when iManager bumped its schema, a vendor/bin/imanager schema:migrate.

Before you do anything, back up. The Backup and restore topic covers the recipe; do it before every update, including the small ones.

Walkthrough

Step 1: Take a backup

sqlite3 data/imanager.db ".backup '/tmp/imanager.db.snapshot'"
tar czf /var/backups/scriptor/pre-update-$(date +%Y%m%d-%H%M).tgz \
  /tmp/imanager.db.snapshot \
  public/uploads/ \
  data/settings/custom.scriptor-config.php
rm /tmp/imanager.db.snapshot

Skipping this step is the most common reason an update becomes a problem. See Backup and restore for the full reasoning.

Step 2: Check what is currently installed

composer show bigins/scriptor bigins/imanager

The output tells you the current versions of Scriptor and iManager. Note them down; you will reference them if a roll- back becomes necessary.

For plugins, list them too:

composer show 'bigins/scriptor-*'

Step 3: Update

Native install:

composer update bigins/scriptor bigins/imanager 'bigins/scriptor-*' --with-dependencies

This pulls the latest tags within the version constraints in your composer.json. To go to a specific version instead, edit the constraint in composer.json first ("bigins/scriptor": "^2.1.0") and then run composer update bigins/scriptor.

Docker (compose stack):

The Docker workflow bakes Composer dependencies into the image at build time. To update, rebuild the image:

docker compose build --no-cache scriptor
docker compose up -d scriptor

Restart-only (docker compose restart scriptor) does not update; the existing container's vendor/ is unchanged.

Step 4: Run schema migrations if needed

iManager's CLI has two commands that matter here:

vendor/bin/imanager schema:status

Reports the database schema version against the iManager release's expected version. If it says "up to date", nothing more to do; skip to Step 5.

If it lists pending migrations, apply them:

vendor/bin/imanager schema:migrate

The command runs migrations in order, idempotently. A migration that already ran is skipped. A failing migration stops the run and reports which one.

Since iManager 2.2.1, vendor/bin/imanager fts:rebuild implicitly runs schema:migrate first when the schema is behind. For older iManager versions, run schema:migrate explicitly before fts:rebuild.

Step 5: Rebuild the full-text-search index (when iManager changed searchable fields)

iManager 2.2.0 made the searchable-field defaults smarter, which means an older install that worked correctly may have indexed less than the new release expects. Rebuild after a release that touches FTS:

vendor/bin/imanager fts:rebuild

The release notes for the iManager version you are moving to will say whether this is needed. When in doubt, run it; it is idempotent and takes seconds even on large content trees.

Step 6: Clear OPcache (production)

If you have OPcache enabled in production with opcache.validate_timestamps=0, PHP keeps running the old bytecode after the update. Reset it:

php -r "opcache_reset();"
# or, for Docker stacks:
docker compose restart php   # whichever service runs PHP-FPM

For Docker, the rebuild in Step 3 already replaced the container; no separate OPcache reset is needed.

Step 7: Smoke-test

A short checklist:

  1. / returns HTTP 200 in an anonymous browser session.
  2. /editor/ shows the login form.
  3. Logging into the editor lands on the dashboard.
  4. Pages module opens, shows the page tree.
  5. Clicking a page opens the form with content intact.
  6. Saving a page (no changes is fine; just the round-trip) succeeds.
  7. /plugins/ lists every plugin you expect, with a version that matches what composer show reports.

If all seven pass, the update is good. Keep the pre-update backup for at least a day in case a subtle regression surfaces later.

What to check after

  • composer show bigins/scriptor reports the new version.
  • vendor/bin/imanager schema:status reports "up to date".
  • The smoke-test checklist passes end to end.
  • Plugins that were enabled before the update are still enabled (in the Plugins module's main table, not the Disabled section).

Troubleshooting

composer update fails with a "platform requirements" error

The new Scriptor release requires a PHP version your install does not have. The error names the constraint (e.g. requires php ^8.3). Either upgrade PHP first (the install path you used decides how) or pin Scriptor to a version that supports your PHP ("bigins/scriptor": "^2.0" for PHP 8.2 hosts).

composer update succeeds but the site shows a fatal error

A class name or method signature changed between releases and something in your override or theme is referencing the old shape. Look at the error message; it names the file and line. Two options:

  1. Fix the reference. Update your theme or override to match the new API. The release notes are the canonical reference for what changed.
  2. Roll back. Restore the pre-update backup (composer.lock + the database snapshot from Step 1), then pin the constraint to the working version before retrying.

schema:migrate fails partway

The output names the failing migration. Common causes:

  1. Database is on read-only filesystem. Common on Docker bind-mounts with the wrong ownership. Fix the mount and retry; migrations are idempotent.
  2. A custom plugin's data violates a new constraint. The new schema added a NOT NULL column or a UNIQUE constraint that existing rows violate. The release notes call this out; the fix is to clean the offending rows first and then retry.

When in doubt, restore the pre-update backup and pin to the old version while you investigate.

Plugins module shows my plugin disappeared after update

composer update resolves the same constraint to a newer release if the plugin uses a wide range ("^1"). If the new release is incompatible with the Scriptor version you ended up on, the plugin would fail to boot and disappear from the table. Three checks:

  1. composer show bigins/scriptor-<plugin>: is it still in vendor/?
  2. data/logs/scriptor.log: does it show a boot error for that plugin?
  3. The plugin's CHANGELOG: does it support the Scriptor version you are on?

Pin the plugin to a known-good version while you work it out.

See also