docs: stop recommending updateDestructive for plugins - #2426
Open
Soner (shyim) wants to merge 1 commit into
Open
docs: stop recommending updateDestructive for plugins#2426Soner (shyim) wants to merge 1 commit into
Soner (shyim) wants to merge 1 commit into
Conversation
Plugin install/update only run update(), so document that path and drop empty updateDestructive stubs from plugin migration examples.
Developer Docs healthcheckStatus: Completed with |
Soner (shyim)
marked this pull request as ready for review
August 6, 2026 04:46
Contributor
📊 Documentation Impact Analyzer
Reasons
|
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the Shopware plugin documentation to reflect current core behavior: plugin install/update runs migration update() only, and updateDestructive() should not be recommended for plugin development.
Changes:
- Removed empty
updateDestructive()stubs across multiple plugin migration code examples. - Reworked the plugin database migration guide to focus on
update()and removed destructive/database:migrate-destructiveguidance for plugins. - Adjusted related conceptual and unit test documentation to match the updated migration workflow.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| guides/plugins/plugins/storefront/howto/add-custom-sorting-product-listing.md | Removes unused updateDestructive() stub from migration example. |
| guides/plugins/plugins/framework/data-handling/field-inheritance.md | Removes unused updateDestructive() stub(s) and cleans up the migration example blocks. |
| guides/plugins/plugins/framework/data-handling/add-data-translations.md | Removes unused updateDestructive() stub from migration example. |
| guides/plugins/plugins/framework/data-handling/add-custom-complex-data.md | Removes unused updateDestructive() stub from migration example. |
| guides/plugins/plugins/framework/data-handling/add-complex-data-to-existing-entities.md | Removes unused updateDestructive() stub from migration example. |
| guides/plugins/plugins/database/database-migrations.md | Updates guidance and examples to recommend update() only for plugins; removes destructive command references. |
| guides/plugins/plugins/content/seo/add-custom-seo-url.md | Removes unused updateDestructive() stubs from SEO migration examples. |
| guides/plugins/plugins/content/mail/add-mail-template.md | Removes unused updateDestructive() stub from mail template migration example. |
| guides/plugins/plugins/checkout/document/add-custom-document.md | Removes unused updateDestructive() stub from document migration example. |
| guides/plugins/plugins/checkout/document/add-custom-document-type.md | Removes unused updateDestructive() stubs from document-type related migration examples. |
| guides/plugins/plugins/checkout/cart/tax-provider.md | Removes unused updateDestructive() stub from tax provider migration example. |
| guides/development/testing/unit/php-unit.md | Simplifies the migration unit test sample by removing updateDestructive() invocation. |
| concepts/framework/migrations.md | Aligns the migration concept doc with plugin behavior and clarifies updateDestructive() as core-only usage. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+171
to
+175
| | Command | Arguments | Usage | | ||
| |:-----------------|:------------------------|:-----------------------------------------------------| | ||
| | database:migrate | identifier \(optional\) | Calls the `update()` methods of unhandled migrations | | ||
|
|
||
| The identifier argument is used to decide which migrations should be executed. Per default, the identifier is set to run Shopware Core migrations. To run your plugin migrations, set the identifier argument to your plugin's bundle name, in this example `SwagBasicExample`. | ||
|
|
||
| ```bash | ||
| $ ./bin/console database:migrate SwagBasicExample --all | ||
| ``` | ||
| The identifier argument decides which migrations should be executed. Per default, the identifier is set to run Shopware Core migrations. To run your plugin migrations, set the identifier argument to your plugin's bundle name, in this example `SwagBasicExample`. |
Micha Hobert (Isengo1989)
self-requested a review
August 6, 2026 08:33
Contributor
|
Soner (@shyim) so updateDestructive() still works, but we are not recommending it anymore because there is NO usecase/benefit for plugin developers, correct? Just making sure we are not removing smth that might gives a benefit for some special usecases. |
Member
Author
|
Yes. you need to manually invoke bin/console database:migrate-destructive. It's also originally build for core and was never intended for plugins |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
update(), neverupdateDestructive().update()and clean up inuninstall(); treatupdateDestructive()as core-only and not useful for plugins.updateDestructive()stubs from plugin guide examples, dropdatabase:migrate-destructive/ manual destructive examples from the plugin migration guide, and simplify the related migration unit test sample.Related links
shopware/shopwaretrunk (MigrationStep,MigrationRuntime,PluginLifecycleService::runMigrations()).Checklist
PageRefreferences where relevant..gitbook.yamlif pages were moved, renamed, or deleted..wordlist.txt(and sorted it) if spellcheck flags new legitimate terms.Notes
resources/guidelines/code/core/database-migations.mdwas left unchanged (synced from core; still correct for platform migrations).