TYPO3 Context: How to Set and Use TYPO3 Application Context in TYPO3 v14, v13 and v12

What Is TYPO3 Context?

TYPO3 Context tells TYPO3 which environment is handling the current request.

• It separates local, staging, testing, and production configurations.
• It helps TYPO3 load the right settings for each environment.
• It prevents development settings from reaching the live website.

What TYPO3_CONTEXT does

TYPO3_CONTEXT is the environment variable that defines the current TYPO3 Application Context.

• It tells TYPO3 whether the project runs in development, staging, testing, or production.
• It can control database settings, site URLs, debugging, cache behavior, CLI commands, PHP logic, and TypoScript conditions.
• It works as the main environment switch for TYPO3 configuration.

Default TYPO3 Context: Production

If no context is set, TYPO3 falls back to Production.

• This keeps live websites safe by default.
• Developers should still define clear contexts for local and staging environments.
• For example, use Development/DDEV locally and Production/Staging for staging.

Main contexts: Production, Development, Testing

TYPO3 supports three root contexts.

• Production: for live or production-like environments.
• Development: for local and development work.
• Testing: for automated test workflows, not normal staging.

Sub-context examples

TYPO3 also supports sub-contexts for more specific setups.

• Development/Local
• Development/DDEV
• Production/Staging
• Production/Live

When Should You Use TYPO3 Application Context?

Use TYPO3 Application Context when one TYPO3 project needs different behavior across multiple environments.

• Local development needs debugging and test services.
• Staging needs preview URLs and production-like behavior.
• Production needs secure credentials, hidden errors, and optimized settings.

Local development and debugging

Use TYPO3 Context to make local development safer and easier.

• Enable detailed errors only in development.
• Use local database and mail testing tools.
• Keep local settings separate from staging and production.

Staging and preview environments

Use a staging context before changes reach the live website.

• Set a separate staging base URL.
• Test production-like behavior before release.
• Prefer Production/Staging when staging should behave like production.

Production security and performance settings

Use TYPO3 Context to protect live websites.

• Disable visible errors in production.
• Keep debug tools away from public users.
• Enable production-ready cache, compression, and logging rules.

Different database, mail, cache, logging, and site URL settings

Use context-based configuration whenever settings change by environment.

• Separate database credentials.
• Separate mail transport or SMTP settings.
• Separate site URLs, cache rules, API keys, and logging levels.

Important Rules Before Setting TYPO3_CONTEXT

Set TYPO3_CONTEXT before TYPO3 starts.

• TYPO3 reads the Application Context early in the bootstrap process.
• Do not create the context inside additional.php.
• Use valid root contexts before adding sub-contexts.

TYPO3 reads Application Context before bootstrap

• TYPO3 sets the current Application Context very early in the bootstrap process.
• This means the value must already be available before TYPO3 handles the request.
• If it is missing, TYPO3 falls back to Production.

TYPO3 checks context values in this order

TYPO3 checks these values before using the default:

1. TYPO3_CONTEXT
2. REDIRECT_TYPO3_CONTEXT
3. HTTP_TYPO3_CONTEXT
4. Production

Add this because it answers a common troubleshooting question.

Do not set Application Context inside additional.php

Do not define TYPO3_CONTEXT inside config/system/additional.php.

• TYPO3 has already detected the context before this file is used.
• Use additional.php to read the context and load different settings.
• Do not use it to create the context itself.

Root context must be Production, Development, or Testing

The first part of the context must be one of TYPO3’s root contexts.

• Correct: Development/DDEV
• Correct: Production/Staging
• Wrong: Staging
• Wrong: Live

Do not use Testing for staging

Do not use Testing as a normal staging environment.

• Testing is for automated test workflows.
• Use Production/Staging for production-like staging.
• Use Development/Local or Development/DDEV for local work.

How to Set TYPO3 Context

Set TYPO3_CONTEXT at server, environment, or shell level.

• Use Apache or Nginx for web requests.
• Use DDEV or .env for local development.
• Use shell variables for CLI commands.

Set TYPO3 Context in Apache vHost or .htaccess

Use Apache SetEnv for a fixed context.

SetEnv TYPO3_CONTEXT Development

Use this for simple local, development, or single-environment setups.

Set TYPO3 Context with Apache SetEnvIf by domain

Use SetEnvIf when context depends on the hostname.

SetEnvIf Host "^dev\.example\.com$" TYPO3_CONTEXT=Development
SetEnvIf Host "^staging\.example\.com$" TYPO3_CONTEXT=Production/Staging
SetEnvIf Host "^www\.example\.com$" TYPO3_CONTEXT=Production

