API Keys: Environment Variables & Constants

For enhanced security, PerfLocale resolves every machine-translation, GeoIP, and exchange-rate API key from three sources, in this priority order:

1. Environment variable (highest priority)
2. PHP constant in wp-config.php
3. Admin setting stored in the database (lowest priority)

This mirrors the source priority used by WordPress 7.0’s AI Connectors API, but PerfLocale implements it in plain PHP, so it works on every supported WordPress version (6.4+). When a higher-priority source has a non-empty value, the corresponding settings field is automatically disabled in the admin panel and shows where the value comes from.

Canonical names

Each credential has one canonical uppercase name. The same name is used as both the environment variable and the PHP constant — pick whichever fits your hosting setup.

Option 1: Environment variables (recommended for containers / CI)

Set the credential in your container orchestration, systemd unit, or shell profile. PerfLocale reads it via PHP’s getenv(); whitespace is trimmed automatically.

# docker-compose.yml
services:
  wordpress:
    environment:
      PERFLOCALE_DEEPL_API_KEY: "your-deepl-api-key-here"
      PERFLOCALE_GOOGLE_API_KEY: "your-google-api-key-here"
      PERFLOCALE_OXR_API_KEY: "your-openexchangerates-key-here"

# .env (read by your PHP-FPM pool, Docker, etc.)
PERFLOCALE_DEEPL_API_KEY=your-deepl-api-key-here
PERFLOCALE_GOOGLE_API_KEY=your-google-api-key-here

This option keeps secrets out of every PHP file and every database row. It’s the safest choice on managed-host environments (WP Engine, Kinsta, Pressable, Cloudways) that expose env-var configuration through their control panel.

Option 2: PHP constants in wp-config.php

If your hosting doesn’t support env vars, define the credential as a PHP constant in wp-config.php (before the /* That’s all, stop editing! */ line):

// Machine translation
define( 'PERFLOCALE_DEEPL_API_KEY', 'your-deepl-api-key-here' );
define( 'PERFLOCALE_GOOGLE_API_KEY', 'your-google-api-key-here' );
define( 'PERFLOCALE_MICROSOFT_API_KEY', 'your-microsoft-api-key-here' );
define( 'PERFLOCALE_LIBRE_API_KEY', 'your-libre-api-key-here' );
define( 'PERFLOCALE_LIBRE_URL', 'https://libretranslate.example.com' );
define( 'PERFLOCALE_AGENCY_URL', 'https://agency.example.com/translate' );
define( 'PERFLOCALE_AGENCY_API_KEY', 'your-agency-api-key-here' );

// GeoIP providers
define( 'PERFLOCALE_IPINFO_TOKEN', 'your-ipinfo-token-here' );
define( 'PERFLOCALE_IPINFO_LITE_TOKEN', 'your-ipinfo-lite-token-here' );
define( 'PERFLOCALE_IPSTACK_KEY', 'your-ipstack-key-here' );
define( 'PERFLOCALE_IP_API_KEY', 'your-ip-api-pro-key-here' );

// Exchange-rate providers
define( 'PERFLOCALE_OXR_API_KEY', 'your-openexchangerates-key-here' );
define( 'PERFLOCALE_CURRENCYFREAKS_KEY', 'your-currencyfreaks-key-here' );
define( 'PERFLOCALE_FIXER_KEY', 'your-fixer-key-here' );

Option 3: Admin settings (database)

If neither an env var nor a constant is set, PerfLocale reads the value from the database — the standard admin form at Settings → Addons → Machine Translation (and the matching tabs for GeoIP under Advanced and Exchange Rates under Addons → WooCommerce). Useful for low-risk single-site setups where a UI flow is more convenient than touching wp-config.php.

How it works

1. On every settings read, PerfLocale checks getenv() first, then defined(), then the database. The first non-empty source wins.
2. When a higher-priority source has a value, the corresponding admin field is disabled and shows either “Defined in environment variable” or “Defined in wp-config.php” (matching the actual source).
3. Admin form submissions are silently ignored for any field with an active env / constant override — your edit appears to do nothing because the override would mask it on the next read anyway.
4. Constants and env values that are empty (or only whitespace) are treated as “not set,” so an unintentional define( '…', '' ) doesn’t blank out a real DB value.
5. Removing both override sources falls back to whatever’s stored in the database.
6. Override values are never written to the database or included in PerfLocale’s data exports.

Benefits

• Security — secrets stay out of the database, immune to SQL injection or accidentally-shared DB dumps.
• Per-environment — same plugin install, different keys on staging vs production via env or per-environment wp-config.php includes.
• Version control — wp-config.php can be committed safely (without the define() calls) and env vars stay in your secrets manager.
• Backup safety — database backups and PerfLocale exports never contain API keys.