Configuration

Thelia 3 uses Symfony's configuration system with environment variables and YAML files.

Environment variables

.env files

Thelia uses the standard Symfony .env file hierarchy:

File	Purpose	Committed
.env	Default values	Yes
.env.local	Local overrides	No
.env.test	Test defaults	Yes
.env.test.local	Test local overrides	No

Key variables

The .env file ships with these defaults:

# Application
APP_ENV=dev
APP_SECRET=your-secret-key

# Mailer
MAILER_DSN=null://null

# CORS
CORS_ALLOW_ORIGIN='^https?://(localhost|127\.0\.0\.1)(:[0-9]+)?$'

# JWT (generated by lexik:jwt:generate-keypair)
JWT_SECRET_KEY=%kernel.project_dir%/config/jwt/private.pem
JWT_PUBLIC_KEY=%kernel.project_dir%/config/jwt/public.pem
JWT_PASSPHRASE=your-passphrase

# Lock
LOCK_DSN=flock

Database configuration

Database credentials are set as individual environment variables (not a DATABASE_URL string):

DATABASE_HOST=localhost
DATABASE_PORT=3306
DATABASE_NAME=thelia
DATABASE_USER=thelia
DATABASE_PASSWORD=your_password

These are written to .env.local by bin/install during setup. With DDEV, they are injected automatically.

Symfony configuration

config/packages/

config/packages/
├── api_platform.yaml
├── cache.yaml
├── csrf.yaml
├── debug.yaml
├── framework.yaml
├── lexik_jwt_authentication.yaml
├── liip_imagine.yaml
├── lock.yaml
├── mailer.yaml
├── monolog.yaml
├── nelmio_cors.yaml
├── property_info.yaml
├── routing.yaml
├── security.yaml
├── symfonycasts_sass.yaml
├── translation.yaml
├── twig.yaml
├── twig_component.yaml
├── validator.yaml
└── web_profiler.yaml

No Doctrine

Thelia uses Propel ORM, not Doctrine. There is no doctrine.yaml.

API Platform

config/packages/api_platform.yaml:

api_platform:
    title: Hello API Platform
    version: 1.0.0
    formats:
        jsonld: ['application/ld+json']
    docs_formats:
        jsonld: ['application/ld+json']
        jsonopenapi: ['application/vnd.openapi+json']
        html: ['text/html']
    defaults:
        stateless: true
        cache_headers:
            vary: ['Content-Type', 'Authorization', 'Origin']
        extra_properties:
            standard_put: true
            rfc_7807_compliant_errors: true

Framework

config/packages/framework.yaml:

framework:
    secret: '%env(APP_SECRET)%'
    annotations: false
    http_method_override: false
    handle_all_throwables: true
    session:
        handler_id: null
        cookie_secure: auto
        cookie_samesite: lax
    php_errors:
        log: true

Security

config/packages/security.yaml ships with a minimal configuration:

security:
    password_hashers:
        Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface: 'auto'
    providers:
        users_in_memory: { memory: null }
    firewalls:
        dev:
            pattern: ^/(_(profiler|wdt)|css|images|js)/
            security: false
        main:
            lazy: true
            provider: users_in_memory

The Thelia core handles authentication for both admins and customers, not Symfony's standard security providers.

Thelia configuration

Store settings

Access in back-office: Configuration > Store

• Store name, company information, contact details
• Default currency and language

Theme configuration

php Thelia template:set frontOffice flexy
php Thelia template:set backOffice default-twig

Overriding a stored variable from the environment

Every variable of the config table can be overridden by an environment variable, which is handy for values that differ between your machines and your servers without touching the database.

The name is derived from the variable name: uppercase, with . and - replaced by _. So store_name is overridden by STORE_NAME, and rewriting_enable by REWRITING_ENABLE.

# .env.local
STORE_NAME="My shop, staging"
REWRITING_ENABLE=0

The override happens when the value is read (Config::getValue()), so it applies to ConfigQuery::read() and to everything built on it, including the {config} Smarty function and the config loop. The database row is left untouched: remove the environment variable and the stored value applies again.

One thing to know: the resolved values are kept in the shared configuration cache, so changing an environment variable is not enough on its own.

php Thelia cache:clear

Caching

Clear cache

# Development
php Thelia cache:clear

# Production
php Thelia cache:clear --env=prod

# DDEV
ddev exec php Thelia cache:clear

cache:clear empties the container cache, in var/cache/<env>: the compiled service container, the routes, the translations, the compiled templates.

What the shop computed and reads back later, so catalog payloads, API refresh tokens and rate limit counters, is the application cache. It is held in separate pools that survive cache:clear, and THELIA_CACHE_DSN moves those pools to a shared server such as Redis. php Thelia thelia:cache:clear, and the button under Configuration > Advanced configuration, also empty the catalog pool; php Thelia cache:pool:clear <pool> empties one pool and nothing else. See Application cache.

Debug mode

# Development (default)
APP_ENV=dev
# APP_DEBUG is derived from APP_ENV

# Production
APP_ENV=prod

warning

Never set APP_ENV=dev in production. It exposes sensitive information via the debug toolbar and profiler.

Mail configuration

Configure in .env.local:

# SMTP
MAILER_DSN=smtp://user:password@smtp.example.com:587

# Disable emails (default)
MAILER_DSN=null://null

Next steps

• First Steps: create your first content
• Architecture: understand the system
• Module Development: extend Thelia