Migrations
OXID eShop uses Doctrine Migrations for database schema and data changes. Migrations can be provided by:
eShop editions (CE, PE, EE)
Project-specific code
Running migrations
The standard command to apply all pending migrations is:
vendor/bin/oe-console oe:database:migrate
This runs migrations from all sources in a single pass:
eShop edition migrations (CE, and PE/EE when applicable)
Project-specific migrations
Component migrations registered via the tagged provider system
Module migrations via the OXID eShop Doctrine Migration Wrapper
Note
Migrations registered via oxid_esales.migration_path_provider execute through
oe:database:migrate, during shop setup, and when the deprecated
oe-eshop-db_migrate migrations:migrate script runs without a suite argument.
They do not run when the deprecated Migrations class is used programmatically.
oe:database:migrate supports the common options of the underlying Doctrine
migrations:migrate command, such as --dry-run, and forwards them to every migration
source. Check the Doctrine Migrations documentation
for the available options.
Example:
vendor/bin/oe-console oe:database:migrate --dry-run
Calling Doctrine Migrations directly
You can call the Doctrine Migrations executable directly to work with a specific configuration, for example to generate a blank migration class:
vendor/bin/doctrine-migrations migrations:generate --configuration=<path-to-migrations.yml>
This places a new Version<YYYYMMDDHHMMSS>.php class in the directory configured under
migrations_paths in the given migrations.yml.
Tagged migrations
Migrations can be registered through the Symfony service container using the
oxid_esales.migration_path_provider DI tag. The shop collects all tagged providers and runs
their migrations as part of oe:database:migrate. This is how components provide their
migrations; project-specific code can register migration paths the same way.
To register a migration path provider, implement MigrationPathProviderInterface and tag the
service in services.yaml.
Registration for a component
Component services are always active, so their migrations are available immediately after
composer require.
<?php
use OxidEsales\EshopCommunity\Internal\Framework\Migration\MigrationPathProviderInterface;
class MyComponentMigrationPathProvider implements MigrationPathProviderInterface
{
public function getMigrationConfigPath(): string
{
return __DIR__ . '/../migration/migrations.yml';
}
}
# services.yaml
services:
MyVendor\MyComponent\MyComponentMigrationPathProvider:
tags:
- { name: 'oxid_esales.migration_path_provider' }
See component-database-migration for the full component migration setup including the
migrations.yml configuration.
Registration for a module
Modules can also register tagged migrations. This is an alternative to the standard module migration setup described in Database Migration, which discovers module migrations automatically.
Note
Module services are only loaded after the module is activated. A migration path provider
registered in a module’s services.yaml will therefore only be picked up by
oe:database:migrate once the module has been activated via oe:module:activate.
<?php
use OxidEsales\EshopCommunity\Internal\Framework\Migration\MigrationPathProviderInterface;
class MyModuleMigrationPathProvider implements MigrationPathProviderInterface
{
public function getMigrationConfigPath(): string
{
return __DIR__ . '/../migration/migrations.yml';
}
}
# services.yaml
services:
MyVendor\MyModule\MyModuleMigrationPathProvider:
tags:
- { name: 'oxid_esales.migration_path_provider' }
The migrations.yml file is placed in the migration folder of the module:
├── migration
│ ├── migrations.yml
│ └── data
│ └── Version20240101000000.php
Example migrations.yml:
table_storage:
table_name: myvendor_mymodule_migrations
migrations_paths:
'MyVendor\MyModule\Migrations': data
Tip
To prevent database table name conflicts, include your module’s ID in table_name.
See Database Migration for the full module migration setup.