Movatterモバイル変換

[0]ホーム
URL:

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

 Sign up
Appearance settings

Commita49109f

Browse files
committed
updating docs for .env changes
1 parent552c488 commita49109f

File tree

12 files changed

+181
-51
lines changed

12 files changed

+181
-51
lines changed

‎best_practices/configuration.rst‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ application behavior.
1919

2020
Define the infrastructure-related configuration options as
2121
:doc:`environment variables</configuration/external_parameters>`. During
22-
development, use the ``.env`` file at the root of your project to set these.
22+
development, use the ``.env`` and ``.env.local`` files at the root of your project
23+
to set these.
2324

2425
By default, Symfony adds these types of options to the ``.env`` file when
2526
installing new dependencies in the app:
@@ -42,6 +43,9 @@ they have nothing to do with the application's behavior. In other words, your
4243
application doesn't care about the location of your database or the credentials
4344
to access to it, as long as the database is correctly configured.
4445

46+
To override these variables with machine-specific or sensitive values, create a
47+
``env.local`` file. This file should not be added to version control.
48+
4549
..caution::
4650

4751
Beware that dumping the contents of the ``$_SERVER`` and ``$_ENV`` variables
@@ -56,14 +60,18 @@ Canonical Parameters
5660

5761
..best-practice::
5862

59-
Define all your application's env vars in the ``.env.dist`` file.
63+
Define all your application's env vars in the ``.env`` file.
64+
65+
Symfony includes a configuration file called ``.env`` at the project root, which
66+
stores the canonical list of environment variables for the application. This
67+
file should be stored in version control and so should only contain non-sensitive
68+
default values.
6069

61-
Symfony includes a configuration file called ``.env.dist`` at the project root,
62-
which stores the canonical list of environment variables for the application.
70+
..caution::
6371

64-
Whenever a new env var is defined for the application, you should also add it to
65-
this file and submit the changes to your version control system so your
66-
workmates can update their ``.env`` files.
72+
Applications created before November 2018 had a slightly different system,
73+
involving a ``.env.dist`` file. For information about upgrading, see:
74+
:doc:`/configuration/dot-env-changes`.
6775

6876
Application-Related Configuration
6977
---------------------------------

‎configuration.rst‎

Lines changed: 32 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -263,10 +263,12 @@ a controller - see :ref:`service-container-parameters`.
263263
The .env File & Environment Variables
264264
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
265265

266-
There is also a ``.env`` file which is loaded. Its contents become environment
267-
variables in the dev environment, making it easier to reference environment
268-
variables in your code. When you install packages, more environment variables are
269-
added to this file. But you can also add your own variables.
266+
There is also a ``.env`` file which is loaded and its contents become environment
267+
variables. This is useful during development, or if setting environment variables
268+
is difficult for your deployment.
269+
270+
When you install packages, more environment variables are added to this file. But
271+
you can also add your own.
270272

271273
Environment variables can be referenced in any other configuration files by using
272274
a special syntax. For example, if you install the ``doctrine`` package, then you
@@ -285,18 +287,34 @@ This is referenced inside ``config/packages/doctrine.yaml``:
285287
286288
For more details about environment variables, see:ref:`config-env-vars`.
287289

290+
..caution::
291+
292+
Applications created before November 2018 had a slightly different system,
293+
involving a ``.env.dist`` file. For information about upgrading, see:
294+
:doc:`configuration/dot-env-changes`.
295+
288296
The ``.env`` file is special, because it defines the values that usually change
289297
on each server. For example, the database credentials on your local development
290-
machine might be different from your workmates. That's why this file is **not
291-
committed to the shared repository** and is only stored on your machine. In
292-
fact, the ``.gitignore`` file that comes with Symfony prevents it from being
293-
committed.
294-
295-
However, a ``.env.dist`` file *is* committed (with dummy values). This file
296-
isn't read by Symfony: it's just a reference so that Symfony knows which
297-
variables need to be defined in the ``.env`` file. If you add or remove keys to
298-
``.env``, add or remove them from ``.env.dist`` too, so both files are always
299-
in sync.
298+
machine might be different from your workmates. The ``.env`` file should contain
299+
sensible, non-secret *default* values for all of your environment variables and
300+
*should* be commited to your repository.
301+
302+
To override these variables with machine-specific or sensitive values, create a
303+
``env.local`` file. This file is **not committed to the shared repository** and
304+
is only stored on your machine. In fact, the ``.gitignore`` file that comes with
305+
Symfony prevents it from being committed.
306+
307+
You can also create a few other ``.env`` files that will be loaded:
308+
309+
* ``.env.{environment}``: e.g. ``.env.test`` will be loaded in the ``test`` environment
310+
and committed to your repository.
311+
312+
* ``.env.{environment}.local``: e.g. ``.env.prod.local`` will be loaded in the
313+
``prod`` environment but will *not* be committed to your repository.
314+
315+
If you decide to set real environment variables on production, the ``.env`` files
316+
will *not* be loaded if Symfony detects that a real ``APP_ENV`` environment variable
317+
exists and is set to ``prod``.
300318

