Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 274105c

Browse filesBrowse files
weaverryanweaverryan
committed
feature #12958 Symfony 4.4 secrets management system (jderusse, weaverryan)
This PR was merged into the 4.4 branch. Discussion ---------- Symfony 4.4 secrets management system Hi! This completes #11396 I also made some changes to the section in `configuration.rst` about environment variables to make sure that it read well with the secrets stuff. Thanks to @jderusse for doing the vast majority of the work. Cheers! Commits ------- cd066cc tweaks thanks to review 75e5ae6 finishing the secrets documentation 82d2058 Add the secret documentation
2 parents b25b9c8 + cd066cc commit 274105c
Copy full SHA for 274105c

File tree

Expand file treeCollapse file tree

4 files changed

+438
-107
lines changed
Filter options
Expand file treeCollapse file tree

4 files changed

+438
-107
lines changed

‎best_practices.rst

Copy file name to clipboardExpand all lines: best_practices.rst
+6Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,12 @@ application behavior.
8787
:ref:`Use env vars in your project <config-env-vars>` to define these options
8888
and create multiple ``.env`` files to :ref:`configure env vars per environment <config-dot-env>`.
8989

90+
Use Secret for Sensitive Information
91+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92+
93+
When your application has sensitive configuration - like an API key - you should
94+
store those securely via :doc:`secrets </configuration/secrets>`.
95+
9096
Use Parameters for Application Configuration
9197
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
9298

‎configuration.rst

Copy file name to clipboardExpand all lines: configuration.rst
+109-105Lines changed: 109 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -436,14 +436,14 @@ Configuration Based on Environment Variables
436436

437437
Using `environment variables`_ (or "env vars" for short) is a common practice to
438438
configure options that depend on where the application is run (e.g. the database
439-
credentials are usually different in production and in your local machine).
439+
credentials are usually different in production versus your local machine). If
440+
the values are sensitive, you can even :doc:`encrypt them as secrets </configuration/secrets>`.
440441

441-
Instead of defining those as regular options, you can define them as environment
442-
variables and reference them in the configuration files using the special syntax
442+
You can reference environment variables using the special syntax
443443
``%env(ENV_VAR_NAME)%``. The values of these options are resolved at runtime
444444
(only once per request, to not impact performance).
445445

446-
This example shows how to configure the database connection using an env var:
446+
This example shows how you could configure the database connection using an env var:
447447

448448
.. configuration-block::
449449

@@ -485,164 +485,168 @@ This example shows how to configure the database connection using an env var:
485485
]
486486
]);
487487
488-
The next step is to define the value of those env vars in your shell, your web
489-
server, etc. This is explained in the following sections, but to protect your
490-
application from undefined env vars, you can give them a default value using the
491-
``.env`` file:
492-
493-
.. code-block:: bash
494-
495-
# .env
496-
DATABASE_URL=sqlite:///%kernel.project_dir%/var/data.db
497-
498488
.. seealso::
499489

500490
The values of env vars can only be strings, but Symfony includes some
501491
:doc:`env var processors </configuration/env_var_processors>` to transform
502492
their contents (e.g. to turn a string value into an integer).
503493

504-
In order to define the actual values of env vars, Symfony proposes different
505-
solutions depending if the application is running in production or in your local
506-
development machine.
507-
508-
Independent from the way you set environment variables, you may need to run the
509-
``debug:container`` command with the ``--env-vars`` option to verify that they
510-
are defined and have the expected values:
494+
To define the value of an env var, you have several options:
511495

512-
.. code-block:: terminal
496+
* :ref:`Add the value to a .env file <config-dot-env>`;
497+
* :ref:`Encrypt the value as a secret <configuration-secrets>`;
498+
* Set the value as a real environment variable in your shell or your web server.
513499

514-
$ php bin/console debug:container --env-vars
515-
516-
---------------- ----------------- ---------------------------------------------
517-
Name Default value Real value
518-
---------------- ----------------- ---------------------------------------------
519-
APP_SECRET n/a "471a62e2d601a8952deb186e44186cb3"
520-
FOO "[1, "2.5", 3]" n/a
521-
BAR null n/a
522-
---------------- ----------------- ---------------------------------------------
500+
.. tip::
523501

524-
# you can also filter the list of env vars by name:
525-
$ php bin/console debug:container --env-vars foo
502+
Some hosts - like SymfonyCloud - offer easy `utilities to manage env vars`_
503+
in production.
526504

527-
# run this command to show all the details for a specific env var:
528-
$ php bin/console debug:container --env-var=FOO
505+
.. caution::
529506

530-
.. versionadded:: 4.3
507+
Beware that dumping the contents of the ``$_SERVER`` and ``$_ENV`` variables
508+
or outputting the ``phpinfo()`` contents will display the values of the
509+
environment variables, exposing sensitive information such as the database
510+
credentials.
531511

