Environment Change Detection

Yoko Core automatically detects when the WordPress site URL (domain) has changed from its previously recorded value. This commonly happens when a site is cloned to a staging server, migrated to a new domain, or restored from a backup. When a domain change is detected, an admin notice is displayed and integrations are given the opportunity to protect against unintended cross-environment side effects.

How It Works

The feature is implemented in includes/Admin/DetectEnvChange.php. On every admin_init request the class compares the hostname extracted from WordPress's siteurl option against the hostname stored in the yoko_prev_domain database option.

State	Behavior
No previous domain recorded	Records the current domain and exits silently.
Previous domain matches current domain	No action taken.
Previous domain differs from current domain	Fires yoko_env_changed on every page load, and fires yoko_on_env_changed exactly once (the first time the discrepancy is noticed). Sets $yoko->state['env_changed'] = true.

The difference between the two actions is important:

• yoko_env_changed – fired on every admin page load while the change is unacknowledged. Use this to show warnings, disable dangerous settings, or add checklist items that should remain visible until the admin dismisses the notice.
• yoko_on_env_changed – fired only once, the first time the change is detected. Use this for one-time destructive or irreversible actions (e.g. deleting API credentials, purging a cache) that should not repeat on subsequent page loads.

Once a Yoko user has verified everything looks correct they can click Dismiss this Message in the admin notice. This triggers the yoko_dashboard_action_reset_env action which updates yoko_prev_domain to the current domain and sets $yoko->state['env_changed'] back to false.

Detecting Live vs. Non-live Environments

DetectEnvChange::domain_is_live( $domain ) returns false for domains that are clearly non-production:

• Domains ending in .local or .test
• Domains whose hostname begins with stg-

Integrations can call this helper to decide how aggressively to act. For example, the WP Activity Log integration resets its pruning settings only when the new domain is not live (i.e. the site was cloned down to staging).

The Admin Notice Checklist

When the environment change notice is rendered it includes an ordered checklist of items that individual integrations can append to via the yoko_env_changed_items_to_check filter. Each item should be a plain-text or minimally-linked string describing something the site administrator should verify or act upon.

add_filter(
    'yoko_env_changed_items_to_check',
    function ( array $items ): array {
        $items[] = sprintf(
            // translators: %s is a link to the relevant settings page.
            __( 'Review the %s settings for this environment.', 'yoko-core' ),
            '<a href="' . esc_url( admin_url( 'admin.php?page=my-plugin-settings' ) ) . '">'
                . __( 'My Plugin', 'yoko-core' )
            . '</a>'
        );
        return $items;
    }
);

Note: Always hook yoko_env_changed_items_to_check inside a callback attached to the yoko_env_changed action so the filter is registered only when the environment change is actually active. See existing integrations in includes/Integrations/ for examples.

Available Actions and Filters

Hook	Type	Arguments	When Fired
yoko_env_changed	action	$prev_domain, $current_domain	Every admin page load while the domain mismatch exists.
yoko_on_env_changed	action	$prev_domain, $current_domain	Once, the first time the domain mismatch is detected.
yoko_dashboard_action_reset_env	action	(none)	When the user dismisses the notice and resets the stored domain.
yoko_env_changed_items_to_check	filter	array $items	During yoko_env_changed, just before the notice is rendered.

Helper Methods

// Returns the hostname stored from the previous environment.
DetectEnvChange::get_prev_domain(): string

// Returns the hostname extracted from the current siteurl option.
DetectEnvChange::get_current_domain(): string

// Returns false for .local, .test, and stg-* domains.
DetectEnvChange::domain_is_live( $domain ): bool

Examples in This Plugin

WP Mail SMTP (includes/Integrations/WPMailSMTP.php)

On every page load while the domain mismatch exists, SMTP's Do Not Send option is enabled to prevent emails being sent from the wrong environment. A checklist item prompts the administrator to verify the setting.

WP Activity Log (includes/Integrations/WPActivityLog.php)

On the first detection of a domain change, if the new domain is non-live the Activity Log's retention period is shortened to one week to avoid bloating a staging database. A checklist item reminds the administrator to review these settings.

Search with Typesense (includes/Integrations/SearchWithTypesense.php)

On the first detection of a domain change, the Typesense server credentials are deleted to prevent search indexing from accidentally running against a production index from a cloned or staging environment. A checklist item instructs the administrator to reconnect Typesense on the new environment.

---

The environment change detection system was introduced across the 1.9.x release series. The yoko_on_env_changed one-time action was added in 1.9.6.