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 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
hook_checkEnableFields	AfterPageAndLanguageIsResolvedEvent
filterMenuPages	FilterMenuItemsEvent
overrideIconOverlay (IconFactory)	ModifyRecordOverlayIconIdentifierEvent
createHashBase	ModifyCacheLifetimeForPageEvent

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" }

Configure settings in your site configuration:

settings:
  contexts:
    debug: false
    matchMode: 'all'

Remove any static TypoScript include (no longer needed with Site Sets)

Updating Tests

Test code must be updated for PHPUnit 10/11/12/13 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