minor #21223 Document how to resolve env var at compile time (nikophil)

javiereguiluz · javiereguiluz · commit 4f8ddfe9a84c · 2025-07-22T16:42:15.000+02:00
This PR was submitted for the 7.3 branch but it was merged into the 6.4 branch instead. Discussion ---------- Document how to resolve env var at compile time see https://symfony-devs.slack.com/archives/C3EQ7S3MJ/p1752843597330219 Resolving env var at compile is a unusual case, but this could be helpful from time to time. This piece of information is hard to find (I've found it [here](symfony/symfony#22456 (comment))), and it could be interesting to have it documented, with a meaningful warning. Commits ------- 4aaca90 Document how to resolve env var at compile time
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>`.
