Updating ShopClass

ShopClass updates itself. When a new release comes out, a notice appears in the admin panel, and the built-in updater downloads and applies it for you. Use the manual route below if your host blocks outgoing web requests, or if you would rather move every file yourself.

Back up first, every time

Take a copy of your database and of oc-content/ before you start. Everything you have configured lives in one of the two, and an update is much easier to undo when you can put them back.

The one-click update

1. Open Admin → Tools → Upgrade Shopclass.
2. If a release is available, the page offers it with its changelog.
3. Press update and wait. The updater downloads the package, replaces core files, and runs any pending database migrations.

That is the whole procedure on a healthy install.

The updater checks each download against the checksum GitHub publishes for it, and refuses a file that does not match.

It also checks that PHP can write every file it would replace, before it changes anything. When it cannot, it stops and lists the files. This happens when PHP runs as another user than the one that owns the files (often nobody). Tools → System info → Server shows “PHP runs as” and “Read-only folders”. Update from a shell as the file owner instead:

php oc-cli.php core:update

The updater also refuses a release that needs a newer PHP than your server runs, before it changes anything.

Update channel and automatic security updates

Settings → General → Software updates has two choices:

• Update channel. Stable releases only is the default. Stable and release candidates and Stable, release candidates and betas are for testing a release before it ships.
• Security updates. Off by default. When on, the nightly cron installs a security release for the version you run (6.4.1 on a 6.4.0 site, never 6.5.0) once it is a day old, and e-mails the contact address whether it worked. A failed attempt is not repeated; update from the admin instead. If your cron runs from the command line, restart PHP-FPM after the e-mail arrives.

Upgrading to 7.1.0 specifically

7.1.0 needs PHP 8.2 or newer. PHP 8.0 and 8.1 no longer get security fixes. Check Tools → System info → Server before you update, and ask your host to move the site to PHP 8.2 or newer first.

From 7.0.4 the updater checks this for you. On PHP 8.0 or 8.1 it refuses the update before it changes any file, and the site keeps running on 7.0.x. Older 7.0 updaters do not check, so update to 7.0.4 first.

Upgrading to 6.4.0 specifically

Saved search alerts used to store SQL, and it ran as written. The upgrade rewrites each alert as the plain search values it stands for.

• Back up t_alerts if you might need the old alerts. The stored SQL is thrown away as each alert is converted.

• An alert holding anything Shopclass did not write (usually a plugin’s own filter) is paused, not deleted. Users → Alerts lists them under a notice. The user has to save the search again.

• A large site finishes in the background. The upgrade converts for about ten seconds, then queues the rest for the next cron runs. Alerts not converted yet send no email until they are. To finish at once:

  php oc-cli.php jobs:work

Upgrading to 6.3.0 specifically

Nothing is required. One setting is worth knowing about.

Strict SQL modes

MySQL and MariaDB can refuse a value that does not fit its column. Shopclass used to switch that off, so a name too long for its field was quietly cut short instead of rejected.

A new install now leaves the strict modes on. The installer writes this into config.php:

define('OSC_DB_STRICT_MODE', true);

An upgraded site does not get that line, and keeps the old, forgiving behaviour. That is deliberate: a plugin that has been silently truncating a value for years would start failing mid-request.

Before you opt in, read the readiness report. It is under Tools → System info → Database, in the Strict SQL mode part, and on the command line:

php oc-cli.php db:doctor --strict

It exits 1 until the site is ready. Fix each line it flags:

• Zero dates: columns holding a date like 0000-00-00. Strict mode refuses that row the next time it is saved.
• Zero-date defaults: columns whose default is a zero date. Strict mode refuses any later change to that table.
• Length settings: a setting such as the title length that is larger than its column. Lower it under Listings → Settings.
• Refused writes, last 7 days: writes strict mode refused, by table, column and kind. They are also in the activity log. The value itself is never recorded.

Values that were cut short in the past leave no trace, so a plugin that writes too much shows up only as a refused write. After you opt in, check the report again for a week.

