add docs

Author: paulbalandan

user_guide_src/source/changelogs/v4.8.0.rst

@@ -256,6 +256,8 @@ Others
 
 - **Float and Double Casting:** Added support for precision and rounding mode when casting to float or double in entities.
 - Float and Double casting now throws ``CastException::forInvalidFloatRoundingMode()`` if an rounding mode other than up, down, even or odd is provided.
+- **Environment:** Added ``CodeIgniter\EnvironmentDetector`` class and corresponding ``environmentdetector`` service as a mockable wrapper around the ``ENVIRONMENT`` constant.
+  Framework internals that previously compared ``ENVIRONMENT`` directly now go through this service, making environment-specific branches reachable in tests via ``Services::injectMock()``. See :ref:`environment-detector-service`.
 
 ***************
 Message Changes

user_guide_src/source/general/environments.rst

@@ -145,6 +145,26 @@ You can also check the current environment by ``spark env`` command:
 
     php spark env
 
+.. _environment-detector-service:
+
+The ``environmentdetector`` service
+===================================
+
+.. versionadded:: 4.8.0
+
+As an alternative to reading the ``ENVIRONMENT`` constant directly, CodeIgniter
+provides the ``environmentdetector`` service, backed by the
+:php:class:`CodeIgniter\\EnvironmentDetector` class. Because it is a shared
+service, it can be mocked in tests (via ``Services::injectMock()``) to exercise
+environment-specific branches without having to redefine the ``ENVIRONMENT``
+constant.
+
+.. literalinclude:: environments/001.php
+
+Passing a value to the constructor overrides the detected environment; passing
+``null`` (the default) falls back to the ``ENVIRONMENT`` constant. An empty or
+whitespace-only string throws ``CodeIgniter\Exceptions\InvalidArgumentException``.
+
 *************************************
 Effects on Default Framework Behavior
 *************************************

user_guide_src/source/general/environments/001.php

@@ -0,0 +1,14 @@
+<?php
+
+$env = service('environmentdetector');
+
+// Get the current environment name.
+echo $env->get();
+
+// Check against the three built-in environments.
+$env->isProduction();
+$env->isDevelopment();
+$env->isTesting();
+
+// Match any one of several environments (useful for custom names).
+$env->is('production', 'staging');