Configuration 

Examples:

• Single IP: 192.168.1.100
• CIDR notation: 10.0.0.0/8, FE80::/16
• Range: 192.168.1.1-192.168.1.255
• Wildcards: 80.76.201.*, 80.76.*.37
• Multiple: 192.168.1.0/24,10.0.0.0/8

Use Cases 

• Internal network detection (show admin tools for office IPs)
• Geographic content (by IP geolocation with contexts_geolocation)
• Office vs. external visitor differentiation
• Development/staging environment detection

Configuration 

Matching Rules:

• Without leading dot: Exact match only

  • www.example.org will not match example.org

• With leading dot: Matches all subdomains

  • .example.org matches www.example.org, shop.example.org, etc.

Examples:

• Single: www.example.com

• Multiple (one per line):

  example.com
  www.example.com

  Copied!
• Subdomain wildcard: .example.com

Use Cases 

• Multi-domain setups (different content per domain)
• Staging vs. production detection
• Brand-specific content on shared installations
• Language-specific domains

Configuration 

Examples:

• ?debug=1 with parameter debug and value 1
• ?variant=a for A/B testing
• ?affID=partner for affiliate tracking

Use Cases 

• A/B testing variants
• Debug mode activation
• Campaign and affiliate tracking
• Feature flags via URL

Configuration 

Mobile
Android
iPhone

Use Cases 

• CDN or proxy detection (X-Forwarded-For, CF-Connecting-IP)
• Mobile device detection via User-Agent
• Accept-Language based content
• Custom application headers
• Bot detection

Configuration 

Use Cases 

• User state tracking
• Shopping cart state (cart has items)
• Login/authentication state
• Multi-step form progress
• User preference flags

Configuration 

Operators:

• && - logical AND (all must match)
• || - logical OR (any must match)
• ! - negation (must NOT match)
• (...) - parentheses for grouping

Examples:

• mobile && !tablet - Mobile but not tablet
• internal || admin - Internal network or admin user
• (german || austrian) && !guest - German-speaking non-guest
• campaign_a && !already_converted - Campaign A visitors who haven't converted

Use Cases 

• Complex multi-condition business rules
• Nested context hierarchies
• Exclusion rules (show to A but not if B)
• Compound targeting (A AND B OR C)

Step 1: Create the Context Class 

Extend AbstractContext and implement the match() method:

<?php

declare(strict_types=1);

namespace Vendor\MyExtension\Context\Type;

use Netresearch\Contexts\Context\AbstractContext;
use Netresearch\Contexts\Context\Container;

final class MyCustomContext extends AbstractContext
{
    public function match(array $arDependencies = []): bool
    {
        $configuredValue = $this->getConfValue('myField');
        $actualValue = $this->getActualValue();

        return $this->invert($this->storeInSession(
            $configuredValue === $actualValue
        ));
    }

    private function getActualValue(): string
    {
        $request = Container::get()->getRequest();
        if ($request === null) {
            return '';
        }

        $params = $request->getQueryParams();
        return $params['myParam'] ?? '';
    }
}

Step 2: Register the Context Type 

In your ext_localconf.php:

<?php

use Vendor\MyExtension\Context\Type\MyCustomContext;

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['contexts']['types']
    ['my_custom'] = [
    'class' => MyCustomContext::class,
    'label' => 'LLL:EXT:my_extension/Resources/Private/'
        . 'Language/locallang.xlf:context.my_custom',
];

Step 3: Add TCA Configuration 

In Configuration/TCA/Overrides/tx_contexts_contexts.php:

<?php

$GLOBALS['TCA']['tx_contexts_contexts']['types']
    ['my_custom'] = [
    'showitem' => 'type, title, '
        . '--palette--;;visibility, my_field',
];

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTCAcolumns(
    'tx_contexts_contexts',
    [
        'my_field' => [
            'label' => 'My Field',
            'config' => [
                'type' => 'input',
            ],
        ],
    ]
);

Page Access Control 

PageAccessEventListener listens to AfterPageAndLanguageIsResolvedEvent and checks whether the current page is accessible based on its context restrictions (tx_contexts_enable / tx_contexts_disable). If access is denied, it throws an ImmediateResponseException with a 403 response.

The current page is always checked for its own context restrictions. Parent pages only propagate restrictions when extendToSubpages is enabled.

Menu Item Filtering 

MenuItemFilterEventListener listens to FilterMenuItemsEvent and removes menu items that should not be visible in the current context. This ensures navigation menus reflect context-based visibility.

Icon Overlay Modification 

IconOverlayEventListener listens to ModifyRecordOverlayIconIdentifierEvent and modifies icon overlays for records that have context-based visibility settings, providing visual feedback in the backend.

Page Cache Identifier 

PageCacheIdentifierEventListener listens to BeforePageCacheIdentifierIsHashedEvent and adds the current values of all GET parameters used by a "getparam" context to the page cache identifier. Without it, a page rendered with a context-switching parameter would overwrite the cache entry of the same page rendered without it.

TypoScript config.linkVars 

TypoScriptConfigEventListener listens to ModifyTypoScriptConfigEvent and appends the GET parameters of all "getparam" contexts to config.linkVars , so the active channel survives following a link. It replaces the configArrayPostProc hook that was removed in TYPO3 v13.0 (#102932).

The parameter list is derived from the configured contexts, never from the current request, because the event result is written into the TypoScript cache. See Caching Considerations for how that cache is invalidated when a context record changes.

FlexForm Data Structure 

FlexFormDataStructureEventListener listens to BeforeFlexFormDataStructureIdentifierInitializedEvent and BeforeFlexFormDataStructureParsedEvent and resolves the FlexForm of tx_contexts_contexts.type_conf from the context type of the record.

TYPO3 v14 removed the ds_pointerField mechanism and the multi-entry ds array (Breaking #107047) that this used to rely on. The replacement core suggests, record types plus types.<type>.columnsOverrides, cannot be used here: TYPO3 v13.4 resolves the data structure from the raw TCA in DataHandler and ReferenceIndex, where columnsOverrides is not applied. These two events are dispatched by FlexFormTools for every caller and have an identical API in v13.4 and v14.3.

For extension authors this is transparent: Configuration::registerContextType() keeps its signature, and the FlexForm file passed as its fourth argument is still the data structure used for that type. Only code that read the FlexForm file back out of $GLOBALS['TCA']['tx_contexts_contexts']['columns']['type_conf']['config']['ds'] has to switch to Configuration::getContextTypes()[$type]['flexFile'] .

Request Lifecycle 

The ContainerInitialization PSR-15 middleware initializes context matching on every frontend request. It:

1. Sets the PSR-7 request on the Container singleton
2. Triggers Container::initMatching() which loads all context records from the database and runs match() on each
3. Only matched contexts are retained in the container

This middleware runs before the page resolver, ensuring contexts are available throughout the rendering pipeline.

Query Restrictions 

The ContextRestriction class implements EnforceableQueryRestrictionInterface and automatically adds WHERE clauses to all database queries on context-controlled tables. It uses FIND_IN_SET() to check whether active context UIDs appear in the tx_contexts_enable or tx_contexts_disable columns.

This means records with context restrictions are automatically filtered in all frontend queries without additional code.

Checking Contexts Programmatically 

The Container class provides access to all matched contexts. It uses a singleton pattern and extends ArrayObject.

<?php

declare(strict_types=1);

use Netresearch\Contexts\Context\Container;

// Get the container instance (singleton)
$container = Container::get();

// Find a specific context by alias or UID
$context = $container->find('my-context-alias');
if ($context !== null) {
    // Context exists and is active (matched)
}

// Iterate over all active (matched) contexts
foreach (Container::get() as $uid => $context) {
    echo $context->getAlias() . ' is active';
}

Using the ContextMatcher API 

For simple matching checks, use the ContextMatcher API:

<?php

declare(strict_types=1);

use Netresearch\Contexts\Api\ContextMatcher;

if (ContextMatcher::getInstance()->matches('mobile')) {
    // Mobile context is active
}

Configuration API 

Enable context settings on custom tables using the Configuration API:

<?php

use Netresearch\Contexts\Api\Configuration;

// Add default visibility settings (enable/disable)
Configuration::enableContextsForTable(
    'contexts',
    'my_table'
);

// With additional custom settings
Configuration::enableContextsForTable(
    'contexts',
    'my_table',
    [
        'my_setting' => [
            'label' => 'LLL:EXT:my_ext/Resources/'
                . 'Private/Language/locallang.xlf:setting',
            'flatten' => true,
            'enables' => true,
        ],
    ]
);

This registers the tx_contexts_settings column, adds flat columns (tx_contexts_enable, tx_contexts_disable), and integrates context visibility into the record editing form.

Record API 

Check if a record is enabled for the current contexts:

<?php

declare(strict_types=1);

use Netresearch\Contexts\Api\Record;

// Check if a record is visible in current context
$row = ['uid' => 42, 'tx_contexts_enable' => '3,5'];
if (Record::isEnabled('tt_content', $row)) {
    // Record is visible
}

// Check a specific setting
if (Record::isSettingEnabled('my_table', 'my_setting', $row)) {
    // Setting is enabled for this record
}

TypoScript Conditions 

Use the contextMatch() function in TypoScript conditions:

# Show content only when mobile context is active
[contextMatch('mobile')]
    page.10.wrap = <div class="mobile-wrapper">|</div>
[END]

# Combine with other conditions
[contextMatch('internal') && tree.level > 2]
    lib.breadcrumb.show = 1
[END]

The contextMatch() function is provided via TYPO3's ExpressionLanguage and works in all condition contexts (TypoScript, TSconfig, etc.).

Register the Namespace 

Add the namespace to your Fluid template:

<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
      xmlns:contexts="http://typo3.org/ns/Netresearch/Contexts/ViewHelpers"
      data-namespace-typo3-fluid="true">

Or use the inline namespace declaration:

{namespace contexts=Netresearch\Contexts\ViewHelpers}

Using the Matches ViewHelper 

Check if a context is active using the matches ViewHelper:

<f:if condition="{contexts:matches(alias: 'mobile')}">
    <f:then>
        <p>Mobile context is active</p>
    </f:then>
    <f:else>
        <p>Mobile context is not active</p>
    </f:else>
</f:if>

The ViewHelper returns 1 when the context matches and 0 otherwise, making it compatible with Fluid's condition evaluation.

Practical Examples 

Conditional rendering based on context:

<f:if condition="{contexts:matches(alias: 'internal')}">
    <div class="admin-toolbar">
        <!-- Only shown for internal network -->
    </div>
</f:if>

Combining with other conditions:

<f:if condition="{contexts:matches(alias: 'premium')} && {user}">
    <div class="premium-content">
        <!-- Premium user content -->
    </div>
</f:if>

Running Tests 

Tests can be run via Composer scripts or the Docker-based runTests.sh script.

Composer scripts (local PHP required):

# Unit tests
composer ci:test:php:unit

# Functional tests (requires database)
composer ci:test:php:functional

# Static analysis
composer ci:test:php:phpstan

# Code style check
composer ci:test:php:cgl

Docker-based (no local PHP needed):

# Unit tests (default suite)
./Build/Scripts/runTests.sh -s unit

# Unit tests with coverage
./Build/Scripts/runTests.sh -s unitCoverage

# Functional tests with SQLite
./Build/Scripts/runTests.sh -s functional -d sqlite

# PHPStan
./Build/Scripts/runTests.sh -s phpstan

# With specific PHP version
./Build/Scripts/runTests.sh -s unit -p 8.4

# Show all options
./Build/Scripts/runTests.sh -h

The Docker-based script uses ghcr.io/typo3/core-testing-php* images and requires Docker or Podman.

Writing Tests for Custom Contexts 

<?php

declare(strict_types=1);

namespace Vendor\MyExtension\Tests\Unit\Context\Type;

use PHPUnit\Framework\Attributes\Test;
use TYPO3\TestingFramework\Core\Unit\UnitTestCase;
use Vendor\MyExtension\Context\Type\MyCustomContext;

final class MyCustomContextTest extends UnitTestCase
{
    #[Test]
    public function matchReturnsTrueForValidCondition(): void
    {
        $context = new MyCustomContext();
        // Setup test conditions

        self::assertTrue($context->match());
    }
}

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

Breaking Changes 

• Dropped TYPO3 v12.4 support - use version 4.x for TYPO3 v12.4
• Removed ext_tables.php - deprecated in TYPO3 v14.3 (forge#109438)
• Removed FrontendControllerService::registerQueryParameter(), ::createHashBase() and ::configArrayPostProc()
• Removed PageService::createHashBase() - use the public PageService::getHashString()
• Removed the empty CacheHashEventListener
• Removed the protected AbstractContext::getTypoScriptFrontendController() and AbstractContext::getIndpEnv() - custom context types use getRequest(), getFrontendUser() and getNormalizedParams()
• Dropped the unused typo3/cms-extbase and typo3/cms-extensionmanager requirements - no class of either package is referenced
• Removed the site set settings contexts.matchMode and contexts.cacheLifetimeModifier - neither was ever read by the extension
• Configuration::registerContextType() no longer writes the FlexForm file into TCA[tx_contexts_contexts][columns][type_conf][config][ds]; the data structure is resolved from the context type registry instead

Bug Fixes 

• Context records can be edited on TYPO3 v14.3 again - ds_pointerField and the multi-entry ds array were removed in TYPO3 v14.0 (forge#107047), so every read of tx_contexts_contexts.type_conf threw an InvalidTcaException. FlexFormDataStructureEventListener resolves the data structure through the PSR-14 BeforeFlexFormDataStructure* events, which behave identically on v13.4 and v14.3
• Frontend caches are invalidated when a context record changes - saving, deleting or restoring a context flushes the pages cache group. TYPO3 caches the ModifyTypoScriptConfigEvent result under an identifier derived from the TypoScript sources, so a new or renamed GET parameter context previously never reached config.linkVars
• Session context matches again - the frontend user is read from the frontend.user request attribute instead of the TypoScriptFrontendController removed in TYPO3 v14 (forge#107831). The same applies to the use_session persistence of the GET parameter context
• Context-aware page caching works again - the active contexts and the values of all context GET parameters are added to the page cache identifier via \TYPO3\CMS\Frontend\Event\BeforePageCacheIdentifierIsHashedEvent , replacing the createHashBase hook removed in TYPO3 v13.0 (forge#102932)
• config.linkVars works again - the GET parameters of all query parameter contexts are appended via \TYPO3\CMS\Frontend\Event\ModifyTypoScriptConfigEvent , replacing the removed configArrayPostProc hook
• Page tree restrictions are no longer dropped - the PageTreeRepository XCLASS forwards the third $additionalQueryRestrictions constructor argument, so options.pageTree.excludeDoktypes is honoured again
• Removed the write to $TYPO3_CONF_VARS['FE']['addRootLineFields'], removed in TYPO3 v13.2 (forge#103752)

Improvements 

• CI matrix covers TYPO3 ^13.4 and ^14.3 on PHP 8.2 - 8.5
• composer.json declares extra.typo3/cms.version and extra.typo3/cms.Package.providesPackages (forge#108345)
• Rector and Fractor run the TYPO3 v14 rule sets; the one rule that may not be applied while TYPO3 v13.4 is supported is skipped explicitly
• PHPStan enables reportUnmatchedIgnoredErrors and drops the 27 ignore patterns that no longer matched anything
• DDEV development environment provides TYPO3 v13 and v14 instances

Breaking Changes 

• Dropped TYPO3 v11 support - Use version 3.x for TYPO3 v11
• Dropped PHP 7.4/8.0/8.1 support - Minimum PHP 8.2 required
• Removed SC_OPTIONS hooks - Migrated to PSR-14 events
• PHPUnit 10/11/12/13 required - Test code must use new patterns

New Features 

• TYPO3 v12.4 LTS support - Full compatibility with TYPO3 v12
• TYPO3 v13.4 LTS support - Full compatibility with TYPO3 v13
• Site Sets support - Modern site configuration for TYPO3 v13
• PHP 8.2/8.3/8.4/8.5 support - Latest PHP versions supported
• PSR-14 events - Modern event dispatching system
• PHP 8 Attributes - Native attribute-based configuration
• Docker-based runTests.sh - TYPO3 core testing pattern

Improvements 

• Modernized codebase with strict types
• Enhanced IDE support through better typing
• Improved test coverage (target: 80%+)
• Mutation testing - Infection with MSI > 80%
• PHPStan level 10 compliance
• Updated coding standards (PSR-12)

Migration 

See Migration Guide for detailed upgrade instructions.