Plugins

Plugins add what your particular site needs and core deliberately does not carry: payment gateways, map providers, storage backends, import tools.

Plugins in the admin panel.

Installing

Plugins → Manage plugins has three tabs:

Tab	What it shows
Installed	What this site has, as cards with a state badge.
Browse	The plugin registry: a public catalog of packages, each checked by an automated build before it is listed. One click installs.
Updates	Installed plugins with a newer version, with a count in the tab.

Each card carries the version, the author, a short description, and whether the package runs on your version (Needs 6.5 or newer, Needs PHP 8.2), so you never have to compare numbers yourself.

Appearance uses the same three tabs and the same cards.

A plugin zip can also be uploaded directly, for something private or bought elsewhere.

From a shell:

php oc-cli.php market:search maps
php oc-cli.php market:info better-s3
php oc-cli.php market:install better-s3

Active, disabled, not installed

Each card carries one of three state badges, and the difference matters:

Badge	Meaning
Active	Running.
Disabled	Files present, code not running, settings and data kept.
Not installed	Files present, but no data. Either never installed, or already uninstalled.

An active or disabled plugin has two destructive actions, and they do different things:

• Uninstall drops the plugin’s data (its tables and settings), usually for good. The files stay on disk, and the card moves to Not installed.
• Delete files, offered once a plugin is not installed, removes its folder entirely.

To stop a plugin temporarily, disable it. Uninstall only when you are done with its data for good, and delete the files only once you are done with the plugin entirely.

php oc-cli.php plugin:list
php oc-cli.php plugin:deactivate --plugin=better-s3
php oc-cli.php plugin:activate --plugin=better-s3

plugin:deactivate is the fix when a plugin fatals on load and takes the admin panel down with it: see debugging PHP errors.

Updating

Updates appear in the plugins list when the catalog offers a newer version.

php oc-cli.php market:update --all
php oc-cli.php market:update better-s3

Update plugins after updating core, not before: a plugin release usually targets the newest core, while the reverse is not guaranteed.

Configuring

A configurable plugin adds its own screen, reachable from its row in the plugins list. Where that screen lives in the menu is the plugin’s choice: some add a top-level section, most add an entry under Settings or Tools.

Some plugins also carry per-category configuration, set from the category rather than from the plugin.

Choosing well

The catalog will happily install anything listed. Before you add one:

• Check what it last supported. A package declares the ShopClass versions it was tested against.
• Prefer one plugin over three. Every plugin is code running on every request, and a conflict between two is much harder to diagnose than a missing feature.
• Check its support link. Every listed package has one. An unanswered issue tracker tells you what you are buying into.
• Test on a copy before installing on a site with traffic.

When a plugin breaks the site

1. Disable it from a shell: php oc-cli.php plugin:deactivate --plugin=<folder>.
2. Confirm the site recovers.
3. Turn on error logging and reproduce.
4. Report it on the plugin’s own issue tracker, with the detail in how to write a bug report, including your ShopClass and PHP versions.

Locking installs down

On a container deployment you may not want packages installed from the admin at all, since a container’s filesystem is replaced on every redeploy. Set OSC_DISABLE_PACKAGE_INSTALLS=1 to turn off installing and updating from both the market UI and oc-cli.php market:*. See Docker.