Migration Guide

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

Migrating from v3.x to v4.0

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

Breaking Changes

PHP Version

Before: PHP 7.4 - 8.1

After: PHP 8.2+

Update your deployment and CI pipelines accordingly.

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

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

Before (v3.x):

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

After (v4.0):

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

Dependency Injection

Services must now be properly configured for dependency injection.

Before: Direct instantiation or makeInstance()

After: Constructor injection via Services.yaml

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

Step-by-Step Migration

Update PHP version to 8.2 or higher
Update TYPO3 to v12.4 or v13.4

Update extension via Composer:

composer require netresearch/contexts:^4.0

Run database migrations:
```
vendor/bin/typo3 database:updateschema
```
Copied!
Clear all caches:
```
vendor/bin/typo3 cache:flush
```
Copied!
Review custom context types - update to new interface if needed
Migrate hooks to events - see Event Migration below

Event Migration Reference

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

Adopting Site Sets (Optional)

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

Benefits of Site Sets

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

Migration Steps

In your site configuration, add the contexts set:

imports:
  - { resource: "EXT:contexts/Configuration/Sets/Contexts/config.yaml" }

Move TypoScript constants to site settings:

Before (TypoScript Constants):
```
plugin.tx_contexts.settings.debug = 1
```
Copied!
After (Site Settings):
```
settings:
  contexts:
    debug: true
```
Copied!
Remove the static TypoScript include (no longer needed with Site Sets)

Updating Tests

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

Annotation to Attribute Migration

Before:

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

After:

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

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

Deprecated Methods

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

Before:

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

After:

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

Troubleshooting

Common Issues

"Class not found" errors:

Clear all caches and ensure Composer autoload is regenerated:

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

Context not matching:

Enable debug mode to see matching details:

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

Backend module missing:

Ensure the extension is properly activated:

vendor/bin/typo3 extension:activate contexts

Getting Help

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