---
title: "Migration Guide"
manual: "Contexts"
version: "4.0"
source: "Migration/Index.rst"
rendered: "2026-10-07T05:17:05+00:00"
---

# Migration Guide {#migration}

This guide covers migrating from previous versions of the Contexts extension.

## Migrating from v3.x to v4.0 {#migration-v3-to-v4}

Version 4.0 introduces significant changes for TYPO3 v12/v13 compatibility.

### Breaking Changes {#breaking-changes}

#### PHP Version {#php-version}

**Before:** PHP 7.4 - 8.1

**After:** PHP 8.2+

Update your deployment and CI pipelines accordingly.

#### TYPO3 Version {#typo3-version}

**Before:** TYPO3 v10 - v11

**After:** TYPO3 v12.4 LTS and v13.4 LTS only

TYPO3 v11 and earlier are no longer supported. Use version 3.x for older
TYPO3 installations.

#### Hook Migration {#hook-migration}

All SC_OPTIONS hooks have been replaced with PSR-14 events.

**Before (v3.x):**

```php
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']
    ['processDatamapClass'][] = MyHook::class;
```

**After (v4.0):**

```php
#[AsEventListener(
    identifier: 'my-extension/datahandler',
    event: AfterDatabaseOperationsEvent::class
)]
final class MyEventListener { ... }
```

#### Dependency Injection {#dependency-injection}

Services must now be properly configured for dependency injection.

**Before:** Direct instantiation or makeInstance()

**After:** Constructor injection via Services.yaml

```yaml
services:
  Vendor\MyExtension\Service\MyService:
    public: true
```

### Step-by-Step Migration {#step-by-step-migration}

1.  **Update PHP version** to 8.2 or higher
1.  **Update TYPO3** to v12.4 or v13.4
1.  **Update extension** via Composer:

    ```bash
    composer require netresearch/contexts:^4.0
    ```
1.  **Run database migrations**:

    ```bash
    vendor/bin/typo3 database:updateschema
    ```
1.  **Clear all caches**:

    ```bash
    vendor/bin/typo3 cache:flush
    ```
1.  **Review custom context types** \- update to new interface if needed
1.  **Migrate hooks to events** \- see Event Migration below

### Event Migration Reference {#event-migration-reference}

| Old Hook (SC_OPTIONS) | New PSR-14 Event |
| --- | --- |
| processDatamapClass | AfterDatabaseOperationsEvent |
| filterMenuPages | FilterMenuItemsEvent |
| hook_checkEnableFields | ModifyRecordOverlayEvent |

## Adopting Site Sets (Optional) {#migration-site-sets}

TYPO3 v13 introduces Site Sets as the modern way to manage site configuration.
This is optional and backward compatible.

### Benefits of Site Sets {#benefits-of-site-sets}

-   Cleaner site configuration
-   Composable settings
-   Better multi-site management
-   IDE autocompletion for settings

### Migration Steps {#migration-steps}

1.  In your site configuration, add the contexts set:

    ```yaml
    imports:
      - { resource: "EXT:contexts/Configuration/Sets/Contexts/config.yaml" }
    ```
1.  Move TypoScript constants to site settings:

    **Before (TypoScript Constants):**

    ```typoscript
    plugin.tx_contexts.settings.debug = 1
    ```

    **After (Site Settings):**

    ```yaml
    settings:
      contexts:
        debug: true
    ```
1.  Remove the static TypoScript include (no longer needed with Site Sets)

## Updating Tests {#migration-testing}

Test code must be updated for PHPUnit 10/11 compatibility.

### Annotation to Attribute Migration {#annotation-to-attribute-migration}

**Before:**

```php
/**
 * @test
 * @dataProvider myProvider
 */
public function myTest(): void { }
```

**After:**

```php
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\Attributes\DataProvider;

#[Test]
#[DataProvider('myProvider')]
public function myTest(): void { }
```

### Deprecated Methods {#deprecated-methods}

The `$this->at()` method is removed. Use explicit mock configuration:

**Before:**

```php
$mock->expects($this->at(0))->method('foo')->willReturn('a');
$mock->expects($this->at(1))->method('foo')->willReturn('b');
```

**After:**

```php
$mock->expects($this->exactly(2))
    ->method('foo')
    ->willReturnOnConsecutiveCalls('a', 'b');
```

## Troubleshooting {#migration-troubleshooting}

### Common Issues {#common-issues}

**"Class not found" errors:**

Clear all caches and ensure Composer autoload is regenerated:

```bash
composer dump-autoload
vendor/bin/typo3 cache:flush
```

**Context not matching:**

Enable debug mode to see matching details:

```php
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['contexts']['debug'] = true;
```

**Backend module missing:**

Ensure the extension is properly activated:

```bash
vendor/bin/typo3 extension:activate contexts
```

### Getting Help {#getting-help}

-   GitHub Issues: [https://github.com/netresearch/t3x-contexts/issues](https://github.com/netresearch/t3x-contexts/issues)
-   TYPO3 Slack: #ext-contexts channel