README

Zero-config environment type detection

Answers one question, with no configuration: what kind of environment is this code running in? It detects a single environment type - local, ci, development, preview, stage, or production - from the hosting platform or CI platform the code runs on, and also recognises the local stack (native host or container) beneath it.

• Zero configuration: a single call detects and caches the type.
• Recognises hosting platforms (Acquia, Lagoon, Pantheon, Platform.sh, Skpr, Tugboat) and CI platforms (GitHub Actions, GitLab CI, CircleCI).
• Recognises the stack it runs on (native host, Container, DDEV, Lando).
• Turnkey Drupal integration: one line in settings.php detects the environment and owns all its settings.
• Extensible with custom platforms, stacks, and contexts, with a safe fallback type.

Installation

composer require drevops/environment-detector

Usage

The detector works in any PHP application, and ships a turnkey integration for Drupal.

Drupal

A single line in settings.php detects the environment and applies every setting the detector owns - the resolved type, trusted hosts, reverse proxy, cache prefix, file paths, and more:

require DRUPAL_ROOT . '/../vendor/drevops/environment-detector/environment.drupal.php';

That is the complete, recommended integration - nothing else is needed in settings.php. With it in place the detector:

• resolves the environment type and writes it to $settings['environment'];
• adds the universal loopback trusted hosts (^localhost$, ^127\.0\.0\.1$);
• applies the active platform's Drupal settings (e.g. Lagoon reverse proxy and routes, Acquia config and temp paths);
• applies the active stack's Drupal settings (e.g. the container service-host allowlist and LOCALDEV_URL).

The file is required rather than autoloaded so it runs in the caller's scope: it hands the site's own $settings and $config to the detector by reference, and the detector writes the settings Drupal reads back. (A library writing the global $settings would update a different variable than the local one Drupal core consumes, so the settings would silently never land.) See Contexts to extend or override what is applied.

Any PHP application

Detect the environment type directly through the static facade:

use DrevOps\EnvironmentDetector\Environment;

if (Environment::isProd()) {
  // Apply production settings.
}

The first call auto-detects and caches the result. The full set is isLocal(), isCi(), isDev(), isPreview(), isStage(), isProd(), plus Environment::is('custom-type') for custom types.

The detected type is also written to the ENVIRONMENT_TYPE environment variable:

Environment::init();
if (getenv('ENVIRONMENT_TYPE') === Environment::PRODUCTION) {
  // ...
}

If ENVIRONMENT_TYPE is already set, that value wins - handy for forcing a type while debugging.

Environment types

The built-in detectors resolve to one of these types (a custom platform can return its own, read via Environment::is('custom-type')):

preview is the only ephemeral, per-change tier with its own URL - which is what sets it apart from development (shared and long-lived) and stage (a persistent pre-production mirror).

How it works

A run is a set of nested rings, from the outermost ring inward to the application:

┌─ PLATFORM ── hosting (tiered) · CI (flat) · none ⇒ local ───────────────┐
│   ┌─ STACK ── native · container · ddev · lando ────────────────────┐   │
│   │   ┌─ RUNTIME ── PHP 8.x ────────────────────────────────────┐   │   │
│   │   │   ┌─ APP / CONTEXT ── Drupal ───────────────────────┐   │   │   │
│   │   │   └─────────────────────────────────────────────────┘   │   │   │
│   │   └─────────────────────────────────────────────────────────┘   │   │
│   └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘

• Platform - the outermost ring, and the only one that decides the type. A hosting platform maps to production/stage/development/preview; a CI platform maps to ci; with no platform at all the type is local (or ci when a generic CI signal is present).
• Stack - the substrate the run sits in (native, container, ddev, lando). A stack nests inside a platform, never decides the type, and can only update the context. ddev and lando are specific containers, container is the generic container fallback, and native is the native host (bare metal), the fallback when nothing else matches.
• Context - the application/framework (e.g. Drupal, WordPress, Laravel) that detected settings are applied to.
• Runtime (PHP) is shown only to complete the picture; it is not detected.

Two rules follow:

1. At most one platform is active. Two active platforms (say Acquia and Lagoon) is a genuine misconfiguration and throws.
2. Exactly one stack is always active - the most specific stack that matches, or the native host as the fallback. A container inside Acquia or inside CI is just an inner ring; it never collides with the platform. The most specific match wins - DDEV over the generic container, say - and the native host is the last-resort fallback when nothing else matches.

When a context is active, it applies its own generic changes first, then the active platform and the active stack apply their own on top. This happens even when the type was pre-set via ENVIRONMENT_TYPE.

Configuration

init() is optional - the is*() methods initialise on first use. Call it directly only to register custom detectors or change the fallback:

Environment::init(
  contextualize: TRUE,                 // Apply context settings automatically (default).
  fallback: Environment::DEVELOPMENT,  // Type used when a platform cannot resolve its tier.
  platforms: [new MyHostingPlatform()],
  stacks: [new MyStack()],
  contexts: [new MyContext()],
);

The fallback (development by default) applies only when a platform is active but cannot resolve its tier - it is never used to silently downgrade a known environment. It guards against applying local settings in production, or production settings locally.

Platforms

A platform is the outermost ring and the only one that decides the type. Built-ins:

• Acquia
• CircleCI
• GitHub Actions
• GitLab CI
• Lagoon
• Pantheon
• Platform.sh
• Skpr
• Tugboat

How platforms map to types

Each hosting platform maps its own signal to a type. preview is the catch-all: any environment a platform spins up that it cannot place in one of the three persistent tiers (production, stage, development) is treated as an ephemeral, per-branch or per-PR build.

The name-based platforms (Acquia, Pantheon, Skpr) read an environment name - recognised names map to a persistent tier, and any other name is a preview. The branch-based platforms (Lagoon, Platform.sh) type an environment as production or non-production, then resolve the exact tier from the deployed Git branch: the develop branch is development, and any other non-production, non-stage branch is a preview.

On Lagoon, main/master resolve to stage unless one of them is named by ENVIRONMENT_PRODUCTION_BRANCH, in which case it is production. The branch names (main, master, release/*, hotfix/*, develop) are built-in conventions.

Every built-in platform resolves to one of these tiers whenever it is active - an active environment it cannot place in a persistent tier (an unrecognised name or env-type) is a preview. The development fallback applies only to custom platforms that return no type. The CI platforms - CircleCI, GitHub Actions, GitLab CI - always resolve to ci.

Read the active platform:

Environment::init();

if (Environment::getActivePlatform()?->id() === 'acquia') {
  // Acquia-specific logic.
}

Add your own by extending AbstractPlatform. Implement a context's capability interface (DrupalContextualizerInterface for Drupal) to apply settings through a typed method the detector resolves for you; override contextualize() to handle a context defined at runtime instead:

use DrevOps\EnvironmentDetector\Contexts\Drupal;
use DrevOps\EnvironmentDetector\Contexts\DrupalContextualizerInterface;
use DrevOps\EnvironmentDetector\Environment;
use DrevOps\EnvironmentDetector\Platforms\AbstractPlatform;

class CustomHosting extends AbstractPlatform implements DrupalContextualizerInterface {
  public const ID = 'customhosting';

  public function active(): bool {
    return isset($_SERVER['CUSTOM_ENV']);
  }

  public function type(): ?string {
    return match ($_SERVER['CUSTOM_ENV_TYPE'] ?? null) {
      'dev' => Environment::DEVELOPMENT,
      'qa' => 'qa',
      'live' => Environment::PRODUCTION,
      default => null,
    };
  }

  // Resolved automatically for the Drupal context. To handle a context defined
  // at runtime, override contextualize(ContextInterface $context) instead.
  public function contextualizeDrupal(Drupal $context): void {
    $context->settings['some_setting'] = 'value';
  }
}

Environment::init(platforms: [new CustomHosting()]);

Stacks

A stack is the substrate the run sits in. Stacks never decide the type. Exactly one stack is always active - the most specific stack that matches, or the native host as the last-resort fallback. Container is the generic container fallback, matched by probing for containerisation; Ddev and Lando are specific containers, matched by the marker their tool sets (IS_DDEV_PROJECT, LANDO_INFO); and Native is the native host, used when nothing else matches. Built-ins:

• Container
• DDEV
• Lando
• Native

Read the active stack:

Environment::init();

if (Environment::getActiveStack()?->id() === 'ddev') {
  // DDEV-specific logic.
}

getActiveStack() returns the first registered stack whose active() matches - your custom stacks included - with the native host as the last-resort fallback.

Add your own by extending AbstractStack. As with platforms, implement a context's capability interface for the typed path, or override contextualize() for a runtime context:

use DrevOps\EnvironmentDetector\Contexts\Drupal;
use DrevOps\EnvironmentDetector\Contexts\DrupalContextualizerInterface;
use DrevOps\EnvironmentDetector\Stacks\AbstractStack;

class CustomStack extends AbstractStack implements DrupalContextualizerInterface {
  public const ID = 'customstack';

  public function active(): bool {
    return getenv('CUSTOM_STACK') !== false;
  }

  // Resolved automatically for the Drupal context. To handle a context defined
  // at runtime, override contextualize(ContextInterface $context) instead.
  public function contextualizeDrupal(Drupal $context): void {
    $context->settings['some_setting'] = 'value';
  }
}

Environment::init(stacks: [new CustomStack()]);

Contexts

A context is the framework or application that detected settings are applied to. Once a context is active it applies its own generic changes first, then the active platform and the active stack layer their changes on top of the same target (the Lagoon platform, say, adds its reverse-proxy and trusted-host settings).

A platform or stack applies settings to a context in one of two ways. For a context the library ships, it implements that context's capability interface - DrupalContextualizerInterface for Drupal - and the detector resolves the typed contextualizeDrupal() method automatically. For a context defined at runtime, it overrides contextualize(ContextInterface $context) and handles the context itself. The built-in platforms and stacks use the typed path.

The built-in Drupal context is the turnkey example: it holds the site's $settings and $config by reference and is wired up by the one-line Drupal integration shown above.

Note

Drupal is the only built-in context today, but the ring model is framework-agnostic. We are looking to add more framework integrations - contributions that add contexts for other frameworks (WordPress, Laravel, Symfony, and more) are welcome. Open an issue or a pull request.

Custom contexts

Add your own by implementing ContextInterface. Bind the framework's own state by reference in the constructor, then write to it in contextualize() - the same by-reference approach the built-in Drupal context uses:

use DrevOps\EnvironmentDetector\Contexts\ContextInterface;

class CustomContext implements ContextInterface {
  // Hold the framework's own config by reference so the changes land in the
  // array the framework reads back, not a separate copy.
  public array $config;

  public function __construct(array &$config = []) {
    $this->config = &$config;
  }

  public function id(): string {
    return 'myframework';
  }

  public function active(): bool {
    return class_exists('MyFramework');
  }

  public function contextualize(): void {
    $this->config['custom_value'] = $_SERVER['custom_value'] ?? 'default';
  }
}

// $config is the framework's own configuration array, in scope here.
Environment::init(contexts: [new CustomContext($config)]);

Environment variables

Beyond the platform and stack detection signals the hosting or CI provider sets (listed in the Platforms table), the detector reads a few variables that you set - to override detection or to shape the settings a context applies. All are optional.

The DRUPAL_* variables take effect only when the Drupal context is active.

Maintenance

composer install
composer lint
composer test

This repository was created using the Scaffold project template.