Expose Environment Configuration by roxblnfk · Pull Request #661 · temporalio/sdk-php

roxblnfk · 2025-10-28T18:18:34Z

What was changed

See the documentation below

Checklist

Closes [Feature Request] Environment Configuration #628
How was this tested: added unit tests

Documentation: External Client Configuration Support

Common docs: https://docs.temporal.io/develop/environment-configuration

The PHP SDK now implements the Temporal external client configuration specification, enabling standardized configuration management across development, staging, and production environments.

This feature allows you to:

Store client configuration in TOML files with multiple named profiles (note: requires internal/toml package)
Override settings via environment variables
Switch between environments without code changes
Share configuration files across your team

Configuration File

Create a temporal.toml file in your platform-specific configuration directory:

Linux/Unix: ~/.config/temporalio/temporal.toml (or $XDG_CONFIG_HOME/temporalio/temporal.toml)
macOS: ~/Library/Application Support/temporalio/temporal.toml
Windows: %APPDATA%\temporalio\temporal.toml

[profile.development]
address = "localhost:7233"
namespace = "default"

[profile.production]
address = "my-namespace.a1b2c.tmprl.cloud:7233"
namespace = "my-namespace.a1b2c"
api_key = "your-api-key-here"

[profile.production.tls]
client_cert_path = "/path/to/client.pem"
client_key_path = "/path/to/client.pem"

[profile.production.grpc_meta]
custom-header = "custom-value"

Loading Configuration

The configuration system supports multiple loading strategies:

use Temporal\Common\EnvConfig\ConfigClient;

// Load a single profile from default location with environment overrides
$profile = ConfigClient::load(
    profileName: 'production',  // or use TEMPORAL_PROFILE env var
);

// Convert to ServiceClient and ClientOptions
$serviceClient = $profile->toServiceClient();
$clientOptions = $profile->toClientOptions();

// Create Temporal clients
use Temporal\Client\WorkflowClient;
use Temporal\Client\ScheduleClient;

$workflowClient = WorkflowClient::create($serviceClient, $clientOptions);
$scheduleClient = ScheduleClient::create($serviceClient, $clientOptions);

Environment Variables

All configuration keys can be overridden via environment variables using the TEMPORAL_* prefix:

# Connection settings
export TEMPORAL_ADDRESS="localhost:7233"
export TEMPORAL_NAMESPACE="my-namespace"
export TEMPORAL_API_KEY="my-secret-key"

# Profile selection
export TEMPORAL_PROFILE="production"

# Config file override
export TEMPORAL_CONFIG_FILE="/custom/path/to/config.toml"

# TLS configuration
export TEMPORAL_TLS="true"
export TEMPORAL_TLS_CLIENT_CERT_PATH="/path/to/cert.pem"
export TEMPORAL_TLS_CLIENT_KEY_PATH="/path/to/key.pem"
export TEMPORAL_TLS_SERVER_CA_CERT_PATH="/path/to/ca.pem"
export TEMPORAL_TLS_SERVER_NAME="custom-server"

# gRPC metadata headers
export TEMPORAL_GRPC_META_X_CUSTOM_HEADER="custom-value"
export TEMPORAL_GRPC_META_AUTHORIZATION="Bearer token"

Environment variables take precedence over configuration file values, enabling easy overrides for CI/CD pipelines and containerized deployments.

Configuration Hierarchy

Configuration is loaded with the following precedence (later values override earlier ones):

Profile from TOML file (if file exists at default location or specified via TEMPORAL_CONFIG_FILE)
Environment variable overrides (any TEMPORAL_* variables)
SDK defaults (applied for unspecified values)

Default Profile Behavior

When loading a profile without explicitly specifying a name:

If no profile name is provided and TEMPORAL_PROFILE is not set, the SDK looks for a profile named "default"
If the "default" profile doesn't exist and was NOT explicitly requested, the SDK returns an empty profile (matches Rust SDK behavior)
If a profile is explicitly requested (via profileName parameter or TEMPORAL_PROFILE env var) but doesn't exist, a ProfileNotFoundException is thrown

// TOML file with only 'production' profile
[profile.production]
address = "prod.temporal.io:7233"

