Conditional Config Values with @dj_if

You have one app.ini file. It runs your dev machine, your staging server, and your production site.

But sometimes you need a value to change depending on where the code is running. Disable theme loading in dev. Turn on debug in staging. Use a different URL locally.

You could maintain separate config files per environment. Or you could use @dj_if and keep everything in one place.

---

How It Works

The @dj_if directive lets you set a value conditionally. It gets evaluated when the INI file is parsed. No runtime overhead after that.

The env. namespace checks environment variables. Three formats:

@dj_if env.VAR:result
@dj_if env.VAR=value:result
@dj_if env.VAR!=value:result

The first checks if VAR is enabled (1, true, yes, on). The second checks if VAR matches a specific value. The third checks if VAR does NOT match. In all cases, if the condition doesn't match, the key becomes an empty string.

Here's a real example. You want to disable theme loading when APP_ENV is set to dev:

[theme]
theme_id = djebel
load_theme = @dj_if env.APP_ENV=dev:0

On your dev machine where APP_ENV=dev, load_theme becomes 0. On production where APP_ENV=live, load_theme becomes an empty string and the theme loads normally.

Spaces around operators and separators are allowed. These are all equivalent:

load_theme = @dj_if env.APP_ENV=dev:0
load_theme = @dj_if env.APP_ENV = dev : 0
load_theme = @dj_if env.APP_ENV != dev : 1

Write it however feels readable. The parser trims spaces automatically. It also normalizes == to = and !== to != in case you accidentally use the PHP-style operators.

---

Boolean Check

The simplest form. Skip the = and just check if an env var is enabled:

@dj_if env.VAR:result

If the variable has an enabled value (1, true, yes, on), the condition matches. If it's disabled (0, false, no, off) or not set, the key becomes an empty string.

; Disable cache when DEV_ENV is enabled
djebel-static-content.cache = @dj_if env.DEV_ENV:0

; Turn on debug when DEBUG_MODE is enabled
debug = @dj_if env.DEBUG_MODE:1

This is the cleanest option when your env var is a simple on/off flag. Set DEV_ENV=1 on your dev machine and you're done.

---

Exact Matching

When you need to check for a specific value, use the = operator:

; Only disable theme when APP_ENV is exactly "dev"
load_theme = @dj_if env.APP_ENV=dev:0

; Enable debug when APP_ENV is exactly "staging"
debug = @dj_if env.APP_ENV=staging:1

This is strict. dev matches dev but not development.

---

Wildcard Matching

When exact matching is too strict, wildcards give you flexibility. Three flavors:

; Starts with: dev* matches "dev", "development", "dev-local"
load_theme = @dj_if env.APP_ENV=dev*:0

; Ends with: *ment matches "development", "deployment"
load_theme = @dj_if env.APP_ENV=*ment:0

; Contains: *stag* matches "staging", "pre-staging", "staging-v2"
load_theme = @dj_if env.APP_ENV=*stag*:0

Use the one that fits your naming convention. If your environments are dev, staging, and production, exact match is fine. If you have variants like dev-local and dev-docker, a starts-with wildcard handles all of them.

---

Multiple Values with Pipe

Sometimes you need to match more than one value. Use the pipe character for OR matching:

; Disable theme on dev OR staging
load_theme = @dj_if env.APP_ENV=dev|staging:0

; Enable debug on any non-production environment
debug = @dj_if env.APP_ENV=dev|staging|testing:1

You can combine pipes with wildcards too:

; Match "dev", "development", or anything starting with "stag"
load_theme = @dj_if env.APP_ENV=dev*|stag*:0

Spaces around the pipe are fine. dev | staging works the same as dev|staging.

---

Negative Matching

Use != to match when the value is NOT something. This is useful when you want a setting to apply everywhere except a specific environment:

; Enable debug on anything that's NOT production
debug = @dj_if env.APP_ENV!=production:1

; Enable caching only on production (disable when NOT production)
djebel-static-content.cache = @dj_if env.APP_ENV!=production:0

Wildcards and pipes work with != too:

; Disable cache on anything that's NOT prod*
djebel-static-content.cache = @dj_if env.APP_ENV!=prod*:0

; Enable debug when NOT on production or staging
debug = @dj_if env.APP_ENV!=production|staging:1

If the env var is not set at all, != considers it as not matching the expected value, so the result applies.

---

Setting Up Your Environment Variable

The @dj_if env. directive reads environment variables through Dj_App_Env::getEnv(), which checks both getenv() and $_SERVER. That means you can set the variable in several ways.

In your shell:

export APP_ENV=dev

In Apache's virtual host or .htaccess:

SetEnv APP_ENV dev

In Docker:

ENV APP_ENV=dev

In a .env file loaded by your deployment:

APP_ENV=dev

Pick whatever fits your setup. The directive will find it.

---

Practical Examples

Here are some patterns that work well in practice.

Disable theme loading in dev:

[theme]
theme_id = djebel
load_theme = @dj_if env.APP_ENV=dev:0

Turn on debug outside production:

[app]
debug = @dj_if env.APP_ENV=dev|staging:1

Disable caching in dev:

[plugins]
djebel-static-content.cache = @dj_if env.DEV_ENV:0

---

What Happens When There's No Match

If the condition doesn't match, the value becomes an empty string. This is important. An empty string is not the same as the key not existing.

For boolean-style settings like load_theme, an empty string means the default behavior kicks in. For settings where you need a specific fallback value, put the production value on its own line and the conditional override after it:

[app]
; Production default
env = live

; Override in dev (when APP_ENV=dev, this empty string won't override "env = live"
; because env is already set above)

For most use cases, the simple pattern of one conditional line per key is all you need.

---

Your Next Step

If you're maintaining separate config files per environment, try consolidating them into one app.ini with @dj_if directives. Start with the settings that actually differ between environments. Most config stays the same everywhere. Only the handful of values that change need the conditional treatment.

One file. Same codebase. Different behavior where it matters.