The WooCommerce migration is a setup task, not a script you run

There is no migration binary here, and that is the design

Start with the repository layout, because it is unusually small and it explains the package. The top level holds a LICENSE, the readme, a composer.json, a manifest.php, a phing.xml build file, and a setup directory. There is no src directory and no Tests directory. So the entire implementation is a set of setup tasks, and the package's real content lives in that one directory. This is why the readme's migration section has no command of its own to show you. Installing the package is a composer require inside an existing Aimeos setup, and running the migration is the same command that installs or updates Aimeos itself:

composer req aimeos/ai-woocommerce

then, later:

php artisan aimeos:setup

The readme describes that second command as executing all setup tasks including those from the ai-woocommerce package. A package that hangs its work off the framework's own setup pipeline inherits the framework's ordering, its error handling and its transaction boundaries, which is the sensible choice for a one-time data move that has to be consistent with the schema it is writing into. It also means you cannot run the migration without running the rest of the setup, which is precisely why the caution about demo data exists. The manifest.php is the Aimeos extension manifest, which is how the setup command discovers that these tasks exist. The phing.xml build file is the Ant build, consistent with the rest of this package family, and its presence next to a package with no source directory is a reminder that the Aimeos ecosystem builds extensions uniformly regardless of how little code each one contains.

The migration connects to WordPress as a second database resource

How the migration reaches your old data is a configuration addition rather than a command-line argument. The readme says to configure the WordPress database in the Laravel shop configuration file, adding a resource entry alongside the existing database connection. The shape is a resource map with a db key holding the existing settings and a db-woocommerce key holding an adapter of mysql, a host, a port, a database name of wordpress, a username and a password. The reason this is a resource rather than a connection string is that the Aimeos setup task reads it through the same configuration layer as everything else, so a second database is just another named resource, and the same credential can be pointed at a replica for the run. Two details are easy to get wrong. The host is a loopback address in the example, so if the WordPress database is on a different machine you have to change it and make sure that machine accepts the connection. And the credential belongs to the WordPress database, not to Aimeos, so a migration account with read-only rights on the source is the right shape, if the setup task does not require write access to it. The readme does not say which permissions the task needs, so assume read on the source and write on the target, and grant nothing more than that until you have seen it work.

Two ordering constraints, and one of them the readme does not explain

The caution line is the densest sentence in the readme and it carries two requirements. The first is that the Aimeos installation must contain no demo data. The reason is not stated, but it follows from what the migration does: it writes products, categories, brands and attributes into a catalogue, and a catalogue seeded with sample products is a catalogue the migration will have to coexist with. Depending on whether the setup tasks clear or append, you end up with a shop containing both your real products and someone else's samples, which is the kind of mistake that reaches production. Remove the demo data before you run it, not after. The second requirement is that the db-woocommerce resource sits at the end of the resource list. That one is also unexplained, and the order-sensitivity is the tell. A resource list is an ordered structure, and if the setup tasks resolve resources in order then the WooCommerce connection has to be established after the primary one is in place, so that the tasks read from the source and write to the target in that sequence. That is inference from the requirement rather than something the readme states, and the honest way to treat it is as an instruction with an unknown reason, which means follow it exactly rather than rearranging the config for tidiness. Both constraints are cheap to satisfy and expensive to debug after a failed run.

What actually migrates, and the word that qualifies it

The readme lists the migrated entities and the list is short enough to read as a specification. Products. Categories. Suppliers and brands. Attributes and attribute types. Then a fifth item: extra product options from a WooCommerce extension, and it is qualified as partly done. That single adverb is the most important word in the readme, because extra product options are exactly where WooCommerce installations accumulate bespoke data. A shop selling, say, made-to-order goods with an options extension carries configuration there that no generic schema can represent, and a partial migration means those options either arrive incomplete or are dropped. Nothing in the readme says which extension is meant, which options survive, or how to detect loss, so if your catalogue depends on extension-supplied product options you need a manual audit after the run. The absence of other entities is equally informative. Orders, customers, coupons, addresses, payment records and download links are not in the list, which is defensible for a tool that describes itself as migrating a database rather than a business, but it means this is a catalogue migration and not a business migration. If you need order history and customer accounts to move as well, this package is one part of a project rather than the whole of it.

The last step is deleting your own credentials

The readme closes with an instruction that is easy to skim: if everything works correctly, remove the db-woocommerce database settings from your configuration again. That sentence contains an implicit acceptance test and a security cleanup, and both matter. The acceptance test is yours, because nothing in the readme describes how to verify a migration: no counts to compare, no report to read, no dry run to preview. The cleanup is the part with a security dimension. During the run your shop configuration holds a second set of database credentials in plain text, and the recommended workflow is to leave it there until you are satisfied, which means it will be present in your deployed configuration for as long as you take to check the result. If that configuration file is under version control, or is deployed through a pipeline, or is readable by anyone who can see your environment, you have created a credential exposure window. Two practices reduce it. Use a read-only WordPress account rather than an administrator credential. Remove the resource block immediately after the run rather than when you remember. And compare the product counts on both sides, because a partial migration and a successful one look identical from the shop's front end until someone notices a category is empty.

Licence, maintenance, and what a five-file repository tells you

The licence is LGPL-2.1, and the package is a one-shot utility rather than a runtime dependency, which means the licensing question is smaller than it would be for the adapters in this family: you run it, you get your data across, and then it is out of your dependency tree. That is worth doing deliberately, because leaving a migration package installed means leaving a live second database connection in your shop configuration, and the readme's own instruction to remove those settings is the first step of uninstalling it properly. On maintenance, the last push to the master branch was on 2026-04-29 and the repository publishes no GitHub releases, so there is no tag history to consult and the composer constraint is what identifies a version. The stated requirement is Aimeos 2023.10 or later, which is a floor rather than a tested range, and since this package executes inside the Aimeos setup pipeline, an Aimeos upgrade is the event that can break it. The absence of a Tests directory at the top level is worth noting plainly, and the readme does not claim otherwise: this is a package whose correctness is established by running it once against your own data, not by an automated suite. Plan the run accordingly, with a snapshot of both databases and a count comparison afterwards.

Editorial conclusion

Use ai-woocommerce if you are moving catalogue data from a WooCommerce store into Aimeos 2023.10 or later and your products are mostly products, categories, brands and attributes, because that is the whole of what the readme says migrates, and the mechanism is clean: point the shop config at the WordPress database and let the Aimeos setup command run the package's tasks in order. Do not treat it as a full site migration, because orders, customers, coupons and payment history are absent from the list of migrated entities, and the one extension-related item is qualified as partly migrated. Four things to verify before you start. That the Aimeos installation has no demo data, because the readme flags this as a caution and running a migration into a shop seeded with samples produces a catalogue with invented products in it. That the database resource for WooCommerce sits at the end of the resource list, which the readme also flags and does not explain. That you have a restorable copy of both databases, since the readme documents no rollback and no dry run, only a suggestion to remove the connection settings afterwards if things worked. And that you remove those credentials once the run succeeds, because they are a second database account sitting in your shop configuration in plain text. The licence is LGPL-2.1 and the last push was on 2026-04-29.

Frequently asked questions

Official sources

1. aimeos/ai-woocommerce on GitHub
2. Issues
3. License: LGPL-2.1
4. README