// Case 1: No explicit profile request - returns empty profile (no exception)
$profile = ConfigClient::load();  // Returns empty ConfigProfile

// Case 2: Explicit profile request - throws exception
$profile = ConfigClient::load(profileName: 'default');  // ❌ Throws ProfileNotFoundException

// Case 3: Profile requested via env var - throws exception
putenv('TEMPORAL_PROFILE=staging');
$profile = ConfigClient::load();  // ❌ Throws ProfileNotFoundException

Profile Management

Loading a Specific Profile

The load() method returns a single ConfigProfile instance:

// Load the 'production' profile
$profile = ConfigClient::load(profileName: 'production');

// Load using TEMPORAL_PROFILE environment variable (defaults to 'default')
$profile = ConfigClient::load();

// Load with custom TOML file
$profile = ConfigClient::load(
    profileName: 'staging',
    configFile: '/path/to/temporal.toml'
);

// Load with custom environment variables
$profile = ConfigClient::load(
    profileName: 'production',
    env: ['TEMPORAL_ADDRESS' => 'localhost:7233', ...]
);

Working with Multiple Profiles

To access multiple profiles from a TOML file, use loadFromToml():

// Load all profiles from TOML
$config = ConfigClient::loadFromToml('/path/to/temporal.toml');

// Check if profile exists
if ($config->hasProfile('staging')) {
    $profile = $config->getProfile('staging');
}

// Profile names are case-insensitive
$profile = $config->getProfile('Production');  // matches "production"

// Access all profiles
$profiles = $config->profiles;  // array<string, ConfigProfile>

// Convert back to TOML
$tomlString = $config->toToml();

Loading Strategies

1. Load a single profile (recommended for most use cases):

// Load with automatic profile selection (TEMPORAL_PROFILE env var or 'default')
$profile = ConfigClient::load();

// Load specific profile from TOML + env overrides
$profile = ConfigClient::load(profileName: 'production');

// Load from inline TOML string
$tomlContent = <<<TOML
[profile.dev]
address = "localhost:7233"
namespace = "default"
TOML;
$profile = ConfigClient::load(
    profileName: 'dev',
    configFile: $tomlContent
);

2. Load from environment variables only:

// Returns a ConfigProfile directly from TEMPORAL_* env vars
$profile = ConfigClient::loadFromEnv();

// With custom environment array
$profile = ConfigClient::loadFromEnv([
    'TEMPORAL_ADDRESS' => 'localhost:7233',
    'TEMPORAL_NAMESPACE' => 'my-namespace',
    'TEMPORAL_API_KEY' => 'my-key',
]);

3. Load all profiles from TOML (for multi-profile scenarios):

// Load all profiles from file
$config = ConfigClient::loadFromToml('/path/to/temporal.toml');

// Access individual profiles
$devProfile = $config->getProfile('dev');
$prodProfile = $config->getProfile('production');

// Convert back to TOML format
$tomlString = $config->toToml();
file_put_contents('output.toml', $tomlString);

Remote Codec Support

Note

Remote codec configuration is not supported in the PHP SDK, following the same approach as TypeScript, Python, and .NET SDKs.

If you attempt to configure a remote codec either in the TOML file or via environment variables, the SDK will throw a CodecNotSupportedException to prevent silent failures:

# ❌ This will throw an exception
[profile.production.codec]
endpoint = "https://codec.example.com"
auth = "Bearer token"

# ❌ These will also throw an exception
export TEMPORAL_CODEC_ENDPOINT="https://codec.example.com"
export TEMPORAL_CODEC_AUTH="Bearer token"

This explicit error ensures users are aware that codec functionality is not available, rather than silently ignoring the configuration and causing unexpected behavior.

Practical Usage Examples

Example 1: Quick Start - Load and Use a Profile

use Temporal\Client\WorkflowClient;
use Temporal\Client\ScheduleClient;
use Temporal\Common\EnvConfig\ConfigClient;

// Load configuration profile (uses TEMPORAL_PROFILE env var or 'default')
$profile = ConfigClient::load();

// Convert to client options and service client
$serviceClient = $profile->toServiceClient();
$clientOptions = $profile->toClientOptions();

