OXID eShop uses database migrations for:
eShop editions migration (CE, PE and EE)
Project specific migrations
OXID eShop uses Doctrine Migrations integrated via OXID eShop migration components.
Prior to v3.0, Doctrine Migrations was not able to collect migrations from multiple folders/namespaces and to specify dependencies between them. But there was a need to run migration for one or all the projects and modules (CE, PE, EE, PR and a specific module). For this reason, we have created the OXID eShop Doctrine Migration Wrapper.
The Doctrine Migration Wrapper needs some information about the OXID eShop installation like:
what edition is active
what are credentials for database
This information is gathered from OXID eShop Facts.
OXID eShop Facts has a class which can provide an information about OXID eShop and its environment. This component is shop-independent and can be used without bootstrap. The only restriction is to have the config.inc.php file configured.
Running migrations - CLI
The script to run migrations is installed within Composer’s bin directory. It accepts two parameters:
Suite Type (CE, PE, EE, PR or a specific module_id)
vendor/bin/oe-eshop-db_migrate <Doctrine_Command> <Suite_Type>
For the comprehensive and up-to-date info, consult the Doctrine Migrations official documentation.
This command will run all the migrations which are in OXID eShop specific directories. If you have the OXID eShop Enterprise edition, for example, the migration tool will run migrations in this order:
Community Edition migrations (executed always)
Professional Edition migrations (executed when eShop has PE or EE)
Enterprise Edition migrations (executed when eShop has EE)
Project specific migrations (executed always)
Module migrations (executed when eShop has at least one module with migration)
Suite Types (Generate migration for a single suite)
It is also possible to run migrations for a specific suite by defining <Suite_Type> parameter in the command. This variable defines what type of migration it is. There are 5 suite types:
PR - For project specific migrations. It should be always used for project development.
CE - Generates migration file for OXID eShop Community Edition. It’s used for product development only.
PE - Generates migration file for OXID eShop Professional Edition. It’s used for product development only.
EE - Generates migration file for OXID eShop Enterprise Edition. It’s used for product development only.
<module_id> - Generates migration file for OXID eShop specific module. It’s used for module development only.
This command generates migration versions for all the suite types.
vendor/bin/oe-eshop-db_migrate migrations:generate EE
In this case, it will be generated only for Enterprise Edition in vendor/oxid-esales/oxideshop_ee/migration directory.
Calling Doctrine Migrations directly:
OXID Migration Wrapper makes it easy to manage complete sets of project’s migrations with a single command. You can always bypass this component and just call Doctrine Migration’s executable directly to use migrations in any other scenario:
# calling OXID Migration Wrapper's executable vs. vendor/bin/oe-eshop-db_migrate # calling Doctrine Migration's executable vendor/bin/doctrine-migrations
to execute a single migration file, run:
vendor/bin/doctrine-migrations execute \ --up \ 'OxidEsales\EshopCommunity\Migrations\Version1234567890' \ --db-configuration 'vendor/oxid-esales/oxideshop-doctrine-migration-wrapper/src/migrations-db.php' \ --configuration source/migration/migrations.yml
Using Migrations Wrapper without CLI
Doctrine Migration Wrapper is written in PHP and also could be used without command line interface. To do so:
executemethod with needed parameters
Put the migration configuration file into the migration folder inside the module’s root directory:
├── migration └── migrations.yml
Example of migrations.yml:
table_storage: table_name: oxmigrations_ddoewysiwyg migrations_paths: 'OxidEsales\WysiwygModule\Migrations': data
To prevent database table name conflicts, include your module’s ID in table_name.
To generate migration versions for a specific module, we must use module_id for <Suite_Type> parameter. Then all the module migration versions will be generated based on the configuration from migrations.yml file in migration folder of the given module.
vendor/bin/oe-eshop-db_migrate migrations:generate ddoewysiwyg
In this case it will be generated only for WYSIWYG module.