Skip to content

Commit 274105c

Browse 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

File tree

4 files changed

+438
-107
lines changed

4 files changed

+438
-107
lines changed

‎best_practices.rst

Lines 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

Lines 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)