---
title: "Migration Guide"
manual: "Frontend Edit"
version: "2.6"
source: "Migration/Index.rst"
rendered: "2026-10-01T07:11:45+00:00"
---

# Migration Guide {#migration}

This guide helps you migrate between major versions of the extension.

## Version 2.0 {#version-2-0}

Migration from version 1.x to version 2.x.

### Breaking Changes {#breaking-changes}

| Area | Change |
| --- | --- |
| Configuration | TypoScript → Site Settings (see [Site Settings](../Configuration/SiteSettings.html#site-settings)) |
| TYPO3 | v14 added, v12 removed |
| PHP | Minimum 8.2, added 8.5 support |
| Menu Structure | `defaultMenuStructure` options removed |

### Configuration Mapping {#configuration-mapping}

| TypoScript (1.x) | Site Settings (2.x) |
| --- | --- |
| `config.tx_ximatypo3frontendedit_enable` | `frontendEdit.enabled` |
| `plugin.tx_ximatypo3frontendedit.settings.ignorePids` | `frontendEdit.filter.ignorePids` |
| `plugin.tx_ximatypo3frontendedit.settings.ignoreCTypes` | `frontendEdit.filter.ignoreCTypes` |
| `plugin.tx_ximatypo3frontendedit.settings.ignoreListTypes` | `frontendEdit.filter.ignoreListTypes` |
| `plugin.tx_ximatypo3frontendedit.settings.ignoreUids` | `frontendEdit.filter.ignoreUids` |

### Quick Migration {#quick-migration}

1.  **Update** the extension to version 2.x
1.  **Remove** TypoScript configuration for this extension
1.  **Add** Site Settings in `config/sites/<identifier>/settings.yaml`:

    ```yaml
    frontendEdit:
      enabled: true
      filter:
        ignorePids: '1,2,3'
        ignoreCTypes: 'html,div'
    ```
1.  **Clear** all TYPO3 caches

### Menu Customization {#menu-customization}

The `defaultMenuStructure` configuration has been removed.

**Simple edit button only:**

```yaml
frontendEdit:
  showContextMenu: false
```

**Custom menu items:** Use PSR-14 events (see [PSR-14 Events](../DeveloperCorner/Events.html#events))

```php
use TYPO3\CMS\Core\Attribute\AsEventListener;
use Xima\XimaTypo3FrontendEdit\Event\FrontendEditDropdownModifyEvent;

#[AsEventListener]
final class ModifyMenu
{
    public function __invoke(FrontendEditDropdownModifyEvent $event): void
    {
        $event->getMenuButton()->removeChild('history');
    }
}
```

## Need Help? {#need-help}

-   Check the [FAQ](../FAQ/Index.html#faq) for common issues
-   Open an issue on [GitHub](https://github.com/xima-media/xima-typo3-frontend-edit/issues)