// Create Temporal clients
$workflowClient = WorkflowClient::create($serviceClient, $clientOptions);
$scheduleClient = ScheduleClient::create($serviceClient, $clientOptions);

Example 2: Load Specific Profile from TOML

use Temporal\Common\EnvConfig\ConfigClient;

// Load specific profile with environment variable overrides
$profile = ConfigClient::load(
    profileName: 'my_profile',
    configFile: '/path/to/temporal.toml',  // or TOML string
    env: $_ENV  // optional, defaults to getenv()
);

Example 3: Load from Environment Variables Only

use Temporal\Common\EnvConfig\ConfigClient;

// Set environment variables
$env = [
    'TEMPORAL_ADDRESS' => 'localhost:7233',
    'TEMPORAL_NAMESPACE' => 'my-namespace',
    'TEMPORAL_API_KEY' => 'my-secret-key',
    'TEMPORAL_TLS' => 'true',
];

// Load profile directly from environment
$profile = ConfigClient::loadFromEnv($env);

Example 4: Working with Multiple Profiles (TOML Export/Import)

use Temporal\Common\EnvConfig\ConfigClient;

// Load all profiles from TOML file
$config = ConfigClient::loadFromToml('/path/to/temporal.toml');

// Access specific profiles
$devProfile = $config->getProfile('development');
$prodProfile = $config->getProfile('production');

// Convert configuration back to TOML format
$tomlString = $config->toToml();

// Save to file
file_put_contents('/path/to/output.toml', $tomlString);

Example 5: Inline TOML Configuration

use Temporal\Common\EnvConfig\ConfigClient;

// Define TOML configuration inline
$tomlData = <<<'TOML'
[profile.dev]
address = "localhost:7233"
namespace = "default"

[profile.prod]
address = "prod.temporal.io:7233"
namespace = "production"
api_key = "secret-key"
TOML;

// Load specific profile from inline TOML
$profile = ConfigClient::load(
    profileName: 'dev',
    configFile: $tomlData
);

vercel · 2025-10-28T18:18:39Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
php	Ready	Preview, Comment	Dec 26, 2025 6:09pm

THardy98

Hi @roxblnfk !

Thanks for opening the PR.

Took a quick look through and it looks like the public interface deviates pretty notably from other implementations, see Typescript.

We have typically offered an interface that allows you to:

load a client configuration (e.g. all profiles in a configuration) from TOML file and overridden by env vars if set
load a client configuration, but from provided TOML data and overridden by env vars if set
convert a client configuration back to its TOML representation (as bytes)
load a single profile
load a profile and convert it into a representation that can be immediately used by client/connection (for a quick shorthand way to load and configure your client)

I'm requesting changes such that we keep feature parity here and maintain the same interface in the PHP SDK.

I would also keep in mind the control flow, as it differs in the existing implementations as well (i.e. we only throw ProfileNotFound if a profile name was provided by the user, if not, we return an empty profile)

roxblnfk · 2025-11-19T10:38:41Z

@THardy98 hi. The specification didn't help me understand some mechanics. Could you clarify these questions:

Question 1:

What is the expected behavior if:

I override some profile settings via ENV variables
I set TEMPORAL_PROFILE="default"
When loading the configuration, I explicitly select a different profile via code

Will the ENV variable values override the options of the different profile, even though the profile is not the configured TEMPORAL_PROFILE?
In other words, is it correct to say that ENV variables override options for all profiles, not just the one specified in TEMPORAL_PROFILE?

Question 2:

If I load configuration from both ENV variables and a TOML config file, and then save the loaded
state back to TOML, will the TOML data contain the values that were overridden from ENV?

THardy98 · 2025-11-19T17:51:32Z

Yeah, good questions, I could've clarified this earlier.

Will the ENV variable values override the options of the different profile, even though the profile is not the configured TEMPORAL_PROFILE?

Yes, the order of precedence is:

provided in code
env var
config file

With profile name, if you specify it in code, we will use it. Other env vars should apply on that profile.
If you do not specify a profile name, we will fallback to the TEMPORAL_PROFILE env var.
If you do not specify TEMPORAL_PROFILE we will fallback to the default profile, "default"

This TS code snippet should be a good reference (that file generally should be a good reference).