301319
Environments & the Other Config Files
302320
-------------------------------------

‎configuration/dot-env-changes.rst‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
Nov 2018 Changes to .env & How to Update
2+
========================================
3+
4+
In November 2018, several changes were made to the core Symfony *recipes* related
5+
to the ``.env`` file. These changes make working with environment variables easier
6+
and more consistent - especially when writing functional tests.
7+
8+
If your app was started before November 2018, your app **does not require any changes
9+
to keep working**. However, if/when you are ready to take advantage of these improvements,
10+
you will need to make a few small updates.
11+
12+
What Changed Exactly?
13+
---------------------
14+
15+
But first, what changed? On a high-level, not much. Here's a summary of the most
16+
important changes:
17+
18+
* A) The ``.env.dist`` file no longer exists. Its contents should be moved to your
19+
``.env`` file (see the next point).
20+
21+
* B) The ``.env`` file **is** now commited to your repository. It was previously ignored
22+
via the ``.gitignore`` file (the updated recipe does not ignore this file). Because
23+
this file is committed, it should contain non-sensitive, default values. Basically,
24+
the ``.env.dist`` file was moved to ``.env``.
25+
26+
* C) A ``.env.local`` file can now be created to *override* environment variables for
27+
your machine. This file is ignored in the new ``.gitignore``.
28+
29+
* D) When testing, your ``.env`` file is now read, making it consistent with all
30+
other environments. You can also create a ``.env.test`` file for test-environment
31+
overrides.
32+
33+
There are a few other improvements, but these are the most important. To take advantage
34+
of these, you *will* need to modify a few files in your existing app.
35+
36+
Updating My Application
37+
-----------------------
38+
39+
If you created your application after November 15th 2018, you don't need to make
40+
any changes! Otherwise, here is the list of changes you'll need to make - these
41+
changes can be made to any Symfony 3.4 or higher app:
42+
43+
#. Create a new `src/.bootstrap.php`_ file in your project. This file loads Composer's
44+
autoloader and loads all the ``.env`` files as needed.
45+
46+
#. Update your `public/index.php`_ (`index.php diff`_) file to load the new ``src/.bootstrap.php``
47+
file. If you've customized this file, make sure to keep those changes (but use
48+
the rest of the changes).
49+
50+
#. Update your `bin/console`_ (`bin/console diff`_) file to load the new ``src/.bootstrap.php`` file.
51+
52+
#. Update ``.gitignore``:
53+
54+
..code-block::diff
55+
56+
# .gitignore
57+
# ...
58+
59+
###> symfony/framework-bundle ###
60+
- /.env
61+
+ /.env.local
62+
+ /.env.*.local
63+
64+
# ...
65+
66+
#. Rename ``.env`` to ``.env.local`` and ``.env.dist`` to ``.env``:
67+
68+
..code-block::terminal
69+
70+
# Unix
71+
$ mv .env .env.local
72+
$ git mv .env.dist .env
73+
74+
# Windows
75+
$ mv .env .env.local
76+
$ git mv .env.dist .env
77+
78+
You can also update the `comment on the top of .env`_ to reflect the new changes.
79+
80+
#. If you're using PHPUnit, you will also need to `create a new .env.test`_ file
81+
and update your `phpunit.xml.dist file`_ so it loads the ``src/.bootstrap.php``
82+
file.
83+
84+
.. _`src/.bootstrap.php`:https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/3.3/src/.bootstrap.php
85+
.. _`public/index.php`:https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/3.3/public/index.php
86+
.. _`index.php diff`:https://github.com/symfony/recipes/compare/8a4e5555e30d5dff64275e2788a901f31a214e79...86e2b6795c455f026e5ab0cba2aff2c7a18511f7#diff-473fca613b5bda15d87731036cb31586
87+
.. _`bin/console`:https://github.com/symfony/recipes/blob/master/symfony/console/3.3/bin/console
88+
.. _`bin/console diff`:https://github.com/symfony/recipes/compare/8a4e5555e30d5dff64275e2788a901f31a214e79...86e2b6795c455f026e5ab0cba2aff2c7a18511f7#diff-2af50efd729ff8e61dcbd936cf2b114b
89+
.. _`comment on the top of .env`:https://github.com/symfony/recipes/blob/master/symfony/flex/1.0/.env
90+
.. _`create a new .env.test`:https://github.com/symfony/recipes/blob/master/symfony/phpunit-bridge/3.3/.env.test
91+
.. _`phpunit.xml.dist file`:https://github.com/symfony/recipes/blob/master/symfony/phpunit-bridge/3.3/phpunit.xml.dist

