at path：
ROOT
/
wp-content
/
plugins
/
elementor
/
migrations
/
README.md
run：
R
W
Run
operations
DIR
2026-04-21 06:48:12
R
W
Run
README.md
11.42 KB
2026-04-21 06:48:12
R
W
Run
Delete
Rename
manifest.json
727 By
2026-04-21 06:48:12
R
W
Run
Delete
Rename
error_log
up
📄
README.md
Save
# Prop Type Migrations ## System Overview This is a **prop type migration system**, not a general data migration system. **Trigger**: Migrations run when it finds a mismatch between data prop type, and actual schema (code) (e.g., `string` → `string-v2`). Without a type change, there's no trigger and no migration. **Scope**: Having mismatch of type (e.g., `string` → `string-v2`) will find all instances of mismatch, and send the object to run migration script on. See [Migration Scope](#migration-scope) for details. ## Appendix - [Structure](#structure) - [Language Design](https://elementor.atlassian.net/wiki/spaces/UE/pages/1999110146/Prop+Types+Migration+Schema+Design+Investigation) - [Paths](#paths) - [Conditions](#conditions) - [Functions](#functions) - [Examples](#examples) ## Structure ### Manifest Manifest describes the different migrations, it can contain widget key migrations and prop-type migrations ```json { "widgetKeys": { "e-logo": [ { "from": "svg", "to": "icon" } ] }, "propTypes": { "string-to-html": { "fromType": "string", "toType": "html", "url": "string-to-html.json" } } } ``` ### Prop Type Migrations Prop type migrations are a set of operations, **up** for upgrade and reverse **down** for downgrade. Prop type migrations support wildcard paths and conditions (see below) ```json { "up": [ { "op": { "fn": "set", "path": "$$type", "value": "html" } } ], "down": [ { "op": { "fn": "set", "path": "$$type", "value": "string" } } ] } ``` ## Paths Path parameter works with wildcard, starting from the **root of the prop object**. **Important**: For **prop type migrations** (the primary use case), paths always start at the prop root—not the widget or document root. For example: - `$$type` refers to the type field at the prop root - `value.nested` refers to `propObject.value.nested` - Wildcards like `value.*` or `value.items[*]` match children within the prop **Widget key migrations** (rare) start at the widget/element root instead. See [Migration Scope](#migration-scope) for details. ## Conditions Conditions check whether to run the migration or not, with many helper functions such as `exists`, conditions can be compounded by `AND` and `OR`. Full list can be found [here](https://elementor.atlassian.net/wiki/spaces/UE/pages/1999110146/Prop+Types+Migration+Schema+Design+Investigation#Available-Conditions) ## Important Notes ### Data Transformations **Migrations do NOT support value transformations.** Migrations are purely structural - they create or update, but can't activate any functions on the data. Handle transformations in transformer code - Migrations change structure: `{ "color": "#fff" }` → `{ "color": { "$$type": "color", "value": "#fff" } }` - Transformers can take current values, and transform them `{ "oldColor": "#fff", "newColor": {} }` -> `{ "oldColor": "#fff", "newColor": { "gradient": "something", "value": "#fff" }}` ### Migration Scope - **Prop Type Migrations**: Operate on a single prop instance, paths start at prop root - **Widget Key Migrations**: Operate on entire widget element, paths start at element root - Migrations run **before** validation and transformation in the data processing pipeline **Example widget:** ```json { "id": "heading-1", "elType": "widget", "widgetType": "e-heading", "settings": { "title": { "$$type": "string", "value": "Hello" }, "tag": { "$$type": "string", "value": "h2" } } } ``` **Prop Type Migration** (e.g., `title` migrating from `string` → `string-v2`): - Operates on **just the prop object**: ```json { "$$type": "string", "value": "Hello" } ``` - Paths are relative to prop root: `$$type`, `value` **Widget Key Migration** (e.g., renaming `tag` → `htmlTag`): - Operates on **the entire widget/element** - Paths are relative to widget **settings** root: `tag`, `title.value` ### Performance Considerations - Migration state is cached per document with version + manifest hash - Cache clears on Elementor version change, manifest change, or feature flag toggle ## Functions ### Set `set` creates or updates data, it can update key / value or both. Full Documentation [here](https://elementor.atlassian.net/wiki/spaces/UE/pages/1999110146/Prop+Types+Migration+Schema+Design+Investigation#set) Params: - key (optional) - value (optional) - merge **default** true - attempts to deep merge objects instead of replace #### Usage Replaces nested key and value ```json { "op": { "fn": "set", "path": "value.*.nested", "value": ["a"], "key": "nested2" } } ``` Appends to array ```json { "op": { "fn": "set", "path": "value.*.nested.[]", "value": "a" } } ``` Creates empty object at path ```json { "op": { "fn": "set", "path": "value.*.nested.[*]" } } ``` ### Delete `delete` removes keys/values at specified path. Full Documentation [here](https://elementor.atlassian.net/wiki/spaces/UE/pages/1999110146/Prop+Types+Migration+Schema+Design+Investigation#delete) Params: - clean **default** true - deletes empty parent paths until reaching an object that has siblings #### Usage Delete specific nested key ```json { "op": { "fn": "delete", "path": "value.deprecated" } } ``` Delete all matching wildcard paths ```json { "op": { "fn": "delete", "path": "value.items[*].legacy" } } ``` Delete without cleaning empty parents ```json { "op": { "fn": "delete", "path": "value.old", "clean": false } } ``` ### Move `move` relocates values from one path to another. Full Documentation [here](https://elementor.atlassian.net/wiki/spaces/UE/pages/1999110146/Prop+Types+Migration+Schema+Design+Investigation#move) Params: - src - Source path - dest - Destination path - clean **default** true - deletes source path after move (will delete empty paths until reaching an object that has siblings) #### Usage Move simple value to new location ```json { "op": { "fn": "move", "src": "value.oldField", "dest": "value.nested.newField" } } ``` Move without cleaning source ```json { "op": { "fn": "move", "src": "value.data", "dest": "value.backup", "clean": false } } ``` Move nested object structure ```json { "op": { "fn": "move", "src": "value.settings", "dest": "value.config.settings" } } ``` ## Examples ### Widget Key Migration: Rename Settings Key **Context**: Rename a widget settings key from `tag` → `htmlTag`. Paths start at **widget settings root**. ```json { "up": [ { "op": { "fn": "set", "path": "tag", "key": "htmlTag" } } ], "down": [ { "op": { "fn": "set", "path": "htmlTag", "key": "tag" } } ] } ``` **Before**: ```json { "id": "heading-1", "elType": "widget", "widgetType": "e-heading", "settings": { "tag": { "$$type": "string", "value": "h2" }, "title": { "$$type": "string", "value": "Hello" } } } ``` **After**: ```json { "id": "heading-1", "elType": "widget", "widgetType": "e-heading", "settings": { "htmlTag": { "$$type": "string", "value": "h2" }, "title": { "$$type": "string", "value": "Hello" } } } ``` ### Prop Type Migration: Change Type **Context**: Migrate `string` → `html` type. Paths start at **prop root**. ```json { "up": [ { "op": { "fn": "set", "path": "$$type", "value": "html" } } ], "down": [ { "op": { "fn": "set", "path": "$$type", "value": "string" } } ] } ``` **Before**: `{ "$$type": "string", "value": "Hello" }` **After**: `{ "$$type": "html", "value": "Hello" }` ### Prop Type Migration: Rename Keys (Simple and Wildcard) **Context**: Rename keys using `key` parameter, with and without wildcards. Paths start at **prop root**. **Simple key rename:** ```json { "up": [ { "op": { "fn": "set", "path": "value.oldName", "key": "newName" } } ], "down": [ { "op": { "fn": "set", "path": "value.newName", "key": "oldName" } } ] } ``` **Wildcard key rename across multiple objects:** ```json { "up": [ { "op": { "fn": "set", "path": "value.*.oldName", "key": "newName" }, "condition": { "fn": "exists", "path": "value.*.oldName" } } ], "down": [ { "op": { "fn": "set", "path": "value.*.newName", "key": "oldName" }, "condition": { "fn": "exists", "path": "value.*.newName" } } ] } ``` **Before** (wildcard example): ```json { "$$type": "responsive", "value": { "desktop": { "oldName": "value1" }, "tablet": { "oldName": "value2" }, "mobile": { "oldName": "value3" } } } ``` **After**: ```json { "$$type": "responsive", "value": { "desktop": { "newName": "value1" }, "tablet": { "newName": "value2" }, "mobile": { "newName": "value3" } } } ``` ### Prop Type Migration: Wildcards with Array Items **Context**: Update all color types in a gradient using array wildcards `[*]`. Paths start at **prop root**. ```json { "up": [ { "op": { "fn": "set", "path": "value.stops[*].color.$$type", "value": "color" }, "condition": { "fn": "equals", "path": "value.stops[*].color.$$type", "value": "string" } } ], "down": [ { "op": { "fn": "set", "path": "value.stops[*].color.$$type", "value": "string" }, "condition": { "fn": "equals", "path": "value.stops[*].color.$$type", "value": "color" } } ] } ``` **Before**: ```json { "$$type": "gradient", "value": { "stops": [ { "position": 0, "color": { "$$type": "string", "value": "#ff0000" } }, { "position": 50, "color": { "$$type": "string", "value": "#00ff00" } }, { "position": 100, "color": { "$$type": "string", "value": "#0000ff" } } ] } } ``` **After**: ```json { "$$type": "gradient", "value": { "stops": [ { "position": 0, "color": { "$$type": "color", "value": "#ff0000" } }, { "position": 50, "color": { "$$type": "color", "value": "#00ff00" } }, { "position": 100, "color": { "$$type": "color", "value": "#0000ff" } } ] } } ``` ### Prop Type Migration: Compound Conditions (AND/OR) **Context**: Use `and`/`or` conditions to selectively migrate items. Paths start at **prop root**. ```json { "up": [ { "op": { "fn": "set", "path": "value.items[*].type", "value": "enhanced" }, "condition": { "fn": "and", "conditions": [ { "fn": "equals", "path": "value.items[*].type", "value": "legacy" }, { "fn": "exists", "path": "value.items[*].data" } ] } }, { "op": { "fn": "set", "path": "value.items[*].migrated", "value": true }, "condition": { "fn": "or", "conditions": [ { "fn": "equals", "path": "value.items[*].type", "value": "enhanced" }, { "fn": "not_exists", "path": "value.items[*].migrated" } ] } } ], "down": [ { "op": { "fn": "set", "path": "value.items[*].type", "value": "legacy" }, "condition": { "fn": "equals", "path": "value.items[*].type", "value": "enhanced" } }, { "op": { "fn": "delete", "path": "value.items[*].migrated" } } ] } ``` **Before**: ```json { "$$type": "list", "value": { "items": [ { "type": "legacy", "data": { "content": "Item 1" } }, { "type": "legacy", "data": { "content": "Item 2" } }, { "type": "new", "data": { "content": "Item 3" } } ] } } ``` **After**: ```json { "$$type": "list", "value": { "items": [ { "type": "enhanced", "data": { "content": "Item 1" } }, { "type": "enhanced", "data": { "content": "Item 2" } }, { "type": "new", "data": { "content": "Item 3" } } ] } } ```