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.

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 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.

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>

You are locked out of the admin panel.

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