Merge pull request #3 from unleashedtech/feature/namespaced-vars

Adding support for namespaced variable names...

Author: dl-unleashed-technologies

.gitignore

@@ -3,3 +3,4 @@
 composer.lock
 composer.phar
 /vendor/
+*.ignore.*

CHANGELOG.md

@@ -4,6 +4,14 @@ Updates should follow the [Keep a CHANGELOG](https://keepachangelog.com/) princi
 
 ## [Unreleased][unreleased]
 
+## [0.3.0] - 2022-05-17
+
+### Changed
+
+- Added support for namespaced variable names.
+- Added support for `SALT`.
+- Removed support for `SHIELD*` vars. Use `PUBLIC` instead.
+
 ## [0.2.1] - 2022-03-30
 
 ### Fixed
@@ -141,7 +149,8 @@ Updates should follow the [Keep a CHANGELOG](https://keepachangelog.com/) princi
 
 **Initial release!**
 
-[unreleased]: https://github.com/unleashedtech/dotenv-drupal/compare/0.2.1...main
+[unreleased]: https://github.com/unleashedtech/dotenv-drupal/compare/0.3.0...main
+[0.3.0]: https://github.com/unleashedtech/dotenv-drupal/compare/0.2.1...0.3.0
 [0.2.1]: https://github.com/unleashedtech/dotenv-drupal/compare/0.2.0...0.2.1
 [0.2.0]: https://github.com/unleashedtech/dotenv-drupal/compare/0.1.17...0.2.0
 [0.1.17]: https://github.com/unleashedtech/dotenv-drupal/compare/0.1.16...0.1.17

README.md

@@ -107,17 +107,21 @@ Environment variables can be set in `.env` files, or via modifying server config
 For production environments, environment variables should ideally be defined via server
 configuration.
 
+Multi-site installations often need config that differs from the default site.
+This package first checks for variables following the `{{ app }}__{{ site }}__{{ var }}`
+naming convention, before falling back to the `{{ var }}` naming convention.
+
+You can provide site-specific information via namespaced environment variables.
+
 * [DATABASE_URL](#database_url)
 * [FILE_PUBLIC_PATH](#file_public_path)
 * [FILE_PRIVATE_PATH](#file_private_path)
 * [FILE_TEMP_PATH](#file_temp_path)
 * [CONFIG_SYNC_PATH](#config_sync_path)
 * [DOMAINS](#domains)
 * [MAILGUN_URL](#mailgun_url)
-* [SHIELD](#shield)
-* [SHIELD_USERNAME](#shield_username)
-* [SHIELD_PASSWORD](#shield_password)
-* [SHIELD_MESSAGE](#shield_message)
+* [PUBLIC](#public)
+* [SALT](#salt)
 * [SITES](#sites)
 * [SOLR_URL](#solr_url)
 * [TRUSTED_HOST_PATTERNS](#trusted_host_patterns)
@@ -133,13 +137,35 @@ DATABASE_URL=driver://user:password@host:port/database
 For example:
 
 ```dotenv
-DATABASE_URL=mysql://foo:bar@host:3306/baz
+DATABASE_URL=mysql://foo:bar@localhost:3306/baz
 ```
 
-For multi-site installations, do _not_ specify a database name in the `DATABASE_URL` variable:
+For multi-site installations, do _not_ specify a database name nor credentials in
+the `DATABASE_URL` variable:
 
 ```dotenv
-DATABASE_URL=mysql://foo:bar@host:3306
+DATABASE_URL=mysql://localhost:3306
+```
+
+For an "earth" Drupal App with a "default" site & an "antarctica" site:
+```dotenv
+DATABASE_URL=mysql://localhost:3306
+
+EARTH__DEFAULT__DATABASE_USER=foo
+EARTH__DEFAULT__DATABASE_PASSWORD=bar
+
+EARTH__ANTARCTICA__DATABASE_USER=baz
+EARTH__ANTARCTICA__DATABASE_PASSWORD=qux
+```
+
+The default Drupal [App Name](#app-name) is "default". For most use cases, you'll want to set the
+Drupal [App Name](#app-name) in the default `settings.php` file, as shown below:
+```php
+<?php
+use UnleashedTech\Drupal\Dotenv\Dotenv;
+$dotenv = $dotenv ?? new Dotenv();
+$dotenv->setAppName('earth');
+// ...
 ```
 
 #### FILE_PUBLIC_PATH
@@ -194,33 +220,32 @@ MAILGUN_URL=https://[email protected]
 MAILGUN_URL=https://[email protected]
 ```
 
-#### SHIELD
+#### PUBLIC
 A string allowing the enabling/disabling of Shield module auth functionality.
 
-If empty, shield will not be enabled.
+If `true`, Shield will not be enabled.
 
-If filled, the string will be used as username & password by default.
+If `false`, the username will be the [App Name](#app-name) & the password will
+be the [Site Name](#site-name).
 
 Note: _Make sure the "Enable Shield" checkbox is checked in Drupal & that config is committed._
 
-##### SHIELD_USERNAME
-The username for Shield to require, if enabled.
-
-This package will use the value of `SHIELD` as username, by default.
+#### SITES
+A CSV list of Drupal "sites" (e.g. "subdomains") used by the given environment:
 
-##### SHIELD_PASSWORD
-The password for Shield to require, if enabled.
+```dotenv
+SITES=foo,bar,baz,qux
+```
 
-This package will use the value of `SHIELD` as password, by default.
+#### SALT
+A string used for "one-time login links, cancel links, form tokens, etc."
 
-##### SHIELD_MESSAGE
-The _public_ message Shield should show in the auth prompt if enabled.
+[Best Practices Issue](https://www.drupal.org/project/drupal/issues/3107548)
 
-#### SITES
-A CSV list of Drupal "sites" (e.g. "subdomains") used by the given environment:
+Use `drush eval "var_dump(Drupal\Component\Utility\Crypt::randomBytesBase64(55))"` to generate one.
 
 ```dotenv
-SITES=foo,bar,baz,qux
+SALT=generatedSaltValue
 ```
 
 #### SOLR_URL
@@ -269,6 +294,14 @@ Drupal `trusted_host_patterns` setting array would have the following values:
 * `^baz\.foo\.example$`
 * `^qux\.foo\.example$`
 
+#### Terms
+
+##### App Name
+The machine name of the Drupal App (e.g. "default" or "earth").
+
+##### Site Name
+The site name for a Drupal App Site (e.g. "default" or "antarctica").
+
 #### Configuration Conclusion
 With these few Environment Variables, you will be able to configure Drupal in a streamlined
 fashion similar to the way Symfony is configured. Support for many more common Drupal features