In other words, is it correct to say that ENV variables override options for all profiles, not just the one specified in TEMPORAL_PROFILE?

Yes :)
Env vars will always be applied against the profile you are loading. If you do not want env vars to apply against your profile, you can always specify the overrideEnvVars option with an empty object.

If I load configuration from both ENV variables and a TOML config file, and then save the loaded
state back to TOML, will the TOML data contain the values that were overridden from ENV?

The TOML data will contain the values of whatever configuration you provide it.
If that is a configuration from a config file + env var overrides, then that will be what the TOML serializer sees.

roxblnfk · 2025-12-05T14:10:42Z

@THardy98 after some refactoring, it looks like this:

use Temporal\Client\ScheduleClient;
use Temporal\Client\WorkflowClient;
use Temporal\Common\EnvConfig\ConfigClient;

# load a client configuration (e.g. all profiles in a configuration) from TOML file and overridden by env vars if set
$profile = ConfigClient::load(env: $env);   // ConfigProfile


# load a client configuration, but from provided TOML data and overridden by env vars if set
$profile = ConfigClient::load(profileName: 'my_profile', configFile: $pathOrData);   // ConfigProfile


# convert a client configuration back to its TOML representation (as bytes)
$tomlConfig = ConfigClient::loadFromToml($pathOrData);   // ConfigClient
$tomlData = $tomlConfig->toToml();                       // string


# load a single profile
$profile = ConfigClient::load(profileName: 'my_profile');   // ConfigProfile


# load a profile and convert it into a representation that can be immediately used by client/connection
# (for a quick shorthand way to load and configure your client)
$profile = $profile = ConfigClient::load();    // ConfigProfile
$serviceClient = $profile->toServiceClient();  // ServiceClient
$clientOptions = $profile->toClientOptions();  // ClientOptions

$workflowClient = WorkflowClient::create($serviceClient, $clientOptions);  // WorkflowClient
$scheduleClient = ScheduleClient::create($serviceClient, $clientOptions);  // ScheduleClient

THardy98

Generally LGTM - left a note about TLS interaction with API key

src/Common/EnvConfig/Client/ConfigProfile.php

…onal keys

…nfigTls`

…n and array support

…exceptions

ConfigClient: rename `loadFromFile()` to `loadFromToml()`

…ariables

… Windows in default config path resolving

…od signatures

roxblnfk requested a review from wolfy-j as a code owner October 28, 2025 18:18

vercel bot deployed to Preview October 28, 2025 18:42 View deployment

vercel bot deployed to Preview October 28, 2025 18:43 View deployment

roxblnfk force-pushed the env-config branch from e06ddc4 to 2e20d1e Compare October 28, 2025 18:43

vercel bot deployed to Preview October 28, 2025 18:43 View deployment

roxblnfk requested a review from Sushisource October 28, 2025 18:43

vercel bot deployed to Preview October 28, 2025 18:53 View deployment

vercel bot deployed to Preview October 28, 2025 18:59 View deployment

roxblnfk force-pushed the env-config branch from ee517bf to 93d2bf4 Compare October 28, 2025 19:00

vercel bot deployed to Preview October 28, 2025 19:00 View deployment

roxblnfk mentioned this pull request Oct 29, 2025

Create a service connection depending on ENVs #422

Closed

3 tasks

wolfy-j approved these changes Oct 29, 2025

View reviewed changes

roxblnfk mentioned this pull request Nov 3, 2025

Refactor: rename CloneWith::with to CloneWith::cloneWith #664

Merged

vercel bot deployed to Preview November 3, 2025 15:38 View deployment

THardy98 requested changes Nov 14, 2025

View reviewed changes

vercel bot deployed to Preview November 17, 2025 17:13 View deployment

vercel bot deployed to Preview December 5, 2025 14:04 View deployment

vercel bot deployed to Preview December 5, 2025 14:46 View deployment

vercel bot deployed to Preview December 5, 2025 14:47 View deployment

roxblnfk requested a review from THardy98 December 5, 2025 14:47

THardy98 approved these changes Dec 6, 2025

View reviewed changes

src/Common/EnvConfig/Client/ConfigProfile.php Show resolved Hide resolved

vercel bot deployed to Preview December 8, 2025 09:36 View deployment

roxblnfk force-pushed the env-config branch from b5eb8c5 to c40c30f Compare December 26, 2025 18:01

vercel bot deployed to Preview December 26, 2025 18:02 View deployment

test(envconfig): Add TOML stubs

5f55527

roxblnfk and others added 24 commits December 26, 2025 22:07

chore(envconfig): Add package internal/toml

2949ca1

feat(envconfig): Add ConfigProfile class

621fee9

feat(envconfig): Add ConfigToml

f7cb880

feat(envconfig): Add ConfigTls

2cc8e8a

test(envconfig): Test and fix ConfigToml

77f3e6f

style(php-cs-fixer): fix coding standards

9597a5f

chore(envconfig): Update TOML configuration examples and clarify opti…

9b17fec

…onal keys

feat(envconfig): Add merging functionality to ConfigProfile and `Co…