532-
The option to debug environment variables was introduced in Symfony 4.3.
512+
The values of the env vars are also exposed in the web interface of the
513+
:doc:`Symfony profiler </profiler>`. In practice this shouldn't be a
514+
problem because the web profiler must **never** be enabled in production.
533515

534516
.. _configuration-env-var-in-dev:
535517
.. _config-dot-env:
536518

537-
Configuring Environment Variables in Development
538-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
519+
Configuring Environment Variables in .env Files
520+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
539521

540-
Instead of defining env vars in your shell or your web server, Symfony proposes
541-
a convenient way of defining them in your local machine based on a file called
542-
``.env`` (with a leading dot) located at the root of your project.
522+
Instead of defining env vars in your shell or your web server, Symfony provides
523+
a convenient way to define them inside a ``.env`` (with a leading dot) file
524+
located at the root of your project.
543525

544526
The ``.env`` file is read and parsed on every request and its env vars are added
545-
to the ``$_ENV`` PHP variable. The existing env vars are never overwritten by
546-
the values defined in ``.env``, so you can combine both.
527+
to the ``$_ENV`` & ``$_SERVER`` PHP variables. Any existing env vars are *never*
528+
overwritten by the values defined in ``.env``, so you can combine both.
547529

548-
This is for example the content of the ``.env`` file to define the value of the
549-
``DATABASE_URL`` env var shown earlier in this article:
530+
For example, to define the ``DATABASE_URL`` env var shown earlier in this article,
531+
you can add:
550532

551533
.. code-block:: bash
552534
553535
# .env
554536
DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name"
555537
538+
This file should be committed to your repository and (due to that fact) should
539+
only contain "default" values that are good for local development. This file
540+
should not contain production values.
541+
556542
In addition to your own env vars, this ``.env`` file also contains the env vars
557543
defined by the third-party packages installed in your application (they are
558544
added automatically by :ref:`Symfony Flex <symfony-flex>` when installing packages).
559545

546+
.. _configuration-multiple-env-files:
547+
548+
Overriding Environment Values via .env.local
549+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
550+
551+
If you need to override an environment value (e.g. to a different value on your
552+
local machine), you can do that in a ``.env.local`` file:
553+
554+
.. code-block:: bash
555+
556+
# .env.local
557+
DATABASE_URL="mysql://root:@127.0.0.1:3306/my_database_name"
558+
559+
This file should be ignored by git and should *not* be committed to your repository.
560+
Several other ``.env`` files are available to set environment variables in *just*
561+
the right situation:
562+
563+
* ``.env``: defines the default values of the env vars needed by the application;
564+
* ``.env.local``: overrides the default values for all environments but only on
565+
the machine which contains the file. This file should not be committed to the
566+
repository and it's ignored in the ``test`` environment (because tests should
567+
produce the same results for everyone);
568+
* ``.env.<environment>`` (e.g. ``.env.test``): overrides env vars only for one
569+
environment but for all machines (these files *are* committed);
570+
* ``.env.<environment>.local`` (e.g. ``.env.test.local``): defines machine-specific
571+
env var overrides only for one environment. It's similar to ``.env.local``,
572+
but the overrides only apply to one environment.
573+
574+
*Real* environment variables always win over env vars created by any of the
575+
``.env`` files.
576+
577+
The ``.env`` and ``.env.<environment>`` files should be committed to the
578+
repository because they are the same for all developers and machines. However,
579+
the env files ending in ``.local`` (``.env.local`` and ``.env.<environment>.local``)
580+
**should not be committed** because only you will use them. In fact, the
581+
``.gitignore`` file that comes with Symfony prevents them from being committed.
582+
583+
.. caution::
584+
585+
Applications created before November 2018 had a slightly different system,
586+
involving a ``.env.dist`` file. For information about upgrading, see:
587+
:doc:`configuration/dot-env-changes`.
588+
560589
.. _configuration-env-var-in-prod:
561590

562591
Configuring Environment Variables in Production
563592
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
564593

565-
In production, the ``.env`` files are also parsed and loaded on each request so
566-
you can add env vars to those already defined in the server. In order to improve
567-
performance, you can run the ``dump-env`` command (available when using
568-
:ref:`Symfony Flex <symfony-flex>` 1.2 or later).
594+
In production, the ``.env`` files are also parsed and loaded on each request. So
595+
the easiest way to define env vars is by deploying a ``.env.local`` file to your
596+
production server(s) with your production values.
569597

570-
This command parses all the ``.env`` files once and compiles their contents into
571-
a new PHP-optimized file called ``.env.local.php``. From that moment, Symfony
572-
will load the parsed file instead of parsing the ``.env`` files again:
598+
To improve performance, you can optionally run the ``dump-env`` command (available
599+
in :ref:`Symfony Flex <symfony-flex>` 1.2 or later):
573600

