Updated variables description in .env file.

.env

@@ -27,7 +27,7 @@
 # the project directory and can be overridden with $COMPOSE_PROJECT_NAME.
 VORTEX_PROJECT=your_site
 
-# Name of the webroot directory with Drupal codebase.
+# Name of the web root directory containing a Drupal codebase.
 VORTEX_WEBROOT=web
 
 # The timezone for the containers.
@@ -43,11 +43,13 @@ DRUPAL_PROFILE=standard
 # Drupal theme name.
 DRUPAL_THEME=your_site_theme
 
-# Stage file proxy origin. Note that HTTP Auth provided by Shield will be
-# automatically added to the origin URL.
+# Stage file proxy origin.
+#
+# If using Shield, the HTTP authentication credentials will be automatically
+# added to the origin URL.
 DRUPAL_STAGE_FILE_PROXY_ORIGIN=https://www.your-site-url.example/
 
-# Shield print message.
+# Shield message.
 DRUPAL_SHIELD_PRINT="Restricted access."
 
 #;< REDIS
@@ -71,13 +73,16 @@ DRUPAL_CLAMAV_MODE=daemon
 #                                 PROVISION                                    #
 ################################################################################
 
-# Variables in this section control how the site is provisioned.
+# By "provision", we mean the process of initialising the database (from dump
+# or fresh install from profile), running updates, appying configuration
+# changes, clearing caches and performing other tasks that prepare the site for
+# use.
 # @see https://vortex.drevops.com/workflows/provision
 
 # Set to 1 to install a site from profile instead of the database file dump.
 VORTEX_PROVISION_USE_PROFILE=0
 
-# Overwrite existing database if it exists.
+# Overwrite a database if it exists.
 #
 # Usually set to 0 in deployed environments and can be temporary set to 1 for
 # a specific deployment.
@@ -90,23 +95,42 @@ VORTEX_PROVISION_OVERRIDE_DB=0
 # environments and is always skipped in the production environment.
 VORTEX_PROVISION_SANITIZE_DB_SKIP=0
 
-# Sanitization email pattern. Sanitization is enabled by default in all
-# non-production environments.
+# Sanitization email pattern.
+#
+# Applied if database sanitization is enabled.
 # @see https://vortex.drevops.com/workflows/build#sanitization
 VORTEX_PROVISION_SANITIZE_DB_EMAIL="user_%[email protected]"
 
 # Put the site into a maintenance mode during site provisioning.
 VORTEX_PROVISION_USE_MAINTENANCE_MODE=1
 
+################################################################################
+#                                HOSTING                                       #
+################################################################################
+
+#;< LAGOON
+# Lagoon project name. May be different from $VORTEX_PROJECT.
+LAGOON_PROJECT=your_site
+
+# Dedicated branch to identify the production environment.
+VORTEX_LAGOON_PRODUCTION_BRANCH=main
+#;> LAGOON
+
+#;< ACQUIA
+# Acquia application name.
+VORTEX_ACQUIA_APP_NAME=
+#;> ACQUIA
+
 ################################################################################
 #                                DATABASE                                      #
 ################################################################################
 
 # Database service runs a single database within a container.
-# See settings.php for database credentials defaults.
+# See settings.php for database credentials defaults or run
+# `ahoy drush sql:connect`.
 
-# Database can be imported from a file dump into an empty database started from
-# the database default image or can exist in a pre-built container image.
+# Database can be imported from a *file dump* into an empty database started
+# from the database default image or can *exist* in a pre-built container image.
 # Defaults to importing from a file.
 # @see https://vortex.drevops.com/workflows/database
 
@@ -124,26 +148,28 @@ VORTEX_DB_FILE=db.sql
 #;< !PROVISION_USE_PROFILE
 # Database can be sourced from one of the following locations:
 #
-# - `curl` - directly from URL as a file using CURL.
-# - `ftp` - directly from FTP as a file using CURL.
+# - `curl` - directly from a URL as a file using CURL.
+# - `ftp` - directly from an FTP as a file using CURL.
 # - `acquia` - from the latest Acquia backup via Cloud API as a file.
 # - `lagoon` - from Lagoon main environment as a file.
 # - `container_registry` - from the container registry as a container image.
 # - `none` - not downloaded, site is freshly installed for every build.
-
+#
 # Note that "container_registry" works only for database-in-image
 # database storage (when $VORTEX_DB_IMAGE variable has a value).
 VORTEX_DB_DOWNLOAD_SOURCE=curl
 
 #;< VORTEX_DB_DOWNLOAD_SOURCE_CURL
-# Database dump file sourced from CURL, with optional HTTP Basic Authentication
-# credentials embedded into the value.
+# Database dump file sourced from CURL.
+#
+# HTTP Basic Authentication credentials should be embedded into the value.
 VORTEX_DB_DOWNLOAD_CURL_URL=
 #;> VORTEX_DB_DOWNLOAD_SOURCE_CURL
 
 # Environment to download the database from.
+#
+# Applies to Acquia and Lagoon environments.
 VORTEX_DB_DOWNLOAD_ENVIRONMENT=prod
-#;> !PROVISION_USE_PROFILE
 
 #;< FTP
 # Database dump file sourced from FTP.
@@ -159,17 +185,11 @@ VORTEX_DB_DOWNLOAD_FTP_FILE=db.sql
 #;> FTP
 
 #;< ACQUIA
-# Acquia application name to download the database from.
-VORTEX_ACQUIA_APP_NAME=
-
 # Acquia database name to download the database from.
 VORTEX_DB_DOWNLOAD_ACQUIA_DB_NAME=your_site
 #;> ACQUIA
 
-#;< LAGOON
-# Lagoon project name. May be different from $VORTEX_PROJECT.
-LAGOON_PROJECT=your_site
-#;> LAGOON
+#;> !PROVISION_USE_PROFILE
 
 #;< DEPLOYMENT
 ################################################################################
@@ -186,12 +206,6 @@ LAGOON_PROJECT=your_site
 #
 # See https://vortex.drevops.com/workflows/deploy
 VORTEX_DEPLOY_TYPES=artifact
-
-#;< LAGOON
-# Dedicated branch to identify the production environment.
-VORTEX_LAGOON_PRODUCTION_BRANCH=main
-#;> LAGOON
-
 #;> DEPLOYMENT
 
 #;< NOTIFICATIONS
@@ -222,16 +236,12 @@ VORTEX_NOTIFY_EMAIL_RECIPIENTS="[email protected]"
 ################################################################################
 #                                  DEMO                                        #
 ################################################################################
-
-#-------------------------------------------------------------------------------
-# Variables used to override project-specific values for demonstration purposes.
-#
-# This is to allow to demonstrate how Vortex works without asking users
-# to perform any additional steps when trying out Vortex for the first time.
-#
-# Remove this section from your project when database download integration setup
-# is finished.
-#-------------------------------------------------------------------------------
+#                                                                              #
+# Override project-specific values for demonstration purposes.                 #
+# Used to showcase Vortex without asking users to perform additional steps.    #
+# Remove this section after completing database download integration.          #
+#                                                                              #
+################################################################################
 
 #;< VORTEX_DB_DOWNLOAD_SOURCE_CURL
 # URL of the demo database used for demonstration with CURL database
@@ -240,7 +250,7 @@ VORTEX_DB_DOWNLOAD_CURL_URL=https://github.com/drevops/vortex/releases/download/
 #;> VORTEX_DB_DOWNLOAD_SOURCE_CURL
 
 #;< VORTEX_DB_IMAGE
-# The name of the demo database image used for demonstration only for
+# The name of the demo database image used for demonstration for
 # database-in-image data storage.
 #; The line below will be automatically uncommented for database-in-image
 #; storage. It is commented out to allow running non-database-in-image

.vortex/docs/content/workflows/variables.mdx

@@ -162,7 +162,7 @@ Defined in: `.env`
 
 ### `DRUPAL_SHIELD_PRINT`
 
-Shield print message.
+Shield message.
 
 Default value: `Restricted access.`
 
@@ -186,7 +186,9 @@ Defined in: `.env`, `scripts/vortex/provision.sh`
 
 ### `DRUPAL_STAGE_FILE_PROXY_ORIGIN`
 
-Stage file proxy origin. Note that HTTP Auth provided by Shield will be<br/>automatically added to the origin URL.
+Stage file proxy origin.
+
+If using Shield, the HTTP authentication credentials will be automatically<br/>added to the origin URL.
 
 Default value: `https://www.your-site-url.example/`
 
@@ -294,7 +296,7 @@ Defined in: `scripts/vortex/task-purge-cache-acquia.sh`
 
 ### `VORTEX_ACQUIA_APP_NAME`
 
-Acquia application name to download the database from.
+Acquia application name.
 
 Default value: `UNDEFINED`
 
@@ -488,7 +490,9 @@ Defined in: `.env`, `scripts/vortex/download-db-acquia.sh`
 
 ### `VORTEX_DB_DOWNLOAD_CURL_URL`
 
-Database dump file sourced from CURL, with optional HTTP Basic Authentication<br/>credentials embedded into the value.
+Database dump file sourced from CURL.
+
+HTTP Basic Authentication credentials should be embedded into the value.
 
 Default value: `UNDEFINED`
 
@@ -498,6 +502,8 @@ Defined in: `.env`, `scripts/vortex/download-db-curl.sh`
 
 Environment to download the database from.
 
+Applies to Acquia and Lagoon environments.
+
 Default value: `prod`
 
 Defined in: `.env`, `scripts/vortex/download-db-acquia.sh`, `scripts/vortex/download-db-lagoon.sh`
@@ -618,6 +624,15 @@ Defined in: `scripts/vortex/download-db-lagoon.sh`
 
 ### `VORTEX_DB_DOWNLOAD_SOURCE`
 
+Database can be sourced from one of the following locations:
+
+- `curl` - directly from a URL as a file using CURL.
+- `ftp` - directly from an FTP as a file using CURL.
+- `acquia` - from the latest Acquia backup via Cloud API as a file.
+- `lagoon` - from Lagoon main environment as a file.
+- `container_registry` - from the container registry as a container image.
+- `none` - not downloaded, site is freshly installed for every build.
+
 Note that "container_registry" works only for database-in-image<br/>database storage (when [`$VORTEX_DB_IMAGE`](#vortex_db_image) variable has a value).
 
 Default value: `curl`
@@ -1533,7 +1548,7 @@ Defined in: `scripts/vortex/provision.sh`
 
 ### `VORTEX_PROVISION_OVERRIDE_DB`
 
-Overwrite existing database if it exists.
+Overwrite a database if it exists.
 
 Usually set to `0` in deployed environments and can be temporary set to `1` for<br/>a specific deployment.<br/>Set this to `1` in .env.local to override when developing locally.
 
@@ -1561,7 +1576,9 @@ Defined in: `scripts/vortex/provision-sanitize-db.sh`
 
 ### `VORTEX_PROVISION_SANITIZE_DB_EMAIL`
 
-Sanitization email pattern. Sanitization is enabled by default in all<br/>non-production environments.<br/>@see https://vortex.drevops.com/workflows/build#sanitization
+Sanitization email pattern.
+
+Applied if database sanitization is enabled.<br/>@see https://vortex.drevops.com/workflows/build#sanitization
 
 Default value: `user_%[email protected]`
 
@@ -1862,7 +1879,7 @@ Defined in: `.env`
 
 ### `VORTEX_WEBROOT`
 
-Name of the webroot directory with Drupal codebase.
+Name of the web root directory containing a Drupal codebase.
 
 Default value: `web`
 

.vortex/installer/composer.json

@@ -27,7 +27,7 @@
         "drupal/coder": "^8.3",
         "ergebnis/composer-normalize": "^2.45",
         "mikey179/vfsstream": "^1.6",
-        "opis/closure": "^3.6",
+        "opis/closure": "^4",
         "phpstan/phpstan": "^1.10",
         "phpunit/phpunit": "^10",
         "rector/rector": "^1.0.0"

.vortex/installer/src/Command/InstallCommand.php

@@ -96,6 +96,13 @@ protected function configure(): void {
   protected function execute(InputInterface $input, OutputInterface $output): int {
     $this->output = $output;
 
+    // @see https://github.com/drevops/vortex/issues/1502
+    if ($input->getOption('help') || $input->getArgument('path') == 'help') {
+      $output->write($this->getHelp());
+
+      return Command::SUCCESS;
+    }
+
     try {
       $this->checkRequirements();