This is useful when dev, staging, and live use different domains.

Set TYPO3 Context in Nginx / PHP-FPM

Pass the context to PHP-FPM with fastcgi_param.

location ~ \.php$ {
  include fastcgi_params;
  fastcgi_param TYPO3_CONTEXT Production/Staging;
  fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Set TYPO3 Context in DDEV

For DDEV, use Development/DDEV in .ddev/config.yaml.

web_environment:
- TYPO3_CONTEXT=Development/DDEV

Then restart DDEV:

ddev restart

DDEV’s own TYPO3 CMS settings documentation uses Development/DDEV with web_environment, so this should replace the simpler Development example.

Set TYPO3 Context with Composer .env

For Composer-based projects, define the context in an environment file if your setup loads environment variables early enough.

TYPO3_CONTEXT=Development

Use this only when the environment file is loaded before TYPO3 starts.

Set TYPO3 Context in CLI / shell

CLI commands may need a separate context.

export TYPO3_CONTEXT=Development

Or pass it directly before a command:

TYPO3_CONTEXT=Production/Staging vendor/bin/typo3 cache:flush

Last-resort options for shared hosting

Use these only when server-level access is not available.

• .user.ini
• php.ini
• php.ini
• Hosting panel environment variables

Avoid setting context too late, especially inside TYPO3 runtime files.

How to Check the Current TYPO3 Context

After setting TYPO3_CONTEXT, verify that TYPO3 reads the expected value.

• Check it in TYPO3 backend.
• Check it from CLI.
• Check it in PHP when debugging configuration.

Check it in TYPO3 backend System Information

TYPO3 shows the current Application Context in the backend System Information area.

Use this to confirm whether web requests run in Production, Development, or a sub-context.

Check it from CLI

Use the shell to confirm the variable.

env | grep TYPO3_CONTEXT

For DDEV, run:

ddev exec env | grep TYPO3_CONTEXT

Check it in PHP with Environment::getContext()

Use TYPO3’s PHP API to read the active context.

$context = \TYPO3\CMS\Core\Core\Environment::getContext();

Why CLI context and web context can be different

Web requests and CLI commands can use different environment variables.

• Web context usually comes from Apache, Nginx, DDEV, or hosting settings.
• CLI context usually comes from the shell, deployment script, or command prefix.
• Always verify both when debugging deployment issues.

How to Use TYPO3 Context in Real Projects

Once TYPO3_CONTEXT is set, use it to load environment-specific configuration.

• Change site URLs by context.
• Load separate database or mail settings.
• Control PHP, TypoScript, cache, errors, and logging.

Use TYPO3 Context in Site Configuration config.yaml

Use Site Configuration when each environment has a different base URL.

Path:

config/sites/<site>/config.yaml

Use baseVariants for local, staging, and production URLs

Use baseVariants to switch URLs by Application Context.

base: 'https://www.example.com/'
baseVariants:
-
  base: 'https://dev.example.com/'
  condition: 'applicationContext == "Development/DDEV"'
-
  base: 'https://staging.example.com/'
  condition: ‘applicationContext == "Production/Staging"’

Use TYPO3 Context in config/system/additional.php

Use config/system/additional.php for context-based system settings.

• Enable development-only settings.
• Keep production settings secure.
• Load environment-specific database, mail, cache, or logging configuration.

TYPO3 documentation confirms the current Application Context can be accessed in config/system/additional.php.

Use separate database credentials per environment

Use different database settings for local, staging, and production.

<?php

$context = (string)\TYPO3\CMS\Core\Core\Environment::getContext();

if ($context === 'Development/DDEV') {
  $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default'] = array_replace(
      $GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default'] ?? [],
      [
          'dbname' => 'db',
          'host' => 'db',
          'user' => 'db',
          'password' => 'db',
          'port' => 3306,
      ]
  );
}

if ($context === 'Production') {
  $GLOBALS['TYPO3_CONF_VARS']['SYS']['displayErrors'] = 0;
}

Use TYPO3 Context in custom PHP / extensions

Use Environment::getContext() when custom logic depends on the environment.

$context = \TYPO3\CMS\Core\Core\Environment::getContext();

if ($context->isDevelopment()) {
  // Development-only logic
}

Use TYPO3 Context in TypoScript conditions

Use applicationContext in TypoScript conditions.

[applicationContext == "Production"]
config.compressJs = 1
[end]

Use TYPO3 Context for cache, compression, error handling, and logging

Use context-specific settings to keep development flexible and production safe.