574601
.. code-block:: terminal
575602
603+
# parses ALL .env files and dumps their final values to .env.local.php
576604
$ composer dump-env prod
577605
606+
After running this command, Symfony will load the ``.env.local.php`` file to
607+
get the environment variables and will not spend time parsing the ``.env`` files.
608+
578609
.. tip::
579610

580611
Update your deployment tools/workflow to run the ``dump-env`` command after
581612
each deploy to improve the application performance.
582613

583-
.. _configuration-env-var-web-server:
614+
.. _configuration-secrets:
584615

585-
Creating ``.env`` files is the easiest way of using env vars in Symfony
586-
applications. However, you can also configure real env vars in your servers and
587-
operating systems.
616+
Encrypting Environment Variables (Secrets)
617+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
588618

589-
.. tip::
590-
591-
SymfonyCloud, the cloud service optimized for Symfony applications, defines
592-
some `utilities to manage env vars`_ in production.
593-
594-
.. caution::
619+
Instead of defining a real environment variable or adding it to a ``.env`` file,
620+
if the value of a variable is sensitive (e.g. an API key or a database password),
621+
you can encrypt the value using the :doc:`secrets management system </configuration/secrets>`.
595622

596-
Beware that dumping the contents of the ``$_SERVER`` and ``$_ENV`` variables
597-
or outputting the ``phpinfo()`` contents will display the values of the
598-
environment variables, exposing sensitive information such as the database
599-
credentials.
600-
601-
The values of the env vars are also exposed in the web interface of the
602-
:doc:`Symfony profiler </profiler>`. In practice this shouldn't be a
603-
problem because the web profiler must **never** be enabled in production.
604-
605-
.. _configuration-multiple-env-files:
606-
607-
Managing Multiple .env Files
608-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
623+
Listing Environment Variables
624+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
609625

610-
The ``.env`` file defines the default values for all env vars. However, it's
611-
common to override some of those values depending on the environment (e.g. to
612-
use a different database for tests) or depending on the machine (e.g. to use a
613-
different OAuth token on your local machine while developing).
626+
Regardless of how you set environment variables, you can see a full list with
627+
their values by running:
614628

615-
That's why you can define multiple ``.env`` files to override env vars. The
616-
following list shows the files loaded in all environments. The ``.env`` file is
617-
the only mandatory file and each file content overrides the previous one:
629+
.. code-block:: terminal
618630
619-
* ``.env``: defines the default values of the env vars needed by the application;
620-
* ``.env.local``: overrides the default values of env vars for all environments
621-
but only in the machine which contains the file (e.g. your development computer).
622-
This file should not be committed to the repository and it's ignored in the
623-
``test`` environment (because tests should produce the same results for everyone);
624-
* ``.env.<environment>`` (e.g. ``.env.test``): overrides env vars only for some
625-
environment but for all machines;
626-
* ``.env.<environment>.local`` (e.g. ``.env.test.local``): defines machine-specific
627-
env vars overrides only for some environment. It's similar to ``.env.local``,
628-
but the overrides only apply to some particular environment.
631+
$ php bin/console debug:container --env-vars
629632
630-
.. note::
633+
---------------- ----------------- ---------------------------------------------
634+
Name Default value Real value
635+
---------------- ----------------- ---------------------------------------------
636+
APP_SECRET n/a "471a62e2d601a8952deb186e44186cb3"
637+
FOO "[1, "2.5", 3]" n/a
638+
BAR null n/a
639+
---------------- ----------------- ---------------------------------------------
631640
632-
The real environment variables defined in the server always win over the
633-
env vars created by the ``.env`` files.
641+
# you can also filter the list of env vars by name:
642+
$ php bin/console debug:container --env-vars foo
634643
635-
The ``.env`` and ``.env.<environment>`` files should be committed to the shared
636-
repository because they are the same for all developers and machines. However,
637-
the env files ending in ``.local`` (``.env.local`` and ``.env.<environment>.local``)
638-
**should not be committed** because only you will use them. In fact, the
639-
``.gitignore`` file that comes with Symfony prevents them from being committed.
644+
# run this command to show all the details for a specific env var:
645+
$ php bin/console debug:container --env-var=FOO
640646
641-
.. caution::
647+
.. versionadded:: 4.3
642648

643-
Applications created before November 2018 had a slightly different system,
644-
involving a ``.env.dist`` file. For information about upgrading, see:
645-
:doc:`configuration/dot-env-changes`.
649+
The option to debug environment variables was introduced in Symfony 4.3.
646650

647651
.. _configuration-accessing-parameters:
648652

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.