[#2153] Delegated environment detection and provider settings to 'drevops/environment-detector'.

.ahoy.yml

@@ -121,7 +121,7 @@ commands:
 
   drush:
     usage: Run Drush commands in the CLI service container.
-    cmd: ahoy cli "vendor/bin/drush -l \${VORTEX_LOCALDEV_URL} $*"
+    cmd: ahoy cli "vendor/bin/drush -l \${LOCALDEV_URL} $*"
 
   #;< SERVICE_CACHE
   flush-redis:

.env

@@ -162,13 +162,7 @@ VORTEX_PROVISION_USE_MAINTENANCE_MODE=1
 LAGOON_PROJECT=your_site
 
 # Dedicated branch to identify the production environment.
-VORTEX_LAGOON_PRODUCTION_BRANCH=main
-
-# amazee.io region for the Lagoon internal-route trusted host pattern.
-#
-# Set to your amazee.io region code (for example, "au" or "us"), or leave it
-# empty if the project does not run on amazee.io.
-VORTEX_LAGOON_AMAZEEIO_REGION=au
+ENVIRONMENT_PRODUCTION_BRANCH=main
 #;> HOSTING_LAGOON
 
 #;< HOSTING_ACQUIA

.env.local.example

@@ -10,7 +10,7 @@
 
 # Local development URL.
 # Override only if you need to use a different URL than the default.
-# VORTEX_LOCALDEV_URL="<current_dir>.docker.amazee.io"
+# LOCALDEV_URL="<current_dir>.docker.amazee.io"
 
 # Print debug information in Vortex scripts.
 # VORTEX_DEBUG=1

.lagoon.yml

@@ -41,7 +41,7 @@ tasks:
     - run:
         name: Backup DB before deployment in production
         command: |
-          if [ "$LAGOON_ENVIRONMENT_TYPE" = "production" ] || [ "$LAGOON_GIT_BRANCH" = "${VORTEX_LAGOON_PRODUCTION_BRANCH:-main}" ]; then
+          if [ "$LAGOON_ENVIRONMENT_TYPE" = "production" ] || [ "$LAGOON_GIT_BRANCH" = "${ENVIRONMENT_PRODUCTION_BRANCH:-main}" ]; then
             echo "==> Running in PRODUCTION environment."
             VORTEX_DB_DIR=/app/web/sites/default/files/private/pre_deployment_backups ./vendor/drevops/vortex-tooling/src/export-db-file
           fi
@@ -51,7 +51,7 @@ tasks:
     - run:
         name: Download database in non-production environments
         command: |
-          if [ "$LAGOON_ENVIRONMENT_TYPE" != "production" ] && [ "$LAGOON_GIT_BRANCH" != "${VORTEX_LAGOON_PRODUCTION_BRANCH:-main}" ]; then
+          if [ "$LAGOON_ENVIRONMENT_TYPE" != "production" ] && [ "$LAGOON_GIT_BRANCH" != "${ENVIRONMENT_PRODUCTION_BRANCH:-main}" ]; then
             # No need to load SSH file to access production DB as Lagoon has SSH agent keys.
             export VORTEX_FETCH_DB_SSH_FILE=false
             export VORTEX_DB_DIR=/tmp/data
@@ -82,7 +82,7 @@ tasks:
           fi
           #;> PROVISION_TYPE_PROFILE
 
-          if [ "$LAGOON_ENVIRONMENT_TYPE" = "production" ] || [ "$LAGOON_GIT_BRANCH" = "${VORTEX_LAGOON_PRODUCTION_BRANCH:-main}" ]; then
+          if [ "$LAGOON_ENVIRONMENT_TYPE" = "production" ] || [ "$LAGOON_GIT_BRANCH" = "${ENVIRONMENT_PRODUCTION_BRANCH:-main}" ]; then
             echo "==> Running in PRODUCTION environment."
             #;< !PROVISION_TYPE_PROFILE
             # Never overwrite existing DB when production site already exists.

.vortex/docs/.utils/variables/extra/.env.local.example.variables.sh

@@ -10,7 +10,7 @@
 # Docker Compose to the name of the project directory.
 #
 # Override only if you need to use a different URL than the default.
-VORTEX_LOCALDEV_URL="${COMPOSE_PROJECT_NAME:-example-site}.docker.amazee.io"
+LOCALDEV_URL="${COMPOSE_PROJECT_NAME:-example-site}.docker.amazee.io"
 
 # Set to `1` to print debug information in Vortex scripts.
 VORTEX_DEBUG=

.vortex/docs/.utils/variables/extra/environment.variables.sh

@@ -11,10 +11,11 @@
 # Defaults to the name of the project directory.
 COMPOSE_PROJECT_NAME=
 
-# Override detected Drupal environment type.
+# Override the detected environment type.
 #
-# Used in the application to override the automatically detected environment type.
-DRUPAL_ENVIRONMENT=
+# Set before detection to force a specific environment type. Read by the
+# environment detector.
+ENVIRONMENT_TYPE=
 
 # Drupal hash salt.
 #

.vortex/docs/content/architecture.mdx

@@ -111,8 +111,9 @@ and [Drupal > Theme Scaffold](./drupal/theme-scaffold)
 **Vortex** includes a structured way to manage Drupal settings per environment.
 Here's how it works:
 
-- The environment type (e.g. local, CI, stage) is automatically detected based
-  on the environment provider settings located in `web/sites/default/includes/providers/`.
+- The environment type (e.g. local, CI, stage, preview) is automatically
+  detected by the [`drevops/environment-detector`](https://github.com/drevops/environment-detector)
+  package, which also applies the hosting platform's environment-specific settings.
 - Settings overrides are stored in `web/sites/default/includes/modules/` with logic per
   environment inside each module-specific file.
 

.vortex/docs/content/drupal/settings.mdx

@@ -186,63 +186,76 @@ for platform-specific guidance.
 
 ### Environment type detection
 
-**Vortex** defines an _environment type_ to represent the context in which the
-Drupal site is running — such as local, CI, development, staging, or production.
-This concept allows the system to conditionally adjust settings and behaviors
-depending on the runtime environment.
-
-The _environment type_ is detected automatically based on known _hosting provider_
-indicators or predefined environment variables. Detection logic is intentionally
-isolated from configuration logic — it identifies the context but does not apply
-any overrides directly.
-
-Once detected, the environment type value is stored in the `$settings['environment']`
-, which can be used by modules, settings overrides, and shell scripts to
-drive environment-specific behavior.
+**Vortex** uses an _environment type_ to represent the context in which the
+Drupal site is running. Detection is delegated to the
+[`drevops/environment-detector`](https://github.com/drevops/environment-detector)
+package, which identifies the active _hosting platform_ (such as Acquia or
+Lagoon) or _CI service_, resolves the environment type, and applies that
+platform's environment-specific Drupal settings.
+
+The detector recognizes six environment types:
+
+| Type | What it is | Lifespan |
+|------|------------|----------|
+| `local` | Your own machine or a local container stack; no hosting platform is active. | Persistent |
+| `ci` | An automated CI runner (GitHub Actions, CircleCI). | Ephemeral, per job |
+| `development` | A shared, long-lived hosting environment for ongoing integration work. Also the safe fallback. | Persistent |
+| `preview` | A short-lived, throwaway per-branch or per-PR environment with its own URL. | Ephemeral |
+| `stage` | A persistent pre-production environment that mirrors production; used for UAT and release sign-off. | Persistent |
+| `production` | The live environment serving real users. | Persistent |
+
+The detected type is stored in `$settings['environment']`, which modules,
+settings overrides, and shell scripts use to drive environment-specific
+behavior. **Vortex** treats `preview` the same as `development` in its module
+settings.
 
 #### Environment type constants
 
-**Vortex** defines the following constants to represent supported environments:
+The detector exposes the supported environment types as constants on the
+`DrevOps\EnvironmentDetector\Environment` class:
 
-- `ENVIRONMENT_LOCAL`
-- `ENVIRONMENT_CI`
-- `ENVIRONMENT_DEV`
-- `ENVIRONMENT_STAGE`
-- `ENVIRONMENT_PROD`
+- `Environment::LOCAL` (`local`)
+- `Environment::CI` (`ci`)
+- `Environment::DEVELOPMENT` (`development`)
+- `Environment::PREVIEW` (`preview`)
+- `Environment::STAGE` (`stage`)
+- `Environment::PRODUCTION` (`production`)
 
-These constants are used consistently throughout settings files and scripts to
-determine conditional behavior.
+Use these constants in module settings files instead of hardcoding the string
+values.
 
 #### Detection mechanism
 
-The detection process uses indicators provided by known cloud hosting platforms. Logic
-for supported providers is stored in the `includes/providers` directory.
-
-To add support for a custom platform, simply create a `settings.[provider].php`
-file in that directory with the relevant detection logic.
+The detector resolves the environment type from the active platform and applies
+that platform's Drupal settings (reverse proxy, trusted hosts, file paths, and
+similar):
 
-- If a provider is detected, the default environment type is set to `ENVIRONMENT_DEV`.
-- Additional provider-specific conditions can elevate this to `ENVIRONMENT_STAGE` or `ENVIRONMENT_PROD`.
-- If no provider is detected, the environment type defaults to `ENVIRONMENT_LOCAL`.
+- If a hosting platform or CI service is detected, it determines the environment
+  type.
+- If the active platform cannot determine a specific type, the type falls back
+  to `Environment::DEVELOPMENT` — the safest default, so a misconfigured
+  environment never receives local settings in production or production settings
+  locally.
+- If no platform is detected, the type is `Environment::CI` when a generic CI
+  signal is present, otherwise `Environment::LOCAL`.
 
-It is important to note that this detection logic is only responsible for
-identifying the environment type. It does not apply any configuration changes.
-Those are handled separately in per-module override files located in
-`includes/providers`, making the setup modular and independent of the cloud
-hosting platforms.
+The detector owns all environment-specific settings. **Vortex** only bridges a
+few of its own variables (such as the Lagoon production branch and the local
+development URL) to the variable names the detector reads.
 
 #### Overriding environment type
 
 You can override the detected environment type by setting the
-`DRUPAL_ENVIRONMENT` environment variable.
+`ENVIRONMENT_TYPE` environment variable. When it is set before detection, the
+detector uses its value verbatim.
 
 This is useful when:
 
 - Testing environment-specific behavior locally.
 - Working around gaps in the detection logic.
 - Forcing a known environment type for debugging.
 
-For example, add `DRUPAL_ENVIRONMENT=ci` to your `.env.local` file to simulate
+For example, add `ENVIRONMENT_TYPE=ci` to your `.env.local` file to simulate
 the CI environment locally.
 
 ### Per-module overrides
@@ -265,7 +278,7 @@ web/sites/default/includes/modules/settings.[module_name].php
 
 Each settings file should:
 
-- Use environment type constants (`ENVIRONMENT_LOCAL`, `ENVIRONMENT_PROD`, etc.) for conditional logic
+- Use the environment detector's constants (`Environment::LOCAL`, `Environment::PRODUCTION`, etc.) for conditional logic
 - Leverage environment variables for configuration values
 - Provide sensible defaults when environment variables are not set
 - Be self-contained and removable without affecting other modules

.vortex/docs/content/drupal/update-hooks.mdx

@@ -35,7 +35,7 @@ function ys_base_deploy_create_about_page(): string {
   $environment = \Drupal\Core\Site\Settings::get('environment');
 
   // Conditional execution based on environment.
-  if ($environment === ENVIRONMENT_PROD) {
+  if ($environment === \DrevOps\EnvironmentDetector\Environment::PRODUCTION) {
     return 'Skipped in production environment';
   }
 

.vortex/docs/content/hosting/acquia.mdx

@@ -42,10 +42,11 @@ operations.
 
 ### Environment detection
 
-Vortex automatically detects when running on Acquia and loads appropriate
-settings from [`web/sites/default/includes/providers/settings.acquia.php`](https://github.com/drevops/vortex/blob/main/web/sites/default/includes/providers/settings.acquia.php).
-This includes Acquia-specific configurations for caching, file paths, and
-environment variables.
+Vortex automatically detects when running on Acquia and applies the
+Acquia-specific Drupal settings through the
+[`drevops/environment-detector`](https://github.com/drevops/environment-detector)
+package. This includes Acquia-specific configurations for caching, file paths,
+and environment variables.
 
 #### Acquia settings file
 

.vortex/docs/content/hosting/lagoon.mdx

@@ -40,10 +40,11 @@ environment-specific configurations.
 
 ### Environment detection
 
-Vortex automatically detects when running on Lagoon and loads appropriate
-settings from [`web/sites/default/includes/providers/settings.lagoon.php`](https://github.com/drevops/vortex/blob/main/web/sites/default/includes/providers/settings.lagoon.php).
-This includes Lagoon-specific configurations for caching, file paths, and
-environment variables provided by the platform.
+Vortex automatically detects when running on Lagoon and applies the
+Lagoon-specific Drupal settings through the
+[`drevops/environment-detector`](https://github.com/drevops/environment-detector)
+package. This includes Lagoon-specific configurations for caching, file paths,
+and environment variables provided by the platform.
 
 ## Onboarding
 

.vortex/docs/content/tools/docker.mdx

@@ -168,7 +168,7 @@ Consider the example:
 ```shell
 TZ: ${TZ:-UTC}
 # Local development URL.
-VORTEX_LOCALDEV_URL: &default-url ${COMPOSE_PROJECT_NAME:-example-site}.docker.amazee.io
+LOCALDEV_URL: &default-url ${COMPOSE_PROJECT_NAME:-example-site}.docker.amazee.io
 # Local development route used in Lagoon images and Pygmy to route requests.
 LAGOON_ROUTE: *default-url
 ```
@@ -178,10 +178,10 @@ where
 - `TZ: ${TZ:-UTC}` - defines a variable `TZ` with a
   default value of `UTC`, but only if `TZ` variable is
   not defined.
-- `VORTEX_LOCALDEV_URL: &default-url ${COMPOSE_PROJECT_NAME:-example-site}.docker.amazee.io` - defines
-   a variable `VORTEX_LOCALDEV_URL` with a default value of
+- `LOCALDEV_URL: &default-url ${COMPOSE_PROJECT_NAME:-example-site}.docker.amazee.io` - defines
+   a variable `LOCALDEV_URL` with a default value of
   `${COMPOSE_PROJECT_NAME:-example-site}.docker.amazee.io`, but only if
-  `VORTEX_LOCALDEV_URL` variable is not defined. The value of the variable
+  `LOCALDEV_URL` variable is not defined. The value of the variable
   is also stored in a YAML anchor `default-url` for later use.
 - `LAGOON_ROUTE: *default-url` - defines a variable `LAGOON_ROUTE` with a value
   of `*default-url`, which is a reference to the `default-url` YAML anchor

.vortex/docs/content/tools/phpunit.mdx

@@ -127,7 +127,7 @@ The `w3c: true` option is required for compatibility with Selenium 4.
 The custom [`tests/phpunit/bootstrap.php`](https://github.com/drevops/vortex/blob/main/tests/phpunit/bootstrap.php)
 file runs before tests to:
 
-1. Set `BROWSERTEST_OUTPUT_BASE_URL` from the `VORTEX_LOCALDEV_URL` environment
+1. Set `BROWSERTEST_OUTPUT_BASE_URL` from the `LOCALDEV_URL` environment
    variable so that HTML output links are accessible from the host machine.
 2. Create the `web/sites/simpletest/browser_output` directory required by the
    `HtmlOutputLogger` extension before it initializes

.vortex/installer/src/Command/BuildCommand.php

@@ -139,7 +139,7 @@ protected function getProjectMachineName(): string {
    * Get the local development URL from Docker Compose configuration.
    *
    * Runs `docker compose config --format json` to get the resolved
-   * VORTEX_LOCALDEV_URL, which correctly accounts for COMPOSE_PROJECT_NAME.
+   * LOCALDEV_URL, which correctly accounts for COMPOSE_PROJECT_NAME.
    *
    * @return string|null
    *   The local development URL, or NULL if it cannot be determined.
@@ -158,9 +158,9 @@ protected function getLocalDevUrl(): ?string {
       $config = json_decode($output, TRUE);
 
       if (is_array($config)) {
-        // Extract URL from any service that has VORTEX_LOCALDEV_URL.
-        $url = $config['services']['cli']['environment']['VORTEX_LOCALDEV_URL']
-          ?? $config['services']['webserver']['environment']['VORTEX_LOCALDEV_URL']
+        // Extract URL from any service that has LOCALDEV_URL.
+        $url = $config['services']['cli']['environment']['LOCALDEV_URL']
+          ?? $config['services']['webserver']['environment']['LOCALDEV_URL']
           ?? NULL;
 
         if ($url !== NULL) {

.vortex/installer/src/Prompts/Handlers/CiProvider.php

@@ -97,14 +97,12 @@ public function process(): void {
 
     if ($remove_gha) {
       File::remove($t . '/.github/workflows/build-test-deploy.yml');
-      File::remove($t . '/' . $this->webroot . '/sites/default/includes/providers/settings.gha.php');
       File::removeTokenAsync('CI_PROVIDER_GHA');
       File::removeTokenAsync('SETTINGS_PROVIDER_GHA');
     }
 
     if ($remove_circleci) {
       File::remove($t . '/.circleci');
-      File::remove($t . '/' . $this->webroot . '/sites/default/includes/providers/settings.circleci.php');
       File::remove($t . '/tests/phpunit/CircleCiConfigTest.php');
       File::removeTokenAsync('CI_PROVIDER_CIRCLECI');
       File::removeTokenAsync('SETTINGS_PROVIDER_CIRCLECI');

.vortex/installer/src/Prompts/Handlers/HostingProjectName.php

@@ -77,19 +77,6 @@ public function discover(): null|string|bool|array {
       return $v;
     }
 
-    // @deprecated Discovery from hardcoded path in settings.acquia.php. The
-    // new settings.acquia.php uses AH_SITE_GROUP environment variable instead
-    // of a hardcoded project name. Kept for backward compatibility with older
-    // installations.
-    $acquia_settings_file = $this->dstDir . sprintf('/%s/sites/default/includes/providers/settings.acquia.php', $this->webroot);
-    if (file_exists($acquia_settings_file)) {
-      $content = file_get_contents($acquia_settings_file);
-      // Require '/var/www/site-php/your_site/your_site-settings.inc';.
-      if ($content !== FALSE && preg_match('/require\s+[\'"]\/var\/www\/site-php\/([a-z0-9_]+)\/[a-z0-9_]+-settings\.inc[\'"]\s*;/', $content, $matches) && !empty($matches[1])) {
-        return $matches[1];
-      }
-    }
-
     // Try Lagoon.
     $v = Env::getFromDotenv('LAGOON_PROJECT', $this->dstDir);
     if (!empty($v)) {
@@ -132,14 +119,8 @@ public function process(): void {
 
     $v = $this->getResponseAsString();
     $t = $this->tmpDir;
-    $w = $this->webroot;
 
     Env::writeValueDotenv('VORTEX_ACQUIA_APP_NAME', $v, $t . '/.env');
-    // @deprecated The settings.acquia.php no longer uses hardcoded project
-    // names - it uses AH_SITE_GROUP environment variable instead. This
-    // replacement is kept for backward compatibility with older installations
-    // that may still use the hardcoded path pattern.
-    File::replaceContentInFile($t . '/' . $w . '/sites/default/includes/providers/settings.acquia.php', 'your_site', $v);
 
     Env::writeValueDotenv('LAGOON_PROJECT', $v, $t . '/.env');
     File::replaceContentInFile($t . '/drush/sites/lagoon.site.yml', 'your_site-${env-name}', $v . '-${env-name}');

.vortex/installer/src/Prompts/Handlers/HostingProvider.php

@@ -111,7 +111,6 @@ public function process(): void {
 
   protected function removeAcquia(): void {
     File::remove($this->tmpDir . '/hooks');
-    File::remove(sprintf('%s/%s/sites/default/includes/providers/settings.acquia.php', $this->tmpDir, $this->webroot));
 
     File::removeTokenAsync('HOSTING_ACQUIA');
     File::removeTokenAsync('SETTINGS_PROVIDER_ACQUIA');
@@ -121,7 +120,6 @@ protected function removeLagoon(): void {
     File::remove($this->tmpDir . '/drush/sites/lagoon.site.yml');
     File::remove($this->tmpDir . '/.lagoon.yml');
     File::remove($this->tmpDir . '/.github/workflows/close-pull-request.yml');
-    File::remove(sprintf('%s/%s/sites/default/includes/providers/settings.lagoon.php', $this->tmpDir, $this->webroot));
 
     File::removeTokenAsync('HOSTING_LAGOON');
     File::removeTokenAsync('SETTINGS_PROVIDER_LAGOON');

.vortex/installer/tests/Fixtures/handler_process/_baseline/.ahoy.yml

@@ -101,7 +101,7 @@ commands:
 
   drush:
     usage: Run Drush commands in the CLI service container.
-    cmd: ahoy cli "vendor/bin/drush -l \${VORTEX_LOCALDEV_URL} $*"
+    cmd: ahoy cli "vendor/bin/drush -l \${LOCALDEV_URL} $*"
 
   flush-redis:
     usage: Flush Redis cache.

.vortex/installer/tests/Fixtures/handler_process/_baseline/.env.local.example

@@ -10,7 +10,7 @@
 
 # Local development URL.
 # Override only if you need to use a different URL than the default.
-# VORTEX_LOCALDEV_URL="<current_dir>.docker.amazee.io"
+# LOCALDEV_URL="<current_dir>.docker.amazee.io"
 
 # Print debug information in Vortex scripts.
 # VORTEX_DEBUG=1