• Enable debugging in development.
• Disable visible errors in production.
• Adjust cache, compression, logging, and mail settings by environment.

Recommended Context Naming Strategy

se clear context names that show the environment and purpose.

• Start with a valid root context.
• Add sub-contexts only when useful.
• Use one naming pattern across the team.

Good context names

Use names like:

• Development/Local
• Development/DDEV
• Development/Debug
• Production/Staging
• Production/Live

Context names to avoid

Avoid names that do not start with a valid root context.

• Avoid Staging
• Avoid Live
• Avoid Preview
• Avoid using Testing for normal staging

Use Production/Staging instead of only Staging.

Suggested naming pattern for teams

Use one shared pattern in documentation and deployment scripts.

• Development/DDEV for local DDEV projects.
• Production/Staging for staging or preview.
• Production/Live for the live website.

Security and Deployment Best Practices

Use TYPO3 Context carefully in deployment workflows.

• Keep production settings protected.
• Keep local settings separate.
• Avoid exposing secrets in project files.

Never commit production credentials

Do not store live credentials in version-controlled files.

• Keep production database passwords outside Git.
• Do not commit production .env files.
• Use separate credentials for local, staging, and live environments.

Keep production errors disabled

Production should not show detailed errors to users.

• Enable detailed errors only in development.
• Disable visible error output on live websites.
• Keep debug tools away from production.

Use environment variables for secrets where possible

Use environment variables for sensitive values.

• Database passwords
• SMTP credentials
• API tokens
• External service keys

Use TYPO3_CONTEXT to decide which configuration should load, not to store the secret itself.

Keep DDEV/local configuration out of production deployments

DDEV settings should stay local unless intentionally shared for development.

• Do not deploy local Docker settings to production.
• Keep local database and mail settings separate.
• Review deployment scripts before pushing to live.

Troubleshooting TYPO3 Context

If TYPO3 Context does not work, first check where the value is set.

• Web and CLI context can be different.
• TYPO3 falls back to Production if no context is found.
• Invalid context names can break context checks.

TYPO3 still shows Production

TYPO3 usually shows Production when no valid context is detected.

• Check Apache, Nginx, DDEV, or hosting settings.
• Confirm TYPO3_CONTEXT is available before TYPO3 starts.
• Check whether REDIRECT_TYPO3_CONTEXT or HTTP_TYPO3_CONTEXT is overriding behavior.
• Clear TYPO3 and server/PHP cache after changes.

.htaccess context does not work

.htaccess settings may fail if Apache overrides are disabled.

• Check whether .htaccess is enabled.
• Use Apache vHost config if possible.
• Confirm SetEnv, SetEnvIf, or mod_rewrite rules are applied.

DDEV context is not changing

DDEV usually needs a restart after context changes.

• Check .ddev/config.yaml.
• Confirm web_environment contains TYPO3_CONTEXT=Development/DDEV.
• Run ddev restart.
• Verify with ddev exec env | grep TYPO3_CONTEXT.

CLI commands use the wrong context

CLI commands may not use the same context as web requests.

TYPO3_CONTEXT=Development/DDEV vendor/bin/typo3 cache:flush

Set the context in your shell or deployment script when needed.

isDevelopment() or isProduction() returns unexpected results

This usually happens when the root context is wrong.

• Use Development/Local, not Local.
• Use Production/Staging, not Staging.
• Keep the first part as Production, Development, or Testing.

Backend and frontend show different context

Backend and frontend may run through different server or PHP settings.

• Check vHost settings.
• Check PHP-FPM pool settings.
• Check whether only one entry point has a fallback context.
• Compare backend display, CLI output, and server environment values.

Optional TYPO3 Context Extensions and Tools

TYPO3 Context can usually be handled with server, CLI, and project configuration.
 Extensions are optional and should only be used when they simplify complex setups.

When an extension-based config loader makes sense

A config loader may help when one TYPO3 project has many environment-specific files.

• Use it for complex multi-environment projects.
• Use it when teams need cleaner configuration separation.
• Avoid it if the default TYPO3_CONTEXT setup already works.

What to verify before using a context extension

Do not add a context extension without checking maintenance and compatibility.

• Check TYPO3 version support.
• Check recent updates.
• Read the documentation.
• Test it in local or staging before production.

Conclusion

TYPO3 Context keeps local, staging, and production settings separate. It helps TYPO3 load the right configuration for each environment.

Set TYPO3_CONTEXT first, then verify it in backend, CLI, or PHP. After that, apply context-based settings for site URLs, database, TypoScript, and deployment.