To opt your site in, add the line to config.php yourself. In a container with no config.php, set the environment variable instead:

OSC_DB_STRICT_MODE=1

Remove it to go back; nothing is stored in the database either way.

Try it on a copy first

Core is tested under strict modes. Third-party plugins write through the same connection and are not. A plugin storing an over-length or out-of-range value gets an error where it used to get a silently altered row.

Upgrading to 6.2.0 specifically

6.2.0 rebuilds foreign keys on twenty-four tables so the database removes dependent rows along with their parent. Three consequences:

• Back up the database first. This is the one release where that instruction is not boilerplate.

• It takes time proportional to your row count. Tests on a quarter of a million listings and three quarters of a million custom-field values show the whole rebuild takes about six seconds. A much larger site, or slow shared hosting, should expect longer.

• A timeout page does not mean it failed. The upgrade is still running and will finish. With shell access you can sidestep the browser entirely:

  php oc-cli.php db:upgrade

An interrupted upgrade is safe to resume: each step is recorded as it completes and every step can be re-run, so starting it again finishes it.

Before each key is rebuilt, any row still pointing at a parent that no longer exists is removed. A healthy database has none; if yours does, they were rows nothing could reach. The backup is what lets you look at them afterwards.

Google Analytics is gone from core

The Tracking ID field has been removed from Settings → General and no measurement snippet is rendered on public pages. If you were using it, paste your own snippet into a Custom Code (HTML / JavaScript) widget under Appearance → Manage widgets, or install a plugin that provides one.

Your saved measurement ID is left in the database untouched, so a theme printing its own snippet keeps working.

Updating by hand

Use this when the updater cannot reach GitHub, or when you deploy from your own pipeline.

1. Download the release

Get the latest package from the Releases page and unpack it locally.

2. Replace the core files

Upload the new files over the old ones, replacing:

• oc-admin/ and everything under it
• oc-includes/ and everything under it
• the root-level PHP files: index.php, item.php, contact.php, ajax.php, oc-load.php, oc-cli.php and their siblings

Two things you must not overwrite

• config.php: it holds your database credentials. The release does not contain one; make sure your upload tool does not delete it.
• oc-content/: copy only the contents of the release’s oc-content into yours. Replacing the whole directory destroys your uploads, your installed plugins and any theme you have customised.

3. Run the database migration

Core files alone are not an update: the schema has to catch up. Either open the admin panel, which offers the migration as a button (Tools → System info → Database has it too, as Run database update), or run it from a shell:

php oc-cli.php db:upgrade

db:upgrade runs the pending migrations and nothing else. Run it again to finish an interrupted update. If the database is still missing a table, column or index afterwards, php oc-cli.php db:repair (or Tools → System info → Database) adds it.

The update builds the filter index inline for up to 5,000 listings (at most 20 seconds). The rest is built by a background job, which large sites wait on cron or the worker to run (automatic cron runs it every five minutes). Until the index is ready, custom-field and option filters give complete results but run slower. A plugin that writes t_item_meta with raw SQL leaves the index stale until you run php oc-cli.php search:reindex or use Rebuild filter index under Tools → System info → Database.

Updated sites keep exact search counts until you change Listings → Settings → Search count limit.

4. Check the site

Load the front page and the admin panel. If you disabled friendly URLs before updating, turn them back on now.

When an update goes wrong

The site shows a blank page. Turn on PHP error display temporarily and read what it says. A blank page after an update is almost always a leftover file from an older version.

The admin panel loads unstyled. You deployed from a branch rather than a release package. Branches do not carry the compiled admin CSS and JavaScript. Re-deploy from the release zip.

A plugin fatals on load. Disable it from a shell and update it afterwards:

php oc-cli.php plugin:deactivate --plugin=<folder>

The updater says PHP cannot write the files. PHP runs as another user than the one that owns them. Run php oc-cli.php core:update as the file owner, or ask your host to run PHP as your user.

You are locked out of the admin panel.

php oc-cli.php user:reset-password --user=admin