sa-orchestration/includes/class-sa-env.php

<?php
defined( 'ABSPATH' ) || exit;

/**
 * Environment classification helper.
 *
 * Implements the SA-Orch Environment Configuration Classification rule:
 *
 *   production secrets        — human-authorized only (no scaffolding)
 *   development placeholders  — Asterion may scaffold (non-secret)
 *   local test routing        — Asterion may scaffold (non-secret)
 *   deploy-time constants     — Asterion may scaffold (non-secret)
 *
 * The line: production credentials are never auto-written. Dev/local
 * placeholders MAY be scaffolded when the environment is *explicitly*
 * marked local or development AND the value is clearly non-production.
 *
 * Source of truth for "is this local/dev":
 *   1. WP_ENVIRONMENT_TYPE constant (WordPress canonical)
 *   2. WP_ENVIRONMENT_TYPE environment variable (WordPress canonical)
 *   3. Default: 'production' (safe by default)
 *
 * Filterable via 'sa_orch_env_type' for testing only — never used to
 * change production behavior in real deployments.
 */
class SA_Orch_Env {

    /**
     * Return the current environment type. One of:
     *   'local' | 'development' | 'staging' | 'production'
     * Defaults to 'production' when unable to determine — production-safe.
     */
    public static function type(): string {
        if ( ! function_exists( 'wp_get_environment_type' ) ) {
            $base = 'production';
        } else {
            $base = (string) wp_get_environment_type();
        }
        // Filter for testing scenarios; production code paths never set this.
        return (string) apply_filters( 'sa_orch_env_type', $base );
    }

    /** True iff env is explicitly local OR development. */
    public static function is_local_or_dev(): bool {
        $t = self::type();
        return $t === 'local' || $t === 'development';
    }

    /** True iff env is production (the default; assume-prod-when-unsure). */
    public static function is_production(): bool {
        return self::type() === 'production';
    }
}