API Keys: Environment Variables & Constants

For enhanced security, PerfLocale resolves every machine-translation credential 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)

The resolution is plain PHP (getenv() then defined()), so it works on every supported WordPress version (6.4+). If WordPress ever ships its AI Connectors API, PerfLocale will also consult it for the four MT-provider keys — after env and constants, before the database — and the admin field then reads “Provided by the WordPress Connectors API.” When any 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

There are seven credentials, each with one canonical uppercase name. The same name is used as both the environment variable and the PHP constant — pick whichever fits your hosting setup. These are the only PerfLocale settings that can be overridden this way; nothing else the plugin stores has a constant.

GeoIP redirect and WooCommerce exchange-rate syncing ship with no provider, so they have no credential of their own. A provider you register through perflocale/geo/providers or perflocale/woocommerce/exchange_rate_providers stores its key in the ordinary admin field named by its key_setting; to keep that key out of the database, read it from your own constant or environment variable inside the provider’s fetch_callback.

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"

# .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' );

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 PerfLocale → Settings → Addons → Machine Translation (the subtab appears once Machine Translation is enabled on the PerfLocale → Addons screen). 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, shows the value masked, and names the actual source — “Defined in the PERFLOCALE_… environment variable” or “Defined in wp-config.php as PERFLOCALE_…”.
3. A field with an active override is rendered disabled, so the form submits no value for it and the admin screen can’t be used to change that credential — reads return the override regardless.
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.