Migration Guide 

Breaking Changes 

Fixed Behaviour 

Four defects are fixed by this release:

• The session context and the use_session persistence of the GET parameter context read the frontend user from the removed TypoScriptFrontendController. They now read the frontend.user request attribute and match again.
• Context-aware page caching and config.linkVars were registered on hooks removed in TYPO3 v13.0, so every context variant of a page shared one page cache entry and the switching GET parameter was dropped from generated links. They now use \TYPO3\CMS\Frontend\Event\BeforePageCacheIdentifierIsHashedEvent and \TYPO3\CMS\Frontend\Event\ModifyTypoScriptConfigEvent .
• The FlexForm of the context type configuration was selected via ds_pointerField, removed in TYPO3 v14.0 (forge#107047). On v14.3 every read of tx_contexts_contexts.type_conf threw an InvalidTcaException, so context records could neither be rendered nor saved. See FlexForm Data Structure.
• Frontend caches are invalidated when a context record changes. The result of ModifyTypoScriptConfigEvent is cached under an identifier derived from the TypoScript sources, so a new or renamed GET parameter context previously did not reach config.linkVars until the caches were flushed by hand. See Caching Considerations.

Removed Site Set Settings 

contexts.matchMode and contexts.cacheLifetimeModifier have been removed from Configuration/Sets/Contexts/. Neither setting was ever read by the extension. Remove them from your site configuration; there is no replacement. contexts.debug is unchanged.

Removed Files 

ext_tables.php has been removed - it only held a TYPO3 v12 code path and the file itself is deprecated since TYPO3 v14.3 (forge#109438). The v13+ equivalent lives in Configuration/TCA/tx_contexts_contexts.php via ctrl.security.ignorePageTypeRestriction.

$GLOBALS['TYPO3_CONF_VARS']['FE']['addRootLineFields'] is no longer written in ext_localconf.php; the setting was removed in TYPO3 v13.2 (forge#103752) and rootline relations on pages are always resolved since.

Step-by-Step Migration 

1. Update TYPO3 to v13.4 or v14.3

2. Update extension via Composer:

   composer require netresearch/contexts:^5.0

   Copied!

3. Clear all caches:

   vendor/bin/typo3 cache:flush

   Copied!
4. Review custom context types for the removed protected methods listed above

Breaking Changes 

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

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

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

Step-by-Step Migration 

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

3. Update extension via Composer:

   composer require netresearch/contexts:^4.0

   Copied!

4. Run database migrations:

   vendor/bin/typo3 database:updateschema

   Copied!

5. Clear all caches:

   vendor/bin/typo3 cache:flush

   Copied!
6. Review custom context types - update to new interface if needed
7. Migrate hooks to events - see Event Migration below

Event Migration Reference 

Benefits of Site Sets 

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

Migration Steps 

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

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

   Copied!

2. Configure settings in your site configuration:

   settings:
     contexts:
       debug: false

   Copied!
3. Remove any static TypoScript include (no longer needed with Site Sets)

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');

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