From 37f7c5f4f1deb7b4059748a2b7efbefe9a6c4ccd Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 20 Feb 2024 10:16:09 +0900 Subject: [PATCH 1/2] docs: add "What are Configuration Classes?" --- .../source/general/configuration.rst | 18 ++++++++++++++++++ .../source/libraries/official_packages.rst | 2 ++ 2 files changed, 20 insertions(+) diff --git a/user_guide_src/source/general/configuration.rst b/user_guide_src/source/general/configuration.rst index f7d6c2d78d34..3209510dc7ef 100644 --- a/user_guide_src/source/general/configuration.rst +++ b/user_guide_src/source/general/configuration.rst @@ -15,6 +15,24 @@ the application configuration files in the **app/Config** folder. :local: :depth: 2 + +What are Configuration Classes? +******************************* + +Configuration classes are utilized to define system default configuration values. +System configuration values are typically *static*. Configuration classes are +intended to retain the settings that configure how the application operates, +rather than responding to each user's individual settings. + +It is not recommended to alter values set during the instantiation of a +configuration class later during execution. In other words, it is recommended to +treat configuration classes as immutable or readonly classes. This is especially +important if you utilize :ref:`factories-config-caching`. + +Configuration values can be retrieved from environment variables, hard-coded +within the class files, or stored in a database using the :ref:`Settings ` +library. + Working with Configuration Files ******************************** diff --git a/user_guide_src/source/libraries/official_packages.rst b/user_guide_src/source/libraries/official_packages.rst index 6da2f41fd2b7..ccadc81599bc 100644 --- a/user_guide_src/source/libraries/official_packages.rst +++ b/user_guide_src/source/libraries/official_packages.rst @@ -29,6 +29,8 @@ Among the many features, it includes: * Per-user permission overrides, * and more... +.. _settings: + ******** Settings ******** From 5c8bc0339556782cbbf2eb5d339a6fa9f6ebafe7 Mon Sep 17 00:00:00 2001 From: kenjis Date: Tue, 20 Feb 2024 21:27:11 +0900 Subject: [PATCH 2/2] docs: remove misleading description --- user_guide_src/source/general/configuration.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/user_guide_src/source/general/configuration.rst b/user_guide_src/source/general/configuration.rst index 3209510dc7ef..13b412ff3e1e 100644 --- a/user_guide_src/source/general/configuration.rst +++ b/user_guide_src/source/general/configuration.rst @@ -29,9 +29,8 @@ configuration class later during execution. In other words, it is recommended to treat configuration classes as immutable or readonly classes. This is especially important if you utilize :ref:`factories-config-caching`. -Configuration values can be retrieved from environment variables, hard-coded -within the class files, or stored in a database using the :ref:`Settings ` -library. +Configuration values can be hard-coded in the class files or obtained from +environment variables at instantiation. Working with Configuration Files ********************************