4500a4e

…nfigTls`

feat(envconfig): Add ConfigEnv

8fcddd3

style(php-cs-fixer): fix coding standards

d30b74e

feat(envconfig): Add ConfigClient and EnvProvider

6d02a5c

feat(envconfig): Enhance gRPC metadata handling with key normalizatio…

7f9e054

…n and array support

feat(envconfig): Add default config file detection

80132a1

feat(envconfig): Add codec configuration support with validation and …

57b681b

…exceptions

chore: Fix psalm issues

3c8133c

feat: Add TomlParserNotFound exception

5fd88c8

refactor: ConfigToml: remove strict non-mode;

32b2d32

ConfigClient: rename `loadFromFile()` to `loadFromToml()`

refactor(ConfigToml): Add fromString() factory

3b91ad6

feat: Add method ConfigClient::toToml()

9929d34

refactor(ConfigEnv): replace EnvProvider with array for environment v…

35dd08c

…ariables

refactor(ConfigClient): prioritize APPDATA env on USERPROFILE for…

8fc07b8

… Windows in default config path resolving

refactor(ConfigClient): improve profile loading logic and update meth…

850c85d

…od signatures

chore: Fix psalm issues

250691f

fix: Create default TLS config is API key is exposed

7ee0064

roxblnfk force-pushed the env-config branch from c40c30f to 7ee0064 Compare December 26, 2025 18:08

vercel bot deployed to Preview December 26, 2025 18:09 View deployment

roxblnfk merged commit e1c66dc into master Dec 26, 2025
103 of 114 checks passed

roxblnfk deleted the env-config branch December 26, 2025 18:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Expose Environment Configuration#661

Expose Environment Configuration#661
roxblnfk merged 25 commits intomasterfrom
env-config

roxblnfk commented Oct 28, 2025 •

edited

Loading

Uh oh!

vercel bot commented Oct 28, 2025 •

edited

Loading

Uh oh!

THardy98 left a comment •

edited

Loading

Uh oh!

roxblnfk commented Nov 19, 2025

Uh oh!

THardy98 commented Nov 19, 2025 •

edited

Loading

Uh oh!

roxblnfk commented Dec 5, 2025

Uh oh!

THardy98 left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

Conversation

roxblnfk commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What was changed

Checklist

Documentation: External Client Configuration Support

Configuration File

Loading Configuration

Environment Variables

Configuration Hierarchy

Default Profile Behavior

Profile Management

Loading a Specific Profile

Working with Multiple Profiles

Loading Strategies

Remote Codec Support

Practical Usage Examples

Example 1: Quick Start - Load and Use a Profile

Example 2: Load Specific Profile from TOML

Example 3: Load from Environment Variables Only

Example 4: Working with Multiple Profiles (TOML Export/Import)

Example 5: Inline TOML Configuration

Uh oh!

vercel bot commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

THardy98 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

roxblnfk commented Nov 19, 2025

Uh oh!

THardy98 commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

roxblnfk commented Dec 5, 2025

Uh oh!

THardy98 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

roxblnfk commented Oct 28, 2025 •

edited

Loading

vercel bot commented Oct 28, 2025 •

edited

Loading

THardy98 left a comment •

edited

Loading

THardy98 commented Nov 19, 2025 •

edited

Loading