‎configuration/environments.rst‎

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -80,11 +80,11 @@ Executing an Application in different Environments
8080
--------------------------------------------------
8181

8282
To execute the application in each environment, change the ``APP_ENV``
83-
environment variable. During development, this is done in ``.env``:
83+
environment variable. During development, this is done in ``.env`` or in ``.env.local``:
8484

8585
..code-block::bash
8686
87-
# .env
87+
# .env or .env.local
8888
APP_ENV=dev
8989
9090
# or for test:
@@ -95,7 +95,7 @@ your application in the configured environment.
9595

9696
..tip::
9797

98-
In production,it is recommended to configure theenvironment variablesin
98+
In production,you can use realenvironment variablesvia
9999
your:ref:`web server configuration<configuration-env-var-in-prod>`.
100100

101101
..note::
@@ -109,14 +109,10 @@ the environment variable is passed to the kernel::
109109
// public/index.php
110110

111111
// ...
112-
$kernel = new Kernel($_SERVER['APP_ENV'] ?? 'dev', $_SERVER['APP_DEBUG'] ?? false);
112+
$kernel = new Kernel($_SERVER['APP_ENV'], $_SERVER['APP_DEBUG']);
113113

114114
// ...
115115

116-
You can also replace ``$_SERVER['APP_ENV'] ?? 'dev'`` by just ``'dev'`` to
117-
always run the application in the dev environment, independent of the
118-
``APP_ENV`` variable.
119-
120116
..note::
121117

122118
The ``test`` environment is used when writing functional tests and is
@@ -251,7 +247,7 @@ environment through your browser:
251247

252248
..code-block::bash
253249
254-
# .env
250+
# .env or .env.local
255251
APP_ENV=benchmark
256252
257253
..sidebar::Importing configuration

‎deployment.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -125,21 +125,21 @@ B) Configure your Environment Variables
125125
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126126

127127
Most Symfony applications read their configuration from environment variables.
128-
While developing locally, you'll usually store these ina``.env``file. On production,
129-
you have two options:
128+
While developing locally, you'll usually store these in ``.env``and ``.env.local``
129+
(for local overrides). On production,you have two options:
130130

131131
1. Create "real" environment variables. How you set environment variables, depends
132132
on your setup: they can be set at the command line, in your Nginx configuration,
133133
or via other methods provided by your hosting service.
134134

135-
2. Or, create a ``.env`` file just like your local development (see note below)
135+
2. Or, create a ``.env.local`` file just like your local development (see note below)
136136

137137
There is no significant advantage to either of the two options: use whatever is
138138
most natural in your hosting environment.
139139

140140
..note::
141141

142-
If you use the ``.env``file on production, you may need to move your
142+
If you use the ``.env.*``files on production, you may need to move your
143143
``symfony/dotenv`` dependency from ``require-dev`` to ``require`` in ``composer.json``:
144144

145145
..code-block::terminal

‎doctrine.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ The database connection information is stored as an environment variable called
3939

4040
..code-block::text
4141
42-
# .env
42+
# .env (or override DATABASE_URL in .env.local to avoid committing your changes)
4343
4444
# customize this line!
4545
DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name"

‎doctrine/dbal.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Then configure the ``DATABASE_URL`` environment variable in ``.env``:
3131

3232
..code-block::text
3333
34-
# .env
34+
# .env (or override DATABASE_URL in .env.local to avoid committing your changes)
3535
3636
# customize this line!
3737
DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name"

‎doctrine/reverse_engineering.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ to a post record thanks to a foreign key constraint.
4747
) ENGINE=InnoDB AUTO_INCREMENT=1 DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;
4848
4949
Before diving into the recipe, be sure your database connection parameters are
50-
correctly setup in the ``.env`` file.
50+
correctly setup in the ``.env`` file (or ``.env.local`` override file).
5151

5252
The first step towards building entity classes from an existing database
5353
is to ask Doctrine to introspect the database and generate the corresponding

‎email.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@ environment variable in the ``.env`` file:
3434

3535
..code-block::bash
3636
37+
# .env (or override MAILER_URL in .env.local to avoid committing your changes)
38+
3739
# use this to disable email delivery
3840
MAILER_URL=null://localhost
3941

‎quick_tour/the_big_picture.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,6 @@ Symfony application:
2929
3030
quick_tour/
3131
├─ .env
32-
├─ .env.dist
3332
├─ bin/console
3433
├─ composer.json
3534
├─ composer.lock

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp