Merge pull request #7454 from kenjis/docs-improve-env-var-and-config

docs: improve description on Env Vars and Config values

Author: kenjis

user_guide_src/source/database/configuration.rst

@@ -104,6 +104,20 @@ default group's configuration settings. The values should be name following this
     database.default.password = '';
     database.default.database = 'ci4';
 
+But you cannot add a new property by setting environment variables, nor change a
+scalar value to an array. See :ref:`env-var-replacements-for-data` for details.
+
+So if you want to use SSL with MySQL, you need a hack. For example, set the array
+values as a JSON string in your **.env** file:
+
+::
+
+    database.default.encrypt = {"ssl_verify":true,"ssl_ca":"/var/www/html/BaltimoreCyberTrustRoot.crt.pem"}
+
+and decode it in the constructor in the Config class:
+
+.. literalinclude:: configuration/009.php
+
 **********************
 Explanation of Values:
 **********************

user_guide_src/source/database/configuration/009.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Database\Config;
+
+/**
+ * Database Configuration
+ */
+class Database extends Config
+{
+    // ...
+
+    public function __construct()
+    {
+        // ...
+
+        $array = json_decode($this->default['encrypt'], true);
+        if (is_array($array)) {
+            $this->default['encrypt'] = $array;
+        }
+    }
+}

user_guide_src/source/general/configuration.rst

@@ -150,6 +150,9 @@ Configuration Classes and Environment Variables
 When you instantiate a configuration class, any *namespaced* environment variables
 are considered for merging into the configuration object's properties.
 
+.. important:: You cannot add a new property by setting environment variables,
+    nor change a scalar value to an array. See :ref:`env-var-replacements-for-data`.
+
 If the prefix of a namespaced variable exactly matches the namespace of the configuration
 class, then the trailing part of the setting (after the dot) is treated as a configuration
 property. If it matches an existing configuration property, the environment variable's
@@ -180,20 +183,26 @@ Since v4.1.5, you can also write with underscores::
 
 .. note:: When using the *short prefix* the property names must still exactly match the class defined name.
 
+.. _env-var-replacements-for-data:
+
 Environment Variables as Replacements for Data
 ==============================================
 
 It is very important to always remember that environment variables contained in your **.env** are
-**only replacements for existing data**. This means that you cannot expect to fill your **.env** with all
-the replacements for your configurations but have nothing to receive these replacements in the
-related configuration file(s).
+**only replacements for existing data**.
+
+Simply put, you can change only the property value that exists in the Config class
+by setting it in your **.env**.
+
+You cannot add a property that is not defined in the Config class, nor can you
+change it to an array if the value of the defined property is a scalar.
 
-The **.env** only serves to fill or replace the values in your configuration files. That said, your
-configuration files should have a container or receiving property for those. Adding so many variables in
-your **.env** with nothing to contain them in the receiving end is useless.
+For example, you cannot just put ``app.myNewConfig = foo`` in your **.env** and
+expect your ``Config\App`` to magically have that property and value at run time.
 
-Simply put, you cannot just put ``app.myNewConfig = foo`` in your **.env** and expect your ``Config\App``
-to magically have that property and value at run time.
+When you have the property ``$default = ['encrypt' => false]`` in your
+``Config\Database``, you cannot change the ``encrypt`` value to an array even if
+you put ``database.default.encrypt.ssl_verify = true`` in your **.env**.
 
 Treating Environment Variables as Arrays
 ========================================