Document how to resolve env var at compile time

nikophil · javiereguiluz · commit 4aaca90daf15 · 2025-07-22T16:42:11.000+02:00
diff --git a/components/dependency_injection/compilation.rst b/components/dependency_injection/compilation.rst
@@ -612,3 +612,21 @@ have the cache will be considered stale.
 
     In the full-stack framework the compilation and caching of the container
     is taken care of for you.
+
+.. _resolving-env-vars-at-compile-time:
+
+Resolving Environment Variable At Compile Time
+----------------------------------------------
+
+Environment variables value can be resolved at compile time by using the following code::
+
+    $parameterValue = $container->resolveEnvPlaceholders(
+        $container->getParameter('%env(ENV_VAR_NAME)%'),
+        true // Resolve to actual values
+    );
+
+.. warning::
+
+    Environment variables are usually a runtime concern. One of the major drawbacks of resolving them
+    at compile time is that you'll need to manually clear the cache when changing their value (which is exactly
+    what you don't have to do for env vars under normal circumstances).
diff --git a/configuration/env_var_processors.rst b/configuration/env_var_processors.rst
@@ -912,3 +912,9 @@ To enable the new processor in the app, register it as a service and
 tag. If you're using the
 :ref:`default services.yaml configuration <service-container-services-load-example>`,
 this is already done for you, thanks to :ref:`autoconfiguration <services-autoconfigure>`.
+
+Resolving Environment Variable At Compile Time
+----------------------------------------------
+
+Although environment variables are usually a runtime concept, you can also resolve them
+:ref:`at compile time <resolving-env-vars-at-compile-time>`.
