diff --git a/_build/redirection_map b/_build/redirection_map index 7e8c54bd737..b3344cdca95 100644 --- a/_build/redirection_map +++ b/_build/redirection_map @@ -417,3 +417,7 @@ /workflow/state-machines /workflow/introduction /workflow/usage /workflow /introduction/from_flat_php_to_symfony2 /introduction/from_flat_php_to_symfony +/configuration/environment_variables /configuration/env_var_processors +/configuration/configuration_organization /configuration +/configuration/environments /configuration +/configuration/configuration_organization /configuration diff --git a/best_practices/configuration.rst b/best_practices/configuration.rst index 604c28974f5..80d4273c6a1 100644 --- a/best_practices/configuration.rst +++ b/best_practices/configuration.rst @@ -16,9 +16,8 @@ application behavior. .. best-practice:: Define the infrastructure-related configuration options as - :doc:`environment variables `. During - development, use the ``.env`` and ``.env.local`` files at the root of your - project to set these. + :ref:`environment variables `. During development, use the + ``.env`` and ``.env.local`` files at the root of your project to set these. By default, Symfony adds these types of options to the ``.env`` file when installing new dependencies in the app: @@ -84,7 +83,7 @@ layer of configuration that's not needed because you don't need or want these configuration values to change on each server. The configuration options defined in the ``services.yaml`` may vary from one -:doc:`environment ` to another. That's why Symfony +:ref:`environment ` to another. That's why Symfony supports defining ``config/services_dev.yaml`` and ``config/services_prod.yaml`` files so that you can override specific values for each environment. diff --git a/bundles.rst b/bundles.rst index 2f0fb608c04..a16c2870ab6 100644 --- a/bundles.rst +++ b/bundles.rst @@ -18,7 +18,7 @@ SecurityBundle, DebugBundle, etc.) They are also used to add new features in your application via `third-party bundles`_. Bundles used in your applications must be enabled per -:doc:`environment ` in the ``config/bundles.php`` +:ref:`environment ` in the ``config/bundles.php`` file:: // config/bundles.php diff --git a/configuration.rst b/configuration.rst index a875db604c1..a695b1012e1 100644 --- a/configuration.rst +++ b/configuration.rst @@ -1,128 +1,147 @@ .. index:: single: Configuration -Configuring Symfony (and Environments) -====================================== +Configuring Symfony +=================== -Symfony applications can install third-party packages (bundles, libraries, etc.) -to bring in new features (:doc:`services `) to your project. -Each package can be customized via configuration files that live - by default - -in the ``config/`` directory. +Symfony applications are configured with the files stored in the ``config/`` +directory, which has this default structure: -Configuration: config/packages/ -------------------------------- +.. code-block:: text -The configuration for each package can be found in ``config/packages/``. For -instance, the framework bundle is configured in ``config/packages/framework.yaml``: + your-project/ + ├─ config/ + │ ├─ packages/ + │ ├─ bundles.php + │ ├─ routes.yaml + │ └─ services.yaml + ├─ ... -.. configuration-block:: +The ``routes.yaml`` file defines the :doc:`routing configuration `; +the ``services.yaml`` file configures the services of the +:doc:`service container `; the ``bundles.php`` file enables/ +disables packages in your application and is managed automatically by +:doc:`Symfony Flex `. - .. code-block:: yaml +You'll be working most in the ``config/packages/`` directory. This directory +stores the configuration of every package installed in your application. +Packages (also called "bundles" in Symfony and "plugins/modules" in other +projects) add ready-to-use features to your projects. - # config/packages/framework.yaml - framework: - secret: '%env(APP_SECRET)%' - #default_locale: en - #csrf_protection: true - #http_method_override: true +Most packages add a configuration file in ``config/packages/``. For example, +this is the default file for the "API Platform" package: - # Enables session support. Note that the session will ONLY be started if you read or write from it. - # Remove or comment this section to explicitly disable session support. - session: - handler_id: ~ +.. code-block:: yaml - #esi: true - #fragments: true - php_errors: - log: true + # config/packages/api_platform.yaml + api_platform: + mapping: + paths: ['%kernel.project_dir%/src/Entity'] - .. code-block:: xml +Splitting the configuration into lots of small files is intimidating for some +Symfony newcomers. However, you'll get used to them quickly and you rarely need +to change these files after package installation - - - - - - - - - - - - - - +.. tip:: - .. code-block:: php + To learn about all the available configuration options, check out the + :doc:`Symfony Configuration Reference ` or run the + ``config:dump-reference`` command. - // config/packages/framework.php - $container->loadFromExtension('framework', [ - 'secret' => '%env(APP_SECRET)%', - //'default_locale' => 'en', - //'csrf_protection' => true, - //'http_method_override' => true, - - // Enables session support. Note that the session will ONLY be started if you read or write from it. - // Remove or comment this section to explicitly disable session support. - 'session' => [ - 'handler_id' => null, - ], - //'esi' => true, - //'fragments' => true, - 'php_errors' => [ - 'log' => true, - ], - ]); +Configuration Formats +--------------------- -The top-level key (here ``framework``) references configuration for a specific -bundle (:doc:`FrameworkBundle ` in this case). +Unlike other frameworks, Symfony doesn't impose you a specific format to +configure your applications. Symfony lets you choose between YAML, XML and PHP +and throughout the Symfony documentation, all configuration examples will be +shown in these three formats. -.. sidebar:: Configuration Formats +There isn't any practical difference between formats. In fact, Symfony +transforms and caches all of them into PHP before running the application, so +there's not even any performance difference between them. - Throughout the documentation, all configuration examples will be shown in - three formats (YAML, XML and PHP). YAML is used by default, but you can - choose whatever you like best. There is no performance difference: +YAML is used by default when installing packages because it's concise and very +readable. These are the main advantages and disadvantages of each format: - * :doc:`/components/yaml/yaml_format`: Simple, clean and readable; - * *XML*: More powerful than YAML at times & supports IDE autocompletion; - * *PHP*: Very powerful but less readable than standard configuration formats. +* :doc:`YAML `: simple, clean and readable, but + requires using a dedicated parser; +* *XML*: supports IDE autocompletion/validation and is parsed natively by PHP, + but sometimes it generates too verbose configuration; +* *PHP*: very powerful and it allows to create dynamic configuration, but the + resulting configuration is less readable than the other formats. -Configuration Reference & Dumping ---------------------------------- +Importing Configuration Files +----------------------------- -There are *two* ways to know *what* keys you can configure: +Symfony loads configuration files using the :doc:`Config component +`, which provides advanced features such as importing +configuration files, even if they use a different format: -#. Use the :doc:`Reference Section `; -#. Use the ``config:dump-reference`` command. +.. configuration-block:: -For example, if you want to configure something related to the framework bundle, -you can see an example dump of all available configuration options by running: + .. code-block:: yaml -.. code-block:: terminal + # config/services.yaml + imports: + - { resource: 'legacy_config.php' } + # ignore_errors silently discards errors if the loaded file doesn't exist + - { resource: 'my_config_file.xml', ignore_errors: true } + # glob expressions are also supported to load multiple files + - { resource: '/etc/myapp/*.yaml' } - $ php bin/console config:dump-reference framework + # ... -.. index:: - single: Environments; Introduction + .. code-block:: xml -.. _page-creation-environments: -.. _page-creation-prod-cache-clear: + + + + + + + + + + + + + + + + .. code-block:: php + + // config/services.php + $loader->import('legacy_config.xml'); + // the third optional argument of import() is 'ignore_errors', which + // silently discards errors if the loaded file doesn't exist + $loader->import('my_config_file.yaml', null, true); + // glob expressions are also supported to load multiple files + $loader->import('/etc/myapp/*.yaml'); + + // ... + +.. tip:: + + If you use any other configuration format, you have to define your own loader + class extending it from :class:`Symfony\\Component\\DependencyInjection\\Loader\\FileLoader`. + In addition, you can define your own services to load configurations from + databases or web services. .. _config-parameter-intro: +.. _config-parameters-yml: -The parameters Key: Parameters (Variables) ------------------------------------------- +Configuration Parameters +------------------------ -The configuration has some special top-level keys. One of them is called -``parameters``: it's used to define *variables* that can be referenced in *any* -other configuration file. For example, when you install the *translation* -package, a ``locale`` parameter is added to ``config/services.yaml``: +Sometimes the same configuration value is used in several configuration files. +Instead of repeating it, you can define it as a "parameter", which is like a +reusable configuration value. By convention, parameters are defined under the +``parameters`` key in the ``config/services.yaml`` file: .. configuration-block:: @@ -130,7 +149,10 @@ package, a ``locale`` parameter is added to ``config/services.yaml``: # config/services.yaml parameters: - locale: en + # the parameter name is an arbitrary string (the 'app.' prefix is recommended + # to better differentiate your parameters from Symfony parameters). + # the parameter value can be any valid scalar (numbers, strings, booleans, arrays) + app.admin_email: 'something@example.com' # ... @@ -147,7 +169,10 @@ package, a ``locale`` parameter is added to ``config/services.yaml``: https://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> - en + + something@example.com @@ -156,26 +181,30 @@ package, a ``locale`` parameter is added to ``config/services.yaml``: .. code-block:: php // config/services.php - $container->setParameter('locale', 'en'); + // the parameter name is an arbitrary string (the 'app.' prefix is recommended + // to better differentiate your parameters from Symfony parameters). + // the parameter value can be any valid scalar (numbers, strings, booleans, arrays) + $container->setParameter('app.admin_email', 'something@example.com'); // ... -This parameter is then referenced in the framework config in -``config/packages/translation.yaml``: +Once defined, you can reference this parameter value from any other +configuration file using a special syntax: wrap the parameter name in two ``%`` +(e.g. ``%app.admin_email%``): .. configuration-block:: .. code-block:: yaml - # config/packages/translation.yaml - framework: + # config/packages/some_package.yaml + some_package: # any string surrounded by two % is replaced by that parameter value - default_locale: '%locale%' + email_address: '%app.admin_email%' # ... .. code-block:: xml - + - + - + .. code-block:: php - // config/packages/translation.php - $container->loadFromExtension('framework', [ + // config/packages/some_package.php + $container->loadFromExtension('some_package', [ // any string surrounded by two % is replaced by that parameter value - 'default_locale' => '%locale%', + 'email_address' => '%app.admin_email%', // ... ]); -You can define whatever parameter names you want under the ``parameters`` key of -any configuration file. To reference a parameter, surround its name with two -percent signs - e.g. ``%locale%``. +.. include:: /components/dependency_injection/_imports-parameters-note.rst.inc + +Configuration parameters are very common in Symfony applications. Some packages +even define their own parameters (e.g. when installing the translation package, +a new ``locale`` parameter is added to the ``config/services.yaml`` file). + +.. seealso:: + + Read the :ref:`service parameters ` article to + learn about how to use these configuration parameters in services and controllers. + +.. index:: + single: Environments; Introduction + +.. _page-creation-environments: +.. _page-creation-prod-cache-clear: +.. _configuration-environments: + +Configuration Environments +-------------------------- + +You have just one application, but whether you realize it or not, you need it +to behave differently at different times: + +* While **developing**, you want to log everything and expose nice debugging tools; +* After deploying to **production**, you want that same application to be + optimized for speed and only log errors. + +The files stored in ``config/packages/`` are used by Symfony to configure the +:doc:`application services `. In other words, you can change +the application behavior by changing which configuration files are loaded. +That's the idea of Symfony's **configuration environments**. + +A typical Symfony application begins with three environments: ``dev`` (for local +development), ``prod`` (for production servers) and ``test`` (for +:doc:`automated tests `). When running the application, Symfony loads +the configuration files in this order (the last files can override the values +set in the previous ones): + +#. ``config/packages/*.yaml`` (and ``.xml`` and ``*.php`` files too); +#. ``config/packages//*.yaml`` (and ``.xml`` and ``*.php`` files too); +#. ``config/packages/services.yaml`` (and ``services.xml`` and ``services.php`` files too); + +Take the ``framework`` package, installed by default, as an example: + +* First, ``config/packages/framework.yaml`` is loaded in all environments and + it configures the framework with some options; +* In the **prod** environment, nothing extra will be set as there is no + ``config/packages/prod/framework.yaml`` file; +* In the **dev** environment, there is no file either ( + ``config/packages/dev/framework.yaml`` does not exist). +* In the **test** environment, the ``config/packages/test/framework.yaml`` file + is loaded to override some of the settings previously configured in + ``config/packages/framework.yaml``. + +In reality, each environment differs only somewhat from others. This means that +all environments share a large base of common configurations, which is put in +files directly in the ``config/packages/`` directory. + +.. seealso:: + + See the ``configureContainer()`` method of + :doc:`the Kernel class ` to + learn everything about the loading order of configuration files. + +.. _selecting-the-active-environment: + +Selecting the Active Environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Symfony applications come with a file called ``.env`` located at the project +root directory. This file is used to define the value of environment variables +and it's explained in detail :ref:`later in this article `. + +Open the ``.env`` file and edit the value of the ``APP_ENV`` variable to change +the environment in which the application runs. For example, to run the +application in production: + +.. code-block:: bash + + # .env + APP_ENV=prod + +This value is used both for the web and for the console commands. However, you +can override it for commands by setting the ``APP_ENV`` value before running them: + +.. code-block:: terminal + + # Use the environment defined in the .env file + $ php bin/console command_name + + # Ignore the .env file and run this command in production + $ APP_ENV=prod php bin/console command_name + +.. deprecated:: 4.2 + + In previous Symfony versions you could configure the environment with the + ``--env`` command option, which was deprecated in Symfony 4.2. + +Creating a New Environment +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The default three environments provided by Symfony are enough for most projects, +but you can define your own environments too. For example, this is how you can +define a ``staging`` environment where the client can test the project before +going to production: + +#. Create a configuration directory with the same name as the environment (in + this case, ``config/packages/staging/``); +#. Add the needed configuration files in ``config/packages/staging/`` to + define the behavior of the new environment. Symfony loads first the files in + ``config/packages/*.yaml``, so you must only configure the differences with + those files; +#. Select the ``staging`` environment using the ``APP_ENV`` env var as explained + in the previous section. + +.. tip:: + + It's common for environments to be similar between each other, so you can + use `symbolic links`_ between ``config/packages//`` + directories to reuse the same configuration. + +.. _config-env-vars: + +Configuration Based on Environment Variables +-------------------------------------------- + +Using `environment variables`_ (or "env vars" for short) is a common practice to +configure options that depend on where the application is run (e.g. the database +credentials are usually different in production and in your local machine). + +Instead of defining those as regular options, you can define them as environment +variables and reference them in the configuration files using the special syntax +``%env(ENV_VAR_NAME)%``. The values of these options are resolved at runtime +(only once per request, to not impact performance). + +This example shows how to configure the database connection using an env var: + +.. configuration-block:: + + .. code-block:: yaml + + # config/packages/doctrine.yaml + doctrine: + dbal: + # by convention the env var names are always uppercase + url: '%env(DATABASE_URL)%' + # ... + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // config/packages/doctrine.php + $container->loadFromExtension('doctrine', [ + 'dbal' => [ + // by convention the env var names are always uppercase + 'url' => '%env(DATABASE_URL)%', + ] + ]); + +The next step is to define the value of those env vars in your shell, your web +server, etc. This is explained in the following sections, but to protect your +application from undefined env vars, you can give them a default value using the +``parameters`` key: + +.. configuration-block:: + + .. code-block:: yaml + + # config/services.yaml + parameters: + env(DATABASE_URL): 'sqlite:///%kernel.project_dir%/var/data.db' + + .. code-block:: xml + + + + + + + sqlite:///%kernel.project_dir%/var/data.db + + + + .. code-block:: php + + // config/services.php + $container->setParameter('env(DATABASE_URL)', 'sqlite:///%kernel.project_dir%/var/data.db'); .. seealso:: - You can also set parameters dynamically, like from environment variables. - See :doc:`/configuration/environment_variables`. + The values of env vars can only be strings, but Symfony includes some + :doc:`env var processors ` to transform + their contents (e.g. to turn a string value into an integer). -For more information about parameters - including how to reference them from inside -a controller - see :ref:`service-container-parameters`. +In order to define the actual values of env vars, Symfony proposes different +solutions depending if the application is running in production or in your local +development machine. +.. _configuration-env-var-in-dev: .. _config-dot-env: -.. _config-parameters-yml: -The .env File & Environment Variables -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Configuring Environment Variables in Development +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There is also a ``.env`` file which is loaded and its contents become environment -variables. This is useful during development, or if setting environment variables -is difficult for your deployment. +Instead of defining env vars in your shell or your web server, Symfony proposes +a convenient way of defining them in your local machine based on a file called +``.env`` (with a leading dot) located at the root of your project. -When you install packages, more environment variables are added to this file. But -you can also add your own. +The ``.env`` file is read and parsed on every request and its env vars are added +to the ``$_ENV`` PHP variable. The existing env vars are never overwritten by +the values defined in ``.env``, so you can combine both. -Environment variables can be referenced in any other configuration files by using -a special syntax. For example, if you install the ``doctrine`` package, then you -will have an environment variable called ``DATABASE_URL`` in your ``.env`` file. -This is referenced inside ``config/packages/doctrine.yaml``: +This is for example the content of the ``.env`` file to define the value of the +``DATABASE_URL`` env var shown earlier in this article: -.. code-block:: yaml +.. code-block:: bash + + # .env + DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name" + +In addition to your own env vars, this ``.env`` file also contains the env vars +defined by the third-party packages installed in your application (they are +added automatically by :doc:`Symfony Flex ` when installing packages). + +Managing Multiple .env Files +............................ - # config/packages/doctrine.yaml - doctrine: - dbal: - url: '%env(DATABASE_URL)%' +The ``.env`` file defines the default values for all env vars. However, it's +common to override some of those values depending on the environment (e.g. to +use a different database for tests) or depending on the machine (e.g. to use a +different OAuth token in your local machine while developing). - # The `resolve:` prefix replaces container params by their values inside the env variable: - # url: '%env(resolve:DATABASE_URL)%' +That's why you can define multiple ``.env`` files which override the default env +vars. These are the files in priority order (an env var found in one file +overrides the same env var for all the files below): -For more details about environment variables, see :ref:`config-env-vars`. +* ``.env..local`` (e.g. ``.env.test.local``): defines/overrides + env vars only for some environment and only in your local machine; +* ``.env.`` (e.g. ``.env.test``): defines/overrides env vars for + some environment and for all machines; +* ``.env.local``: defines/overrides env vars for all environments but only in + your local machine; +* ``.env``: defines the default value of env vars. + +The ``.env`` and ``.env.`` files should be committed to the shared +repository because they are the same for all developers. However, the +``.env.local`` and ``.env..local`` and files **should not be +committed** because only you will use them. In fact, the ``.gitignore`` file +that comes with Symfony prevents them from being committed. .. caution:: @@ -249,48 +507,65 @@ For more details about environment variables, see :ref:`config-env-vars`. involving a ``.env.dist`` file. For information about upgrading, see: :doc:`configuration/dot-env-changes`. -The ``.env`` file is special, because it defines the values that usually change -on each server. For example, the database credentials on your local development -machine might be different from your workmates. The ``.env`` file should contain -sensible, non-secret *default* values for all of your environment variables and -*should* be commited to your repository. +.. _configuration-env-var-in-prod: + +Configuring Environment Variables in Production +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In production, the ``.env`` files are also parsed and loaded on each request so +you can override the env vars already defined in the server. In order to improve +performance, you can run the ``dump-env`` command (available when using +:doc:`Symfony Flex ` 1.2 or later). + +This command parses all the ``.env`` files once and compiles their contents into +a new PHP-optimized file called ``.env.local.php``. From that moment, Symfony +will load the parsed file instead of parsing the ``.env`` files again: -To override these variables with machine-specific or sensitive values, create a -``.env.local`` file. This file is **not committed to the shared repository** and -is only stored on your machine. In fact, the ``.gitignore`` file that comes with -Symfony prevents it from being committed. +.. code-block:: terminal + + $ composer dump-env prod + +.. tip:: -You can also create a few other ``.env`` files that will be loaded: + Update your deployment tools/workflow to run the ``dump-env`` command after + each deploy to improve the application performance. + +.. caution:: -* ``.env.{environment}``: e.g. ``.env.test`` will be loaded in the ``test`` environment - and committed to your repository. + Beware that dumping the contents of the ``$_SERVER`` and ``$_ENV`` variables + or outputting the ``phpinfo()`` contents will display the values of the + environment variables, exposing sensitive information such as the database + credentials. -* ``.env.{environment}.local``: e.g. ``.env.prod.local`` will be loaded in the - ``prod`` environment but will *not* be committed to your repository. + The values of the env vars are also exposed in the web interface of the + :doc:`Symfony profiler `. In practice this shouldn't be a + problem because the web profiler must **never** be enabled in production. -If you decide to set real environment variables on production, the ``.env`` files -*are* still loaded, but your real environment variables will override those values. +Defining Environment Variables in the Web Server +................................................ -Environments & the Other Config Files -------------------------------------- +Using the ``.env`` files explained earlier is the recommended way of using env +vars in Symfony applications. However, you can also define env vars in the web +server configuration if you prefer that: -You have just *one* app, but whether you realize it or not, you need it to -behave *differently* at different times: +.. configuration-block:: + + .. code-block:: apache + + + # ... -* While **developing**, you want your app to log everything and expose nice - debugging tools; + SetEnv DATABASE_URL "mysql://db_user:db_password@127.0.0.1:3306/db_name" + -* After deploying to **production**, you want that *same* app to be optimized - for speed and only log errors. + .. code-block:: nginx -How can you make *one* application behave in two different ways? With -*environments*. + fastcgi_param DATABASE_URL "mysql://db_user:db_password@127.0.0.1:3306/db_name"; -You've probably already been using the ``dev`` environment without even knowing -it. After you deploy, you'll use the ``prod`` environment. +.. tip:: -To learn more about *how* to execute and control each environment, see -:doc:`/configuration/environments`. + SymfonyCloud, the cloud service optimized for Symfony applications, defines + some `utilities to manage env vars`_ in production. Keep Going! ----------- @@ -316,4 +591,6 @@ Learn more configuration/* -.. _`Incenteev Parameter Handler`: https://github.com/Incenteev/ParameterHandler +.. _`environment variables`: https://en.wikipedia.org/wiki/Environment_variable +.. _`symbolic links`: https://en.wikipedia.org/wiki/Symbolic_link +.. _`utilities to manage env vars`: https://symfony.com/doc/master/cloud/cookbooks/env.html diff --git a/configuration/configuration_organization.rst b/configuration/configuration_organization.rst deleted file mode 100644 index 5fe86fe290d..00000000000 --- a/configuration/configuration_organization.rst +++ /dev/null @@ -1,182 +0,0 @@ -.. index:: - single: Configuration - -How to Organize Configuration Files -=================================== - -The Symfony skeleton defines three :doc:`execution environments ` -called ``dev``, ``prod`` and ``test``. An environment represents a way -to execute the same codebase with different configurations. - -In order to select the configuration file to load for each environment, Symfony -executes the ``configureContainer()`` method of the ``Kernel`` class:: - - // src/Kernel.php - use Symfony\Component\Config\Loader\LoaderInterface; - use Symfony\Component\DependencyInjection\ContainerBuilder; - use Symfony\Component\HttpKernel\Kernel as BaseKernel; - - class Kernel extends BaseKernel - { - const CONFIG_EXTS = '.{php,xml,yaml,yml}'; - - // ... - - public function configureContainer(ContainerBuilder $container, LoaderInterface $loader) - { - $confDir = $this->getProjectDir().'/config'; - $loader->load($confDir.'/packages/*'.self::CONFIG_EXTS, 'glob'); - if (is_dir($confDir.'/packages/'.$this->environment)) { - $loader->load($confDir.'/packages/'.$this->environment.'/**/*'.self::CONFIG_EXTS, 'glob'); - } - $loader->load($confDir.'/services'.self::CONFIG_EXTS, 'glob'); - $loader->load($confDir.'/services_'.$this->environment.self::CONFIG_EXTS, 'glob'); - } - } - -For the ``dev`` environment, Symfony loads the following config files and -directories and in this order: - -#. ``config/packages/*`` -#. ``config/packages/dev/*`` -#. ``config/services.yaml`` -#. ``config/services_dev.yaml`` - -Therefore, the configuration files of the default Symfony applications follow -this structure: - -.. code-block:: text - - your-project/ - ├─ config/ - │ ├─ packages/ - │ │ ├─ dev/ - │ │ │ ├─ framework.yaml - │ │ │ └─ ... - │ │ ├─ prod/ - │ │ │ └─ ... - │ │ ├─ test/ - │ │ │ └─ ... - │ │ ├─ framework.yaml - │ │ └─ ... - │ ├─ services.yaml - │ └─ services_dev.yaml - ├─ ... - -This default structure was chosen for its simplicity — one file per package and -environment. But as any other Symfony feature, you can customize it to better -suit your needs. - -Advanced Techniques -------------------- - -Symfony loads configuration files using the -:doc:`Config component `, which provides some -advanced features. - -Mix and Match Configuration Formats -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Configuration files can import files defined with any other built-in configuration -format (``.yaml``, ``.xml``, ``.php``, ``.ini``): - -.. configuration-block:: - - .. code-block:: yaml - - # config/services.yaml - imports: - - { resource: 'my_config_file.xml' } - - { resource: 'legacy.php' } - - # ... - - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php - - // config/services.php - $loader->import('my_config_file.yaml'); - $loader->import('legacy.xml'); - - // ... - -If you use any other configuration format, you have to define your own loader -class extending it from :class:`Symfony\\Component\\DependencyInjection\\Loader\\FileLoader`. -When the configuration values are dynamic, you can use the PHP configuration -file to execute your own logic. In addition, you can define your own services -to load configurations from databases or web services. - -.. include:: /components/dependency_injection/_imports-parameters-note.rst.inc - -Global Configuration Files -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some system administrators may prefer to store sensitive parameters in files -outside the project directory. Imagine that the database credentials for your -website are stored in the ``/etc/sites/mysite.com/parameters.yaml`` file. You -can load files from outside the project folder by indicating the full file path -when importing it from any other configuration file: - -.. configuration-block:: - - .. code-block:: yaml - - # config/services.yaml - imports: - - { resource: '/etc/sites/mysite.com/parameters.yaml', ignore_errors: true } - - # ... - - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php - - // config/services.php - $loader->import('/etc/sites/mysite.com/parameters.yaml', null, true); - - // ... - -.. tip:: - - The ``ignore_errors`` option (which is the third optional argument in the - loader's ``import()`` method) silently discards errors when the loaded file - doesn't exist. This is needed in this case because most of the time, local - developers won't have the same files that exist on the production servers. - -As you've seen, there are lots of ways to organize your configuration files. You -can choose one of these or even create your own custom way of organizing the -files. For even more customization, see ":doc:`/configuration/override_dir_structure`". diff --git a/configuration/environment_variables.rst b/configuration/env_var_processors.rst similarity index 71% rename from configuration/environment_variables.rst rename to configuration/env_var_processors.rst index 2fc75dcc3d7..fb54a11ecce 100644 --- a/configuration/environment_variables.rst +++ b/configuration/env_var_processors.rst @@ -1,145 +1,18 @@ .. index:: - single: Environment Variables; env vars - -How to Configure Symfony With Environment Variables -=================================================== - -In :doc:`/configuration`, you learned how to manage your application -configuration. In this article you'll learn how to use environment variables (or -"env vars" for short) to configure some of those options, which is a common -practice to configure sensitive options such as credentials and passwords. - -.. _config-env-vars: - -Referencing Env Vars in Configuration Files -------------------------------------------- - -First, define the value of the env var, using your shell environment or the -``.env`` file at the project root directory. For example, consider the -``DATABASE_URL`` env var defined when installing the ``doctrine`` recipe (by -convention the env var names are always uppercase): - -.. code-block:: bash - - # .env - DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name" - -Then, you can reference those env vars in any configuration option enclosing -their names with ``env()``. Their actual values will be resolved at runtime -(once per request), so that dumped containers can be reconfigured dynamically -even after being compiled: - -.. configuration-block:: - - .. code-block:: yaml - - # config/packages/doctrine.yaml - doctrine: - dbal: - url: '%env(DATABASE_URL)%' - # ... - - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php - - // config/packages/doctrine.php - $container->loadFromExtension('doctrine', [ - 'dbal' => [ - 'url' => '%env(DATABASE_URL)%', - ] - ]); - -You can also give the ``env()`` parameters a default value, which will be used -whenever the corresponding environment variable is *not* found: - -.. configuration-block:: - - .. code-block:: yaml - - # config/services.yaml - parameters: - env(DATABASE_HOST): localhost - - .. code-block:: xml - - - - - - - localhost - - - - .. code-block:: php - - // config/services.php - $container->setParameter('env(DATABASE_HOST)', 'localhost'); - -.. _configuration-env-var-in-prod: - -Configuring Environment Variables in Production ------------------------------------------------ - -During development, you'll use the ``.env`` file to configure your environment -variables. On your production server, it is recommended to configure these at -the web server level. If you're using Apache or Nginx, you can use e.g. one of -the following: - -.. configuration-block:: - - .. code-block:: apache - - - # ... - - SetEnv DATABASE_URL "mysql://db_user:db_password@127.0.0.1:3306/db_name" - - - .. code-block:: nginx - - fastcgi_param DATABASE_URL "mysql://db_user:db_password@127.0.0.1:3306/db_name"; - -.. caution:: - - Beware that dumping the contents of the ``$_SERVER`` and ``$_ENV`` variables - or outputting the ``phpinfo()`` contents will display the values of the - environment variables, exposing sensitive information such as the database - credentials. - - The values of the env vars are also exposed in the web interface of the - :doc:`Symfony profiler `. In practice this shouldn't be a - problem because the web profiler must **never** be enabled in production. + single: Environment Variable Processors; env vars Environment Variable Processors -------------------------------- +=============================== -The values of environment variables are considered strings by default. -However, your code may expect other data types, like integers or booleans. -Symfony solves this problem with *processors*, which modify the contents of the -given environment variables. The following example uses the integer processor to -turn the value of the ``HTTP_PORT`` env var into an integer: +:ref:`Using env vars to configure Symfony applications ` is a +common practice to hide sensitive configuration (e.g. database credentials) and +to make your applications truly dynamic. + +The main issue of env vars is that their values can only be strings and your +application may need other data types (integer, boolean, etc.). Symfony solves +this problem with "env var processors", which transform the original contents of +the given environment variables. The following example uses the integer +processor to turn the value of the ``HTTP_PORT`` env var into an integer: .. configuration-block:: @@ -176,6 +49,9 @@ turn the value of the ``HTTP_PORT`` env var into an integer: ], ]); +Built-In Environment Variable Processors +---------------------------------------- + Symfony provides the following env var processors: ``env(string:FOO)`` @@ -500,7 +376,7 @@ It is also possible to combine any number of processors: auth: '%env(json:file:resolve:AUTH_FILE)%' Custom Environment Variable Processors -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------------- It's also possible to add your own processors for environment variables. First, create a class that implements @@ -530,29 +406,3 @@ 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 `, this is already done for you, thanks to :ref:`autoconfiguration `. - -Constants ---------- - -The container also has support for setting PHP constants as parameters. -See :ref:`component-di-parameters-constants` for more details. - -Miscellaneous Configuration ---------------------------- - -You can mix whatever configuration format you like (YAML, XML and PHP) in -``config/packages/``. Importing a PHP file gives you the flexibility to add -whatever is needed in the container. For instance, you can create a -``drupal.php`` file in which you set a database URL based on Drupal's database -configuration:: - - // config/packages/drupal.php - - // import Drupal's configuration - include_once('/path/to/drupal/sites/default/settings.php'); - - // set a app.database_url parameter - $container->setParameter('app.database_url', $db_url); - -.. _`SetEnv`: http://httpd.apache.org/docs/current/env.html -.. _`fastcgi_param`: http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_param diff --git a/configuration/environments.rst b/configuration/environments.rst deleted file mode 100644 index 0efac1eb899..00000000000 --- a/configuration/environments.rst +++ /dev/null @@ -1,364 +0,0 @@ -.. index:: - single: Environments - -How to Master and Create new Environments -========================================= - -Every application is the combination of code and a set of configuration that -dictates how that code should function. The configuration may define the database -being used, if something should be cached or how verbose logging should be. - -In Symfony, the idea of "environments" is that the same codebase can be run using -multiple different configurations. For example, the ``dev`` environment should use -configuration that makes development comfortable and friendly, while the ``prod`` -environment should use a set of configuration optimized for speed and security. - -.. index:: - single: Environments; Configuration files - -Different Environments, different Configuration Files ------------------------------------------------------ - -A typical Symfony application begins with three environments: ``dev``, -``prod`` and ``test``. As mentioned, each environment represents a way to -execute the same codebase with different configuration. It should be no -surprise then that each environment loads its own individual configuration -files. These different files are organized by environment: - -* for the ``dev`` environment: ``config/packages/dev/`` -* for the ``prod`` environment: ``config/packages/prod/`` -* for the ``test`` environment: ``config/packages/test/`` - -In reality, each environment differs only somewhat from others. This means that -all environments share a large base of common configurations. This configuration -is put in files directly in the ``config/packages/`` directory. - -The location of these files is defined by the application's kernel:: - - // src/Kernel.php - - // ... - class Kernel extends BaseKernel - { - // ... - - protected function configureContainer(ContainerBuilder $container, LoaderInterface $loader) - { - // ... - $confDir = $this->getProjectDir().'/config'; - - // always load all files in /config/packages/ - $loader->load($confDir.'/packages/*'.self::CONFIG_EXTS, 'glob'); - - // then, if available, load the files in the specific environment directory - if (is_dir($confDir.'/packages/'.$this->environment)) { - $loader->load($confDir.'/packages/'.$this->environment.'/**/*'.self::CONFIG_EXTS, 'glob'); - } - - // load a special services.(yaml/xml/php) and, if available, services_ENVIRONMENT.(yaml/xml/php) file - $loader->load($confDir.'/services'.self::CONFIG_EXTS, 'glob'); - $loader->load($confDir.'/services_'.$this->environment.self::CONFIG_EXTS, 'glob'); - } - } - -Take the framework package, installed by default, as an example: - -* Loaded in all environments, ``config/packages/framework.yaml`` configures the - framework with some ``secret`` setting; -* In the **prod** environment, nothing extra will be set as there is no - ``config/packages/prod/`` directory; -* The same applies to **dev**, as there is no - ``config/packages/dev/framework.yaml``. There are however other packages (e.g. - ``routing.yaml``) with special dev settings; -* At last, during the **test** environment, the framework's test features are - enabled in ``config/packages/test/framework.yaml``. - -.. index:: - single: Environments; Executing different environments - -Executing an Application in different Environments --------------------------------------------------- - -To execute the application in each environment, change the ``APP_ENV`` -environment variable. During development, this is done in ``.env`` or in ``.env.local``: - -.. code-block:: bash - - # .env or .env.local - APP_ENV=dev - - # or for test: - #APP_ENV=test - -Visit the ``http://localhost:8000/index.php`` page in your web browser to see -your application in the configured environment. - -.. tip:: - - In production, you can use real environment variables via - your :ref:`web server configuration `. - -.. note:: - - The given URLs assume that your web server is configured to use the ``public/`` - directory of the application as its root. Read more in :doc:`Installing Symfony `. - -If you open the file you just visited (``public/index.php``), you'll see that -the environment variable is passed to the kernel:: - - // public/index.php - - // ... - $kernel = new Kernel($_SERVER['APP_ENV'], $_SERVER['APP_DEBUG']); - - // ... - -.. note:: - - The ``test`` environment is used when writing functional tests and is - usually not accessed in the browser directly via a front controller. - -.. index:: - single: Configuration; Debug mode - -.. sidebar:: *Debug* Mode - - Important, but unrelated to the topic of *environments* is the second - argument to the ``Kernel`` constructor. This specifies if the application - should run in "debug mode". Regardless of the environment, a Symfony - application can be run with debug mode set to ``true`` or ``false`` - (respectively ``1`` or ``0`` for the ``APP_DEBUG`` variable defined in - ``.env``). This affects many things in the application, such as displaying - stacktraces on error pages or if cache files are dynamically rebuilt on - each request. Though not a requirement, debug mode is generally set to - ``true`` for the ``dev`` and ``test`` environments and ``false`` for the - ``prod`` environment. - - Internally, the value of the debug mode becomes the ``kernel.debug`` - parameter used inside the :doc:`service container `. - If you look inside the application configuration file, you'll see the - parameter used, for example, to turn Twig's debug mode on: - - .. configuration-block:: - - .. code-block:: yaml - - # config/packages/twig.yaml - twig: - debug: '%kernel.debug%' - - .. code-block:: xml - - - - - - - - - .. code-block:: php - - $container->loadFromExtension('twig', [ - 'debug' => '%kernel.debug%', - // ... - ]); - -Selecting the Environment for Console Commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, Symfony commands are executed in whatever environment is defined by -the ``APP_ENV`` environment variable (usually configured in your ``.env`` file). -In previous Symfony versions you could use the ``--env`` (and ``--no-debug``) -command line options to override this value. However, those options were -deprecated in Symfony 4.2. - -Use the ``APP_ENV`` (and ``APP_DEBUG``) environment variables to change the -environment and the debug behavior of the commands: - -.. code-block:: terminal - - # Symfony's default: 'dev' environment and debug enabled - $ php bin/console command_name - - # 'prod' environment (debug is always disabled for 'prod') - $ APP_ENV=prod php bin/console command_name - - # 'test' environment and debug disabled - $ APP_ENV=test APP_DEBUG=0 php bin/console command_name - -.. index:: - single: Environments; Creating a new environment - -Creating a new Environment --------------------------- - -Since an environment is nothing more than a string that corresponds to a set of -configuration, you can also create your own environments for specific purposes. - -Suppose, for example, that before deployment, you need to benchmark your -application. One way to benchmark the application is to use near-production -settings, but with Symfony's ``web_profiler`` enabled. This allows Symfony -to record information about your application while benchmarking. - -The best way to accomplish this is via a new environment called, for example, -``benchmark``. Start by creating a new configuration directory and a -configuration file: - -.. configuration-block:: - - .. code-block:: yaml - - # config/packages/benchmark/web_profiler.yaml - framework: - profiler: { only_exceptions: false } - - .. code-block:: xml - - - - - - - - - - - - .. code-block:: php - - // config/packages/benchmark/web_profiler.php - $container->loadFromExtension('framework', [ - 'profiler' => ['only_exceptions' => false], - ]); - -And... you're finished! The application now supports a new environment called -``benchmark``. - -Change the ``APP_ENV`` variable to ``benchmark`` to be able to access the new -environment through your browser: - -.. code-block:: bash - - # .env or .env.local - APP_ENV=benchmark - -.. sidebar:: Importing configuration - - Besides loading files in the Kernel, you can also import files in the - configuration directly. For instance, to make sure the benchmark - environment is identical to the prod environment, you might want to load - all its configuration as well. - - You can achieve this by using a special ``imports`` key: - - .. configuration-block:: - - .. code-block:: yaml - - # config/packages/benchmark/other.yaml - imports: - - { resource: '../prod/' } - - # other resources are possible as well, like importing other - # files or using globs: - #- { resource: '/etc/myapp/some_special_config.xml' } - #- { resource: '/etc/myapp/*.yaml' } - - .. code-block:: xml - - - - - - - - - - - - - - .. code-block:: php - - // config/packages/benchmark/other.php - $loader->import('../prod/'); - - // other resources are possible as well, like importing other - // files or using globs: - //$loader->import('/etc/myapp/some_special_config.yaml'); - //$loader->import('/etc/myapp/*.php'); - -.. index:: - single: Environments; Cache directory - -Environments and the Cache Directory ------------------------------------- - -Symfony takes advantage of caching in many ways: the application configuration, -routing configuration, Twig templates and more are cached to PHP objects -stored in files on the filesystem. - -By default, these cached files are largely stored in the ``var/cache/`` directory. -However, each environment caches its own set of files: - -.. code-block:: text - - your-project/ - ├─ var/ - │ ├─ cache/ - │ │ ├─ dev/ # cache directory for the *dev* environment - │ │ └─ prod/ # cache directory for the *prod* environment - │ ├─ ... - -Sometimes, when debugging, it may be helpful to inspect a cached file to -understand how something is working. When doing so, remember to look in -the directory of the environment you're using (most commonly ``dev/`` while -developing and debugging). While it can vary, the ``var/cache/dev/`` directory -includes the following: - -``appDevDebugProjectContainer.php`` - The cached "service container" that represents the cached application - configuration. - -``appDevUrlGenerator.php`` - The PHP class generated from the routing configuration and used when - generating URLs. - -``appDevUrlMatcher.php`` - The PHP class used for route matching - look here to see the compiled regular - expression logic used to match incoming URLs to different routes. - -``twig/`` - This directory contains all the cached Twig templates. - -.. note:: - - You can change the directory location and name. For more information - read the article :doc:`/configuration/override_dir_structure`. - -Going further -------------- - -Read the article on :doc:`/configuration/environment_variables`. diff --git a/configuration/front_controllers_and_kernel.rst b/configuration/front_controllers_and_kernel.rst index a0127c34494..865a4077157 100644 --- a/configuration/front_controllers_and_kernel.rst +++ b/configuration/front_controllers_and_kernel.rst @@ -5,11 +5,11 @@ Understanding how the Front Controller, Kernel and Environments Work together ============================================================================= -The section :doc:`/configuration/environments` explained the basics on how -Symfony uses environments to run your application with different configuration -settings. This section will explain a bit more in-depth what happens when your -application is bootstrapped. To hook into this process, you need to understand -three parts that work together: +The :ref:`configuration environments ` section +explained the basics on how Symfony uses environments to run your application +with different configuration settings. This section will explain a bit more +in-depth what happens when your application is bootstrapped. To hook into this +process, you need to understand three parts that work together: * `The Front Controller`_ * `The Kernel Class`_ @@ -120,6 +120,82 @@ new kernel. But odds are high that you don't need to change things like this on the fly by having several ``Kernel`` implementations. +.. index:: + single: Configuration; Debug mode + +Debug Mode +~~~~~~~~~~ + +The second argument to the ``Kernel`` constructor specifies if the application +should run in "debug mode". Regardless of the +:ref:`configuration environment `, a Symfony +application can be run with debug mode set to ``true`` or ``false``. + +This affects many things in the application, such as displaying stacktraces on +error pages or if cache files are dynamically rebuilt on each request. Though +not a requirement, debug mode is generally set to ``true`` for the ``dev`` and +``test`` environments and ``false`` for the ``prod`` environment. + +Similar to :ref:`configuring the environment ` +you can also enable/disable the debug mode using :ref:`the .env file `: + +.. code-block:: bash + + # .env + # set it to 1 to enable the debug mode + APP_DEBUG=0 + +This value can be overridden for commands by passing the ``APP_DEBUG`` value +before running them: + +.. code-block:: terminal + + # Use the debug mode defined in the .env file + $ php bin/console command_name + + # Ignore the .env file and enable the debug mode for this command + $ APP_DEBUG=1 php bin/console command_name + +.. deprecated:: 4.2 + + In previous Symfony versions you could configure the debug mode with the + ``--no-debug`` command option, which was deprecated in Symfony 4.2. + +Internally, the value of the debug mode becomes the ``kernel.debug`` +parameter used inside the :doc:`service container `. +If you look inside the application configuration file, you'll see the +parameter used, for example, to turn Twig's debug mode on: + +.. configuration-block:: + + .. code-block:: yaml + + # config/packages/twig.yaml + twig: + debug: '%kernel.debug%' + + .. code-block:: xml + + + + + + + + + .. code-block:: php + + $container->loadFromExtension('twig', [ + 'debug' => '%kernel.debug%', + // ... + ]); + The Environments ---------------- @@ -128,9 +204,9 @@ As mentioned above, the ``Kernel`` has to implement another method - This method is responsible for loading the application's configuration from the right *environment*. -Environments have been covered extensively :doc:`in the previous article -`, and you probably remember that the Symfony uses -by default three of them - ``dev``, ``prod`` and ``test``. +:ref:`Configuration environments ` allow to execute +the same code using different configuration. Symfony provides three environments +by default called ``dev``, ``prod`` and ``test``. More technically, these names are nothing more than strings passed from the front controller to the ``Kernel``'s constructor. This name can then be used in @@ -141,5 +217,53 @@ config files found on ``config/packages/*`` and then, the files found on ``config/packages/ENVIRONMENT_NAME/``. You are free to implement this method differently if you need a more sophisticated way of loading your configuration. -.. _front controller: https://en.wikipedia.org/wiki/Front_Controller_pattern -.. _decorate: https://en.wikipedia.org/wiki/Decorator_pattern +.. index:: + single: Environments; Cache directory + +Environments and the Cache Directory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Symfony takes advantage of caching in many ways: the application configuration, +routing configuration, Twig templates and more are cached to PHP objects +stored in files on the filesystem. + +By default, these cached files are largely stored in the ``var/cache/`` directory. +However, each environment caches its own set of files: + +.. code-block:: text + + your-project/ + ├─ var/ + │ ├─ cache/ + │ │ ├─ dev/ # cache directory for the *dev* environment + │ │ └─ prod/ # cache directory for the *prod* environment + │ ├─ ... + +Sometimes, when debugging, it may be helpful to inspect a cached file to +understand how something is working. When doing so, remember to look in +the directory of the environment you're using (most commonly ``dev/`` while +developing and debugging). While it can vary, the ``var/cache/dev/`` directory +includes the following: + +``appDevDebugProjectContainer.php`` + The cached "service container" that represents the cached application + configuration. + +``appDevUrlGenerator.php`` + The PHP class generated from the routing configuration and used when + generating URLs. + +``appDevUrlMatcher.php`` + The PHP class used for route matching - look here to see the compiled regular + expression logic used to match incoming URLs to different routes. + +``twig/`` + This directory contains all the cached Twig templates. + +.. note:: + + You can change the cache directory location and name. For more information + read the article :doc:`/configuration/override_dir_structure`. + +.. _`front controller`: https://en.wikipedia.org/wiki/Front_Controller_pattern +.. _`decorate`: https://en.wikipedia.org/wiki/Decorator_pattern diff --git a/configuration/multiple_kernels.rst b/configuration/multiple_kernels.rst index 7cad1df7863..235305ce090 100644 --- a/configuration/multiple_kernels.rst +++ b/configuration/multiple_kernels.rst @@ -16,7 +16,7 @@ request to generate the response. This single kernel approach is a convenient default, but Symfony applications can define any number of kernels. Whereas -:doc:`environments ` execute the same application +:ref:`environments ` execute the same application with different configurations, kernels can execute different parts of the same application. diff --git a/configuration/override_dir_structure.rst b/configuration/override_dir_structure.rst index 0d312de3826..fbfa119cc14 100644 --- a/configuration/override_dir_structure.rst +++ b/configuration/override_dir_structure.rst @@ -4,9 +4,8 @@ How to Override Symfony's default Directory Structure ===================================================== -Symfony automatically ships with a default directory structure. You can -override this directory structure to create your own. The default -directory structure is: +Symfony applications have the following default directory structure, but you can +override it to create your own structure: .. code-block:: text @@ -28,10 +27,19 @@ directory structure is: │ └─ ... └─ vendor/ +.. _override-config-dir: + +Override the Configuration Directory +------------------------------------ + +The configuration directory is the only one which cannot be overridden in a +Symfony application. Its location is hardcoded as the ``config/`` directory +at your project root directory. + .. _override-cache-dir: -Override the ``cache`` Directory --------------------------------- +Override the Cache Directory +---------------------------- You can change the default cache directory by overriding the ``getCacheDir()`` method in the ``Kernel`` class of your application:: @@ -51,21 +59,21 @@ method in the ``Kernel`` class of your application:: In this code, ``$this->environment`` is the current environment (i.e. ``dev``). In this case you have changed the location of the cache directory to -``var/{environment}/cache``. +``var/{environment}/cache/``. .. caution:: - You should keep the ``cache`` directory different for each environment, + You should keep the cache directory different for each environment, otherwise some unexpected behavior may happen. Each environment generates its own cached configuration files, and so each needs its own directory to store those cache files. .. _override-logs-dir: -Override the ``logs`` Directory -------------------------------- +Override the Log Directory +-------------------------- -Overriding the ``logs`` directory is the same as overriding the ``cache`` +Overriding the ``var/log/`` directory is the same as overriding the ``var/cache/`` directory. The only difference is that you need to override the ``getLogDir()`` method:: @@ -82,7 +90,7 @@ method:: } } -Here you have changed the location of the directory to ``var/{environment}/log``. +Here you have changed the location of the directory to ``var/{environment}/log/``. .. _override-templates-dir: @@ -180,19 +188,19 @@ configuration option to define your own translations directory (or directories): .. _override-web-dir: .. _override-the-web-directory: -Override the ``public`` Directory ---------------------------------- +Override the Public Directory +----------------------------- -If you need to rename or move your ``public`` directory, the only thing you need -to guarantee is that the path to the ``var`` directory is still correct in your -``index.php`` front controller. If you renamed the directory, you're -fine. But if you moved it in some way, you may need to modify these paths inside -those files:: +If you need to rename or move your ``public/`` directory, the only thing you +need to guarantee is that the path to the ``var/`` directory is still correct in +your ``index.php`` front controller. If you renamed the directory, you're fine. +But if you moved it in some way, you may need to modify these paths inside those +files:: require_once __DIR__.'/../path/to/vendor/autoload.php'; -You also need to change the ``extra.public-dir`` option in the -``composer.json`` file: +You also need to change the ``extra.public-dir`` option in the ``composer.json`` +file: .. code-block:: json @@ -206,17 +214,17 @@ You also need to change the ``extra.public-dir`` option in the .. tip:: - Some shared hosts have a ``public_html`` web directory root. Renaming - your web directory from ``public`` to ``public_html`` is one way to make + Some shared hosts have a ``public_html/`` web directory root. Renaming + your web directory from ``public/`` to ``public_html/`` is one way to make your Symfony project work on your shared host. Another way is to deploy your application to a directory outside of your web root, delete your - ``public_html`` directory, and then replace it with a symbolic link to - the ``public`` dir in your project. + ``public_html/`` directory, and then replace it with a symbolic link to + the ``public/`` dir in your project. -Override the ``vendor`` Directory ---------------------------------- +Override the Vendor Directory +----------------------------- -To override the ``vendor`` directory, you need to define the ``vendor-dir`` +To override the ``vendor/`` directory, you need to define the ``vendor-dir`` option in your ``composer.json`` file like this: .. code-block:: json @@ -230,6 +238,6 @@ option in your ``composer.json`` file like this: .. tip:: - This modification can be of interest if you are working in a virtual environment - and cannot use NFS - for example, if you're running a Symfony application using - Vagrant/VirtualBox in a guest operating system. + This modification can be of interest if you are working in a virtual + environment and cannot use NFS - for example, if you're running a Symfony + application using Vagrant/VirtualBox in a guest operating system. diff --git a/controller/error_pages.rst b/controller/error_pages.rst index 06e1251b00c..989938bcd5b 100644 --- a/controller/error_pages.rst +++ b/controller/error_pages.rst @@ -17,7 +17,7 @@ customize error pages, so run this command to make sure the bundle is installed: $ composer require twig -In the :doc:`development environment `, +In the :ref:`development environment `, Symfony catches all the exceptions and displays a special **exception page** with lots of debug information to help you discover the root problem: diff --git a/doctrine/pdo_session_storage.rst b/doctrine/pdo_session_storage.rst index 0dd065d10d6..81fbbd2fead 100644 --- a/doctrine/pdo_session_storage.rst +++ b/doctrine/pdo_session_storage.rst @@ -69,7 +69,7 @@ To use it, first register a new handler service: .. tip:: Configure the database credentials - :doc:`using environment variables in the config file ` + :ref:`using environment variables in the config file ` to make your application more secure. Next, tell Symfony to use your service as the session handler: diff --git a/reference/configuration/kernel.rst b/reference/configuration/kernel.rst index 2081ba5ffad..08413ef59aa 100644 --- a/reference/configuration/kernel.rst +++ b/reference/configuration/kernel.rst @@ -109,7 +109,7 @@ Cache Directory This returns the absolute path of the cache directory of your Symfony project. It's calculated automatically based on the current -:doc:`environment `. +:ref:`environment `. This value is exposed via the ``kernel.cache_dir`` configuration parameter and the :method:`Symfony\\Component\\HttpKernel\\Kernel::getCacheDir` method. To @@ -123,7 +123,7 @@ Log Directory This returns the absolute path of the log directory of your Symfony project. It's calculated automatically based on the current -:doc:`environment `. +:ref:`environment `. This value is exposed via the ``kernel.log_dir`` configuration parameter and the :method:`Symfony\\Component\\HttpKernel\\Kernel::getLogDir` method. To diff --git a/reference/configuration/swiftmailer.rst b/reference/configuration/swiftmailer.rst index d53935b8d59..977c834e14f 100644 --- a/reference/configuration/swiftmailer.rst +++ b/reference/configuration/swiftmailer.rst @@ -256,7 +256,7 @@ the information will be available in the profiler. The following options can be set via environment variables: ``url``, ``transport``, ``username``, ``password``, ``host``, ``port``, ``timeout``, ``source_ip``, ``local_domain``, ``encryption``, ``auth_mode``. For details, - see: :doc:`/configuration/environment_variables`. + see: :ref:`config-env-vars`. Using Multiple Mailers ---------------------- diff --git a/service_container/parameters.rst b/service_container/parameters.rst index 48dbac2c83c..c1c7d570447 100644 --- a/service_container/parameters.rst +++ b/service_container/parameters.rst @@ -245,7 +245,7 @@ for all parameters that are arrays. Environment Variables and Dynamic Values ---------------------------------------- -See :doc:`/configuration/environment_variables`. +See :ref:`config-env-vars`. .. _component-di-parameters-constants: diff --git a/setup/upgrade_major.rst b/setup/upgrade_major.rst index b8c00234fc8..83e1b41b583 100644 --- a/setup/upgrade_major.rst +++ b/setup/upgrade_major.rst @@ -37,7 +37,7 @@ using these deprecated features in the last version before the major (e.g. To help you with this, deprecation notices are triggered whenever you end up using a deprecated feature. When visiting your application in the -:doc:`dev environment ` +:ref:`dev environment ` in your browser, these notices are shown in the web dev toolbar: .. image:: /_images/install/deprecations-in-profiler.png