diff --git a/.vortex/docs/content/README.mdx b/.vortex/docs/content/README.mdx index 41db109c9..9b0dabf53 100644 --- a/.vortex/docs/content/README.mdx +++ b/.vortex/docs/content/README.mdx @@ -34,6 +34,7 @@ on [Lagoon container images](https://github.com/uselagoon/lagoon-images) - [Continuous integration](ci) configuration - [Hosting integration](hosting) - [Unified developer experience](workflows) +- Documentation to help you get started and maintain your project Refer to [Features](getting-started/features.mdx) for more details. diff --git a/.vortex/docs/content/drupal/composer.mdx b/.vortex/docs/content/drupal/composer.mdx index 977d00d8a..ea8db58ba 100644 --- a/.vortex/docs/content/drupal/composer.mdx +++ b/.vortex/docs/content/drupal/composer.mdx @@ -26,7 +26,7 @@ provides a starter kit for managing your site dependencies with Composer. **Vortex** extends the Drupal Composer project's `composer.json` to support additional features and tools. -**Vortex** team will keep the `composer.json` file up-to-date with the +**Vortex** team keeps the `composer.json` file up-to-date with the latest version of the `composer.json` in the [Drupal Composer project](https://github.com/drupal-composer/drupal-project), so you can always make sure you are using the best community practices. diff --git a/.vortex/docs/content/drupal/settings.mdx b/.vortex/docs/content/drupal/settings.mdx index 9e836866a..8073e5815 100644 --- a/.vortex/docs/content/drupal/settings.mdx +++ b/.vortex/docs/content/drupal/settings.mdx @@ -12,9 +12,10 @@ the [`settings.php`](https://github.com/drevops/vortex/blob/develop/web/sites/de [`services.yml`](https://github.com/drevops/vortex/blob/develop/web/sites/default/services.yml) files. It also provides [Settings unit tests](#testing-settings-with-unit-tests) to ensure that -the settings apply correctly per environment. These tests are supposed to be -maintained within your project, ensuring that settings activated by specific -environments and environment variables are applied accurately. +the settings apply correctly per environment. These tests are intended to be +maintained within your project, ensuring that the settings activated within a +specific _environment type_ and with specific _environment variables_ are +applied correctly. The default **Drupal Scaffold**'s [`default.settings.php`](https://github.com/drevops/vortex/blob/develop/web/sites/default/default.settings.php) and [`default.services.yml`](https://github.com/drevops/vortex/blob/develop/web/sites/default/default.services.yml) @@ -24,28 +25,28 @@ The [`settings.php`](https://github.com/drevops/vortex/blob/develop/web/sites/de into several sections: import CodeBlock from '@theme/CodeBlock'; -import MyComponentSource from '!!raw-loader!./../../../../web/sites/default/settings.php'; +import SettingsExample from '!!raw-loader!./../../../../web/sites/default/settings.php';
Click here to see the contents of the `settings.php` file - {MyComponentSource} + {SettingsExample}
-1. [Environment constants definitions](#1-environment-constants-definitions) +1. [Environment type constants definitions](#1-environment-constants-definitions) 2. [Site-specific settings](#2-site-specific-settings) 3. [Environment detection](#3-environment-detection) 4. [Per-environment overrides](#4-per-environment-overrides) 5. [Inclusion of generated Settings](#5-inclusion-of-per-module-settings) 6. [Inclusion of local settings](#6-inclusion-of-local-settings) -### 1. Environment constants definitions +### 1. Environment type constants definitions -Constants for various environments are defined here. These can be used to alter -site behavior based on the active environment. +Constants for various _environment types_ are defined here. These can be used to +alter site behavior based on the active _environment type_. -Available constants include: +Available _environment type_ constants are: - `ENVIRONMENT_LOCAL` - `ENVIRONMENT_CI` @@ -53,16 +54,16 @@ Available constants include: - `ENVIRONMENT_STAGE` - `ENVIRONMENT_DEV` -These are later used to set `$settings['environment']` variable, which can be -used in the modules and outside scripts to target code execution to specific -environments. +These are later used to set `$settings['environment']`, which can be +used in the modules and shell scripts to target code execution to specific +_environments types_. :::info[EXAMPLE] ```shell environment="$(drush php:eval "print \Drupal\core\Site\Settings::get('environment');")" if echo "${environment}" | grep -q -e ci -e local; then - # Do something only in ci, or local environments. + # Do something only in ci or local environments. fi ``` @@ -70,10 +71,10 @@ environments. :::info - The `$VORTEX_PROVISION_ENVIRONMENT` environment variable can be utilized - within post-provision custom scripts, allowing targeted code execution based - on specific environments. Refer to [Provision](provision.mdx) for additional - information. + The `$VORTEX_PROVISION_ENVIRONMENT` _environment variable_ can be utilized + within post-provision custom scripts instead of Drush command evaluation, + allowing targeted code execution based on a specific _environment type_. + Refer to [Provision](provision.mdx) for additional information. ::: @@ -84,58 +85,80 @@ ensuring security with trusted host patterns, setting performance optimizations like aggregating CSS and JS files, and specifying essential directories for Drupal's functionality. -These settings are identical for all environments. +These settings are identical for all _environment types_ . + +Use per-module settings files in the [`web/site/default/includes/modules`](https://github.com/drevops/vortex/tree/develop/web/sites/default/includes/modules) +directory to override per-module settings. + +### 3. Environment type detection + +This section uses known hosting providers mechanisms to determine the +_environment type_ where the site currently runs. -Use per-module settings files in the `web/site/default/includes` directory to -override per-module settings, including per-environment overrides. +Settings for the supported hosting providers are stored in the +[`web/site/default/includes/providers`](https://github.com/drevops/vortex/tree/develop/web/sites/default/includes/providers) +directory. You can add your own custom provider _environment type_ detection logic +by creating a new file `settings.[provider].php` in this directory. -### 3. Environment detection +Once a hosting provider is detected, the _environment type_ +`$settings['environment']` is set to +`ENVIRONMENT_DEV` for all environments as a default. -This section uses known hosting platform mechanisms to determine in which -environment the site currently runs. The result is stored in the -`$settings['environment']` variable. +Higher-level environments types (`PROD`, `STAGE` etc.) are then set based on +the **additional** detected provider-specific settings. -By default, `$settings['environment']` is set to `ENVIRONMENT_LOCAL`. -This value is then overridden by the environment detection logic. +When the hosting provider is not detected, the default value is set to +`ENVIRONMENT_LOCAL`. :::note - In any hosting environment, the default value of `$settings['environment']` - changes to `ENVIRONMENT_DEV`, while further refinements designate more - advanced environments. + Environment type detection settings are only used for _environment type_ + detection and not for environment-specific settings. Those are defined in + the [Per-environment overrides](#4-per-environment-overrides) section. + This approach allows for a more flexible and maintainable configuration + independent of a specific hosting provider. ::: -#### Environment detection override +#### Overriding environment type -It is also possible to force specific environment by setting -`DRUPAL_ENVIRONMENT` environment variable. In this case, the environment -detection will take place and will load any additional hosting platform settings, -but the final value of `$settings['environment']` will be set to the value of -`DRUPAL_ENVIRONMENT` variable. +It is also possible to force specific _environment type_ by setting +`DRUPAL_ENVIRONMENT` _environment variable_. This is useful in cases where a certain behavior is required for a specific -environment, but the environment detection logic does not provide it. Or as a -temporary override during testing. +environment, but the _environment type_ detection logic does not provide it. + +It is also useful when debugging _environment type_-specific issues locally. ### 4. Per-environment overrides -Configurations in this section alter the site's behavior based on the -environment. Out-of-the-box, **Vortex** provides overrides for CI and Local +Configurations in this section alter the site's behavior based on the detected +_environment type_ (see [Environment type detection](#3-environment-type-detection) +above). Out-of-the-box, **Vortex** provides overrides for CI and Local environments. -You can add additional overrides for other environments as needed. +You can add additional overrides for other _environment types_ as needed. ### 5. Inclusion of per-module settings This section includes any additional module-specific settings from the -`/includes` directory. +[`web/site/default/includes/modules`](https://github.com/drevops/vortex/tree/develop/web/sites/default/includes/modules) directory. + +**Vortex** ships with settings overrides for several popular contributed +modules. -**Vortex** ships with settings overrides for several popular contributed modules -used in almost every project. +The per _environment type_ overrides for each module should be placed into the +module-specific settings file. + +import ModuleSettingsExample from '!!raw-loader!./../../../../web/sites/default/includes/modules/settings.environment_indicator.php'; + +
+ Example of the `Environment indicator` module settings file + + {ModuleSettingsExample} + +
-The per environment overrides for modules should be also placed into files -in the `/includes` directory. ### 6. Inclusion of local settings @@ -146,12 +169,32 @@ copy `default.settings.local.php` and `default.services.local.yml` to `settings.local.php` and `services.local.yml`, respectively, to utilize this functionality. +import LocalSettingsExample from '!!raw-loader!./../../../../web/sites/default/default.settings.local.php'; + +
+ Click here to see the contents of the `default.settings.local.php` file + + {LocalSettingsExample} + +
+ + +import LocalServicesExample from '!!raw-loader!./../../../../web/sites/default/default.services.local.yml'; + +
+ Click here to see the contents of the `default.services.local.yml` file + + {LocalServicesExample} + +
+ + ## Testing settings with unit tests **Vortex** provides a [set of unit tests](https://github.com/drevops/vortex/blob/develop/tests/phpunit/Drupal) that -ensure that the settings apply correctly per environment. These tests are -supposed to be maintained within your project, ensuring that settings activated -by specific environments and environment variables are applied accurately. +ensure that the settings apply correctly per environment type. These tests are +expected to be maintained within your project, ensuring that settings activated +by a specific _environment type_ and _environment variables_ are applied correctly. After installing **Vortex**, run `vendor/bin/phpunit --group=drupal_settings` to run the tests for the settings provided by **Vortex**. diff --git a/.vortex/docs/content/tools/README.mdx b/.vortex/docs/content/tools/README.mdx index b828ede96..527d3dc2e 100644 --- a/.vortex/docs/content/tools/README.mdx +++ b/.vortex/docs/content/tools/README.mdx @@ -15,21 +15,22 @@ Some of the tools run in CI and would fail the build if they detect issues. Head over to the tool-specific documentation to learn more. -| Name | Description | -|-----------------------------------|------------------------------------------------------------------| -| [Ahoy](ahoy.mdx) | CLI command wrapper | -| [Behat](behat.mdx) | Testing framework for for auto-testing your business expectations | -| [Docker](docker.mdx) | A platform for containerizing and running applications | -| [Doctor](doctor.mdx) | Check **Vortex** project requirements or print info | -| [Drush](drush.mdx) | Command line shell and Unix scripting interface for Drupal | -| [Gherkin Lint](gherkin-lint.mdx) | Provides a Gherkin linter for PHP | -| [Git artifact](git-artifact.mdx) | Package and push files to remote repositories | -| [PHPCS](phpcs.mdx) | Check that code adheres to coding standards | -| [PHPMD](phpmd.mdx) | Detect code smells and possible errors | -| [PHPStan](phpstan.mdx) | PHP Static Analysis Tool | -| [PHPUnit](phpunit.mdx) | The PHP Testing Framework | -| [Pygmy](pygmy.mdx) | A local reverse-proxy and email catcher | -| [Rector](rector.mdx) | Instant Upgrades and Automated Refactoring | -| [Renovate](renovate.mdx) | A bot for automated dependency updates | -| [Twig CS Fixer](twig-cs-fixer.mdx) | Checkstyle for Twig | -| [Xdebug](xdebug.mdx) | Debugger and Profiler Tool for PHP | +| Name | Description | +|------------------------------------|---------------------------------------------------------------------------------| +| [Ahoy](ahoy.mdx) | CLI command wrapper | +| [Behat](behat.mdx) | Testing framework for for auto-testing your business expectations | +| [Docker](docker.mdx) | A platform for containerizing and running applications | +| [Doctor](doctor.mdx) | Check **Vortex** project requirements or retrieve environment information | +| [Drush](drush.mdx) | Command line shell and Unix scripting interface for Drupal | +| [Gherkin Lint](gherkin-lint.mdx) | Provides a Gherkin linter for PHP | +| [Git artifact](git-artifact.mdx) | Package and push files to remote repositories | +| [Hadolint](hadolint.mdx) | A smarter Dockerfile linter that helps you build best practice container images | +| [PHPCS](phpcs.mdx) | Check that code adheres to coding standards | +| [PHPMD](phpmd.mdx) | Detect code smells and possible errors | +| [PHPStan](phpstan.mdx) | PHP Static Analysis Tool | +| [PHPUnit](phpunit.mdx) | The PHP Testing Framework | +| [Pygmy](pygmy.mdx) | A local reverse-proxy and email catcher | +| [Rector](rector.mdx) | Instant Upgrades and Automated Refactoring | +| [Renovate](renovate.mdx) | A bot for automated dependency updates | +| [Twig CS Fixer](twig-cs-fixer.mdx) | Checkstyle for Twig | +| [Xdebug](xdebug.mdx) | Debugger and Profiler Tool for PHP | diff --git a/.vortex/docs/content/workflows/testing.mdx b/.vortex/docs/content/workflows/testing.mdx index 7e9055162..7c175a710 100644 --- a/.vortex/docs/content/workflows/testing.mdx +++ b/.vortex/docs/content/workflows/testing.mdx @@ -4,21 +4,42 @@ sidebar_position: 2 # Testing -**Vortex** supports running Unit (PHPUnit) and BDD (Behat) tests. +**Vortex** supports running Unit, Kernel, Functional, and BDD tests. -For local development, the tests can be run using handy Ahoy commands: +For local development, the tests can be run directly or using handy Ahoy +commands: -```bash -ahoy test # Run all tests +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -ahoy test-unit # Run Unit tests + + + ```shell + vendor/bin/phpunit # Run Unit, Kernel and Functional tests -ahoy test-kernel # Run Kernel tests + vendor/bin/phpunit --testsuite=unit # Run Unit tests -ahoy test-functional # Run Functional tests + vendor/bin/phpunit --testsuite=kernel # Run Kernel tests -ahoy test-bdd # Run BDD tests -``` + vendor/bin/phpunit --testsuite=functional # Run Functional tests + + vendor/bin/behat # Run BDD tests + ``` + + + ```shell + ahoy test # Run Unit, Kernel and Functional tests + + ahoy test-unit # Run Unit tests + + ahoy test-kernel # Run Kernel tests + + ahoy test-functional # Run Functional tests + + ahoy test-bdd # Run BDD tests + ``` + + In CI, tests are run by calling the test binaries directly. @@ -27,78 +48,82 @@ In CI, tests are run by calling the test binaries directly. **Vortex** uses PHPUnit as a framework for Unit testing. It is configured to use a copy of Drupal core's `core/phpunit.xml.dist` -configuration file. This is done to allow per-project customisations. +configuration file to allow customizing the test suite per project. ### Reporting -Test reports are stored in `$VORTEX_TEST_RESULTS_DIR/phpunit` directory +Test reports are stored in `.logs/phpunit` directory separated into multiple files and named after the suite name. These reports are usually used in CI to track tests performance and stability. -### Vortex +### Boilerplate -**Vortex** provides a Unit test scaffold for custom [modules](https://github.com/drevops/vortex/blob/develop/web/modules/custom/ys_core/tests/src), +**Vortex** provides Unit, Kernel and Functional tests boilerplate for custom [modules](https://github.com/drevops/vortex/blob/develop/web/modules/custom/ys_core/tests/src), [themes](https://github.com/drevops/vortex/blob/develop/web/themes/custom/your_site_theme/tests/src) and [scripts](https://github.com/drevops/vortex/blob/develop/tests/phpunit). -These tests already run in CI when you install **Vortex** and can be used as a -starting point for writing your own. +These boilerplate tests run in CI when you install **Vortex** and can be used as +a starting point for writing your own. #### Drupal settings tests -**Vortex** provides a [Drupal settings tests](https://github.com/drevops/vortex/blob/develop/tests/phpunit/DrupalSettingsTest.php) -to test that Drupal settings are correct based on the environment type the site +**Vortex** provides [Drupal settings tests](https://github.com/drevops/vortex/blob/develop/tests/phpunit/Drupal/DrupalSettingsTest.php) +to check that Drupal settings are correct based on the environment type the site is running: with the number of custom modules multiplied by the number of environment types, it is easy to miss certain settings which may lead to -unexpected issues with deployments. +unexpected issues when deploying a project to a different environment. -It is intended to be used in a consumer site and kept up-to-date with the -changes to the `settings.php` file. +It is intended to be used in your site and kept up-to-date with the +changes made to the `settings.php` file. #### CI configuration tests **Vortex** provides a [CI configuration tests](https://github.com/drevops/vortex/blob/develop/tests/phpunit/CircleCiConfigTest.php) -to assert that CI configuration is correct. It is intended to be used in a consumer +to check that the CI configuration is correct. It is intended to be used in your site and kept up-to-date with the CI configurations. -For example, there are tests for the regular expressions that control for which -branches the deployment job runs. Such test makes sure that there are no -unexpected surprises during the consumer site release to production. +For example, there are tests for regular expressions used to filter the branches +and tags before they are deployed to the hosting environment. ## BDD testing -**Vortex** uses Behat for Behavior-Driven Development (BDD) testing. +**Vortex** uses [Behat](https://behat.org) for Behavior-Driven Development (BDD) +testing. Behat allows to write human-readable stories that describe the behavior +of the application. Behat tests primarily focus on critical user journeys, +serving as comprehensive end-to-end validations. -It provides full Behat support, including configuration in [behat.yml](https://github.com/drevops/vortex/blob/develop/behat.yml) -and a [browser container](https://github.com/drevops/vortex/blob/develop/docker-compose.yml) to run interactive tests. +**Vortex** provides full Behat support, including configuration in [`behat.yml`](https://github.com/drevops/vortex/blob/develop/behat.yml) +and a [browser container](https://github.com/drevops/vortex/blob/develop/docker-compose.yml) to run tests interactively in a real browser with +a VNC viewer. -It also provides additional features: +Additional features include: 1. [Behat Drupal Extension](https://github.com/drupalprojects/drupalextension) - an extension to work with Drupal. 2. [Behat steps](https://github.com/drevops/behat-steps) - a library of re-usable Behat steps. 2. [Behat Screenshot](https://github.com/drevops/behat-screenshot) - extension to capture screenshots on-demand and on failure. -3. [Behat Progress formatter](https://github.com/drevops/behat-format-progress-fail) - extension to show progress as TAP and fails inline. +3. [Behat Progress formatter](https://github.com/drevops/behat-format-progress-fail) - extension to show progress as TAP and failures inline. 4. Parallel profiles - configuration to allow running tests in parallel. ### FeatureContext -The [FeatureContext.php](https://github.com/drevops/vortex/blob/develop/tests/behat/bootstrap/FeatureContext.php) file comes with +The [`FeatureContext.php`](https://github.com/drevops/vortex/blob/develop/tests/behat/bootstrap/FeatureContext.php) file comes with included steps from [Behat steps](https://github.com/drevops/behat-steps) package. -Custom steps can be added into this file. +You can add your custom steps into this file. ### Profiles -Behat `default` profile configured with sensible defaults to allow running Behat +Behat's `default` profile configured with sensible defaults to allow running it with provided extensions. -In CI, the profile can be overridden using `$VORTEX_CI_BEHAT_PROFILE` environment -variable. +In CI, the profile can be overridden using `$VORTEX_CI_BEHAT_PROFILE` +environment variable. ### Parallel runs -In CI, Behat tests can be tagged to be split between multiple runners. The tags -are then used by profiles with the identical names to run them. +In CI, Behat tests can run within multiple runners to increase the speed of the +test suite. To achieve this, Behat tags are used to mark features and scenarios +with `@p*` tags. Out of the box, **Vortex** provides support for unlimited parallel runners, but only 2 parallel profiles `p0` and `p1`: a feature can be tagged by @@ -122,25 +147,29 @@ Add `@skipped` tag to a feature or scenario to exclude it from the test run. Test screenshots are stored into `.logs/screenshots` location by default, which can be overwritten using `$BEHAT_SCREENSHOT_DIR` variable (courtesy of -[Behat Screenshot](https://github.com/drevops/behat-screenshot) package). In CI, screenshots are stored as artifacts -and are accessible in the Artifacts tab. +[Behat Screenshot](https://github.com/drevops/behat-screenshot) package). + +In CI, screenshots are stored as build artifacts. In GitHub Actions, they can be +downloaded from the `Summary` tab. In CircleCI they are accessible in +the `Artifacts` tab. ### Format Out of the box, **Vortex** comes with [Behat Progress formatter](https://github.com/drevops/behat-format-progress-fail) -Behat output formatter to show progress as TAP and fails inline. This allows to -continue test runs after failures while maintaining a minimal output. +output formatter to show progress as TAP and failures inline. This allows to +continue test runs after a failure while maintaining a minimal output. ### Reporting -Test reports produced if `$VORTEX_TEST_RESULTS_DIR` is set. They are stored in -`$VORTEX_TEST_RESULTS_DIR/behat` directory. These reports are usually used in -CI to track tests performance and stability. +Test reports are stored in `.logs/behat` directory. + +CI usually uses them to to track test performance and stability. -### Examples +### Boilerplate -**Vortex** provides BDD test examples for custom [modules](https://github.com/drevops/vortex/blob/develop/web/modules/custom/ys_core/tests/src) -and [themes](https://github.com/drevops/vortex/blob/develop/web/themes/custom/your_site_theme/tests/src). +**Vortex** provides BDD tests boilerplate for [homepage](https://github.com/drevops/vortex/blob/develop/tests/behat/features/homepage.feature) +and [login](https://github.com/drevops/vortex/blob/develop/tests/behat/features/login.feature) +user journeys. -These tests already run in CI when you install **Vortex** and can be used -as a starting point for writing your own. +These boilerplate tests run in CI when you install **Vortex** and can be used as +a starting point for writing your own. diff --git a/.vortex/docs/content/workflows/updating-vortex.mdx b/.vortex/docs/content/workflows/updating-vortex.mdx index 352074242..d193ecb99 100644 --- a/.vortex/docs/content/workflows/updating-vortex.mdx +++ b/.vortex/docs/content/workflows/updating-vortex.mdx @@ -4,18 +4,14 @@ sidebar_position: 9 # Updating Vortex -**Vortex** differs from other project templates in that it is not only used -for a one-time project setup but also for ongoing maintenance. This means that -you can update **Vortex** to the latest version at any time. +**Vortex** differs from other project templates: after the initial setup, you can +update it to get the latest features and bug fixes. -Once you the update process finishes, you will need to review the changes and -commit them to your project. - -If you have modified any of the files that are provided by **Vortex**, -the update process will override them, because **Vortex** is not aware of the -changes you have made. You would need to manually accept or reject the new -changes. +After the update, review and commit the changes to your project. +If you’ve modified files provided by Vortex, the update will overwrite them +since **Vortex** doesn’t track your changes. You’ll need to manually accept or +reject the updates. ```shell title="Update to the latest version" ahoy update-vortex diff --git a/web/sites/default/settings.php b/web/sites/default/settings.php index f97df69f2..b4ce39dea 100644 --- a/web/sites/default/settings.php +++ b/web/sites/default/settings.php @@ -5,7 +5,7 @@ * Drupal site-specific configuration file. * * The structure of this file: - * - Environment constants definitions. + * - Environment type constants definitions. * - Site-specific settings. * - Inclusion of hosting providers settings. * - Per-environment overrides. @@ -22,7 +22,7 @@ declare(strict_types=1); //////////////////////////////////////////////////////////////////////////////// -/// ENVIRONMENT CONSTANTS /// +/// ENVIRONMENT TYPE CONSTANTS /// //////////////////////////////////////////////////////////////////////////////// // Use these constants anywhere in code to alter behaviour for a specific @@ -50,6 +50,7 @@ //////////////////////////////////////////////////////////////////////////////// /// SITE-SPECIFIC SETTINGS /// //////////////////////////////////////////////////////////////////////////////// + $app_root = $app_root ?? DRUPAL_ROOT; $site_path = $site_path ?? 'sites/default'; $contrib_path = $app_root . DIRECTORY_SEPARATOR . (is_dir($app_root . DIRECTORY_SEPARATOR . 'modules/contrib') ? 'modules/contrib' : 'modules'); @@ -124,10 +125,10 @@ ]; //////////////////////////////////////////////////////////////////////////////// -/// ENVIRONMENT DETECTION /// +/// ENVIRONMENT TYPE DETECTION /// //////////////////////////////////////////////////////////////////////////////// -// Load environment-specific settings. +// Load provider-specific settings. if (file_exists($app_root . '/' . $site_path . '/includes/providers')) { $files = glob($app_root . '/' . $site_path . '/includes/providers/settings.*.php'); if ($files) {