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.

Cache Lifetime Modification 

CacheHashEventListener listens to ModifyCacheLifetimeForPageEvent and can adjust cache lifetime based on active contexts.

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 

$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
       matchMode: 'all'

   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 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.