Skip to content

Commit

Permalink
Updated Testing workflow and Settings docs pages.
Browse files Browse the repository at this point in the history
  • Loading branch information
@AlexSkrypnyk
AlexSkrypnyk committed Dec 10, 2024
1 parent 898726a commit 3f116b1
Show file tree
Hide file tree
Showing 7 changed files with 201 additions and 130 deletions.
1 change: 1 addition & 0 deletions .vortex/docs/content/README.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion .vortex/docs/content/drupal/composer.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
141 changes: 92 additions & 49 deletions .vortex/docs/content/drupal/settings.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -24,56 +25,56 @@ 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';

<details>
<summary>Click here to see the contents of the `settings.php` file</summary>

<CodeBlock language="php">{MyComponentSource}</CodeBlock>
<CodeBlock language="php">{SettingsExample}</CodeBlock>

</details>

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`
- `ENVIRONMENT_PROD`
- `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
```

:::

:::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.

:::

Expand All @@ -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';

<details>
<summary>Example of the `Environment indicator` module settings file</summary>

<CodeBlock language="json">{ModuleSettingsExample}</CodeBlock>

</details>

The per environment overrides for modules should be also placed into files
in the `/includes` directory.

### 6. Inclusion of local settings

Expand All @@ -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';

<details>
<summary>Click here to see the contents of the `default.settings.local.php` file</summary>

<CodeBlock language="php">{LocalSettingsExample}</CodeBlock>

</details>


import LocalServicesExample from '!!raw-loader!./../../../../web/sites/default/default.services.local.yml';

<details>
<summary>Click here to see the contents of the `default.services.local.yml` file</summary>

<CodeBlock language="php">{LocalServicesExample}</CodeBlock>

</details>


## 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**.
Expand Down
37 changes: 19 additions & 18 deletions .vortex/docs/content/tools/README.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Loading

0 comments on commit 3f116b1

Please sign in to comment.