Migrating from VirtueMart

Solidshop Migrator (com_solidshopmigrator) is a free, standalone Joomla 6 component that reads a VirtueMart 4 store and writes its catalogue into Solidshop — categories, brands, products, per-language translations, prices, variants, images and stock. You install it on the new site, run it once, and uninstall it.

It exists because migrating off VirtueMart is really two jobs at once: upgrading to Joomla 6 and changing cart. VirtueMart 4 does not run on Joomla 6, so there is no in-place path — the realistic route is a fresh Joomla 6 site with Solidshop on it, and your catalogue pulled across. That is exactly the shape of this tool: it runs on the destination and reads the source, never the other way round.

What migrates

VirtueMart	Becomes
Categories	Joomla categories under a root you choose — the full tree, nesting intact. Solidshop uses Joomla’s own category system, so aliases and access levels come along natively.
Manufacturers	Solidshop brands, linked to their products.
Products	Name, alias, SKU, GTIN (as barcode), published state, featured flag, short and long description, meta description and page title, stock quantity, and weight — converted to your store’s weight unit from whatever VirtueMart recorded (kg, g, lb, oz…).
Translations	Every VirtueMart content-language table becomes a Solidshop product translation. You map each source language to a Joomla language tag on the options step; one is nominated as the default and fills the product’s base fields.
Prices	The default shopper-group price. Where an override price is set and is lower than the base price, the override becomes the selling price and the base becomes the compare-at (strikethrough) price.
Variants	Both VirtueMart mechanisms: child products (Generic Child Variant and Multi Variant) and cart-attribute custom fields. They land on Solidshop’s options and variants, each with its own SKU, price and stock. Per-value price modifiers are resolved into absolute variant prices, and combinations your VirtueMart store never sold are removed rather than left as empty variants.
Images	Copied into images/solidshop/virtuemart-import/ and attached to their products and variants. Shared images are copied once, not once per product.

What does not come across

This is the part worth reading twice. The migrator does not guess: anything it cannot map faithfully is listed in the report by name so you can recreate it deliberately.

• Orders, customers and addresses. Not in version 1. Keep your old database as an archive for accounting; a customer who had an account will need to register again on the new site.
• Tax and calculation rules. Deliberately not mapped — see Prices and tax below.
• Shopper groups and group pricing. Solidshop has no per-group price book yet, so only the default group’s prices are read. Products that carried group-specific prices are listed.
• Coupons, payment and shipment plugin configuration, and vendor configuration. Found, described in the report, never written.
• Reviews. Not in version 1.
• Non-cart custom fields — display-only strings, dates, related-product fields and plugin fields are not product data in Solidshop’s model. The report counts what was left behind.
• Downloadable products are imported as physical products and listed, because Solidshop’s downloadable type is a separate plugin that may not be installed — a wrong guess here produces broken products.
• Extra category and manufacturer assignments. VirtueMart lets a product sit in many categories and carry several manufacturers; Solidshop stores one of each. The first assignment wins and every dropped one is listed with the product and category name, so you can add them back as needed.
• Variants beyond three option axes. Solidshop supports up to three options per product. A product needing four is imported without variants and named in the report along with its option names — it is never silently truncated. The same applies to a product whose combinations would exceed 150.

Before you start

• A Joomla 6 site with Solidshop 1.3.0 or newer, and a store already created. The migrator writes products through the same bulk write path the CSV importer uses, which shipped in Solidshop 1.3.0; the installer refuses to install on an older core rather than failing halfway through a run.
• A VirtueMart 4 source. A VirtueMart 3 store is detected and flagged with a warning — update it to VirtueMart 4 first, on its existing Joomla, before migrating.
• Access to the old database, either as a live connection (host, database name, user, password, table prefix) or as a .sql dump you can upload. A read-only MySQL user is enough, and is what we recommend — the migration never writes to the source.
• Somewhere to read the images from, if you want them: either a copy of the old site’s folder tree on the new server, or the old site’s URL while it is still online.
• The languages you are mapping to, installed on the new site — Joomla content languages must exist before translations can be written to them.

Installing the migrator

Download Solidshop Migrator from the Downloads page and install it the usual way, through System › Install › Extensions. It then appears under Components › Solidshop Migrator. It is free, and it adds nothing to your storefront — no site-side code, no menu entries, no scheduled tasks.

The download is a package holding two extensions: the component (com_solidshopmigrator), which is the wizard you will use, and a console plugin (plg_console_solidshopmigrate) for the command-line route. The plugin installs disabled and does nothing until you turn it on, so there is nothing to decide here — if you never touch the command line, you can ignore it entirely. See Running it from the command line if you do want it.

The migration, step by step

1. Connect to VirtueMart

Choose where the old store lives:

• Live database (recommended) — enter the old site’s MySQL host, database, user, password and table prefix. This is the path to prefer whenever the old site still exists: it is the only mode that can also copy images straight off the old server.
• SQL dump — upload a .sql export instead. Only the VirtueMart tables in it are loaded, into temporary working tables that are removed when you uninstall the migrator. This is the fallback for merchants whose old host is already gone; images then have to be supplied separately as a folder, or skipped.

There is a connection charset setting next to the credentials. Databases from the Joomla 3 era are frequently utf8 (really utf8mb3) or, on very old stacks, latin1. Pick the one that matches; if you are not sure, connect and look at the check below.

Pressing Connect and detect probes the prefix and reports what it found: the VirtueMart version, the content-language tables, counts of products, categories, manufacturers and images — and a handful of sample product names. Read those samples. If accented characters look garbled there, they will be garbled in your new catalogue too; change the charset and reconnect. Catching it here takes ten seconds, catching it afterwards means re-running.

If products belong to more than one VirtueMart vendor, you are told so. Only one vendor is migrated per run.

2. Configure the migration

Setting	What it does
Target store	The Solidshop store the catalogue is written into.
Root category	The VirtueMart category tree is recreated underneath this category, and products without a usable category land here. Choosing Top level creates a category named Imported from VirtueMart to hold them.
Were prices shown including tax?	Prices are copied exactly as VirtueMart stored them either way. Your answer is recorded in the report so you can check the numbers against the tax setup you build afterwards.
Product images	Skip, copy from a folder on this server (give the old site’s root path — the folder that contains images/), or download from the old site’s URL (give its base address). Individual images that cannot be fetched become warnings, never a reason to stop the run.
Languages	One row per VirtueMart content language, each mapped to a Joomla language tag — en_gb is offered as en-GB and so on. Pick which one is the default; the rest become translations.

If the target store already contains products, a confirmation checkbox appears with the current product count. You have to tick it before the run will start.

3. Preview, then run

Preview writes nothing. It reads the whole source through exactly the same mapping code the real run uses and reports every warning the real run would produce — dropped category assignments, products with too many options, missing images, price quirks, calc rules found — along with the counts of what would be created. It is not a separate estimate that can disagree with reality; it is the run with the writing switched off.

Read the preview, fix anything it surfaces (a missing language, a wrong charset, an image path that does not resolve), then press Run the migration. The run works through the catalogue in small chunks with a live progress count, so catalogue size never runs into your host’s PHP time limit. Categories and brands are created first, then products family by family.

When it finishes, download the report. It is a self-contained HTML page you can keep or print: totals, every warning and error keyed to the VirtueMart product id it refers to, and the sections listing what was found but deliberately not migrated. That last part is your to-do list for finishing the move.

4. Uninstall it

Once you are happy with the result, remove Solidshop Migrator from System › Manage › Extensions — uninstall the package, and the component and the console plugin go with it, so nothing is left stranded. Uninstalling drops its working table and any temporary tables left from a dump import; your migrated catalogue is untouched. There is no reason to leave a one-shot tool installed on a live store.

Re-running, resuming and starting over

The migrator keeps a ledger of every source record it created and what it became on this site. That makes three things true, and they are worth relying on:

• A re-run updates, it does not duplicate. Migrate, notice that a language mapping was wrong, fix it and run again — the same products are updated in place.
• A run that dies resumes. If a request times out or the browser is closed, starting again picks up rather than restarting from zero.
• Your edits are mostly safe. The import follows the same rule as the CSV importer: a value the source does not carry is left alone rather than cleared. A field VirtueMart does carry, though, is authoritative — re-running after hand-editing a migrated description will overwrite it.

Start over forgets the connection settings and the run progress so you can migrate a different source. It does not delete anything that was already migrated — remove those products yourself if you want a genuinely clean second attempt.

Prices and tax

Your prices come across exactly as VirtueMart stored them. Your tax rules do not, and that is a deliberate decision rather than a gap.

VirtueMart models tax as free-form calculation rules — arbitrary arithmetic attachable at product, category, vendor or shopper-group level, and used interchangeably for tax, discounts and fees. Solidshop models tax as zones and classes: match the customer’s country and state to a tax zone, look up the rate for that zone and the product’s tax class. There is no faithful automatic translation between the two, and a wrong one produces a store that quietly charges the wrong VAT — the worst failure a migration can hand you.

So the migrator lists every calculation rule it found, with its name, scope and value, in the report. Recreating them as Solidshop tax zones and rates is a small job for a normal single-country store, and one you can verify. See Tax configuration for how.

Running it from the command line

For a very large catalogue, or a host with a brutal execution limit, the same migration runs from Joomla’s CLI. The console plugin came with the migrator package, so there is nothing extra to download — enable Console – Solidshop Migrator in the Plugin Manager, then write a JSON config file carrying what the wizard would have collected:

{
  "connection": {
    "host": "old-db.example.com",
    "database": "old_joomla",
    "user": "readonly",
    "password": "…",
    "prefix": "jos_",
    "charset": "utf8mb4"
  },
  "options": {
    "store_id": 1,
    "root_category_id": 1,
    "vendor_id": 1,
    "default_language": "en_gb",
    "language_map": { "en_gb": "en-GB", "de_de": "de-DE" },
    "prices_include_tax": false,
    "image_mode": "filesystem",
    "image_source": "/var/www/old-site"
  }
}

Then, from your Joomla root:

# Preview — reads everything, writes nothing
php cli/joomla.php solidshop:migrate --config=migration.json --dry-run \
    --report=preview.html

# The real run
php cli/joomla.php solidshop:migrate --config=migration.json \
    --report=report.html

--config is required. --dry-run is the same preview as the wizard’s, and --report=<file> writes the same HTML report the wizard offers for download. --source defaults to virtuemart, which is currently the only source. Progress, counts and every warning are printed as it goes, and the command exits non-zero if any product failed — so it is safe to drive from a script.

After the migration

Working from the report, the usual finishing list is:

1. Rebuild your tax zones and rates from the calculation rules the report lists — Tax configuration.
2. Set up shipping, which does not migrate at all — Shipping.
3. Connect a payment method — Payment methods.
4. Rebuild the handful of products the report named — those with more than three option axes, and any extra category assignments that mattered.
5. Spot-check prices and images across a few products, especially variant prices, before you publish.
6. Walk the go-live checklist, and redirect the old product URLs to the new ones.

If a product needs a change the migrator could not make, remember the CSV importer is available for bulk edits — the migrator writes through the same machinery, so an export, an edit in a spreadsheet and a re-import behaves exactly as you would expect on migrated products.

Honest limits

Version 1 has been verified end to end against a VirtueMart 4.6.4 install with VirtueMart’s official sample data — multi-level child products, Multi Variant matrices, a multi-level category tree, shared images and multiple languages. Real catalogues are messier than sample data, and a few things follow from that:

• Preview first, always. It costs one pass over the source and tells you what the run will do before anything is written.
• Complex or unusual custom-field setups are where surprises live. If the report names products you care about, migrate anyway and fix those by hand — it is a shorter list than the whole catalogue.
• The migrator is one-directional and never modifies VirtueMart. Keep the old site or its dump until you are confident in the new one.
• Found a catalogue it handles badly? Tell us what the report said — the mapping is the part that improves with real-world exposure.