ARTICLE

Magento 2 config.php vs env.php: app:config:dump, config:set –lock-env, and Pipeline Deployment

Magento 2 config.php vs env.php: app:config:dump, config:set --lock-env, and Pipeline Deployment

In Magento 2, app/etc/config.php holds settings shared by every environment: the module list, stores, themes, and non-sensitive configuration. It belongs in git. app/etc/env.php holds what is unique to one server, such as database credentials, cache hosts, the crypt key, and sensitive values. It stays out of git. Environment variables override both files.

That one sentence answers the basic question, but most teams get into trouble in the details. A setting dumped to the wrong file gets committed with production credentials. A value locked in config.php can no longer be changed in the Admin, and nobody remembers why. A deploy runs app:config:import on a server where env.php is out of date and the storefront comes up with the wrong base URL. This guide walks through how the two files actually divide the work, what each CLI command writes and where, and a pipeline you can run on any Magento or Adobe Commerce build.

What lives in config.php and what lives in env.php

Both files are created at install time and together make up what Adobe calls the deployment configuration. The application will not boot without them. They are plain PHP files that return an array, and they are read before the database is ever touched.

config.php is the shared file. According to Adobe’s deployment technical details, it contains shared settings that exclude sensitive and system-specific values: websites, stores, store views, and settings such as non-sensitive payment options. It also contains the modules array, where each module has a value of 1 (enabled) or 0 (disabled), plus the installed themes and language packages. Since Magento 2.2, config.php is no longer listed in the default .gitignore, precisely so it can travel through source control.

env.php is the environment file. It holds the settings that differ between your laptop, staging, and production. The top-level keys you will see in most projects:

  • backend with frontName, the Admin URL path
  • db for database connections, and resource for mapping resources to those connections
  • crypt with the encryption key used for passwords and encrypted config values
  • cache and session for Redis or Valkey hosts, ports, and databases
  • cache_types for which cache types are on or off
  • queue for RabbitMQ or another broker, including consumers_wait_for_messages
  • MAGE_MODE for developer, default, or production mode
  • lock, cron, downloadable_domains, x-frame-options, and install
  • system for configuration values locked to this environment only

The practical rule is simple. If a value would be wrong, dangerous, or embarrassing on a different server, it goes in env.php. If it should be identical everywhere, it goes in config.php.

Question config.php env.php
Committed to git? Yes No
Typical contents Modules list, scopes, themes, i18n, shared store settings DB credentials, crypt key, Redis hosts, queue, MAGE_MODE, Admin path
Written by app:config:dump Shared settings Sensitive and system-specific settings
Written by config:set With –lock-config With –lock-env
Written by config:sensitive:set Never Always
Locks the Admin field? Yes Yes
Overridden by env.php and environment variables Environment variables

How Magento decides which value wins

When the same configuration path exists in more than one place, Magento reads them in a fixed order. Adobe documents it from highest to lowest priority:

  1. Environment variables. Adobe states that environment variables, if they exist, override all other values.
  2. env.php, which overrides config.php.
  3. config.php.
  4. Values stored in the core_config_data table, which is what the Admin writes to.
  5. Defaults from module config.xml files.

This order is why “I changed it in the Admin and nothing happened” is such a common ticket. If a path is present in either file, the Admin field is disabled and shows that the value is locked. If it is only set by an environment variable, the Admin may still accept a save into the database, but the storefront keeps using the environment variable. When something looks stuck, check the three places above the database before you start clearing caches.

A fast way to see the effective value is bin/magento config:show. With no path it lists every saved value. With a path and scope it shows exactly one:

bin/magento config:show --scope=websites --scope-code=base web/unsecure/base_url

Encrypted values print as asterisks, which is expected.

app:config:dump: what it exports and where

bin/magento app:config:dump takes configuration that was set in the Admin and writes it into the two files. Adobe’s export configuration reference describes the split: shared settings go to config.php, and sensitive and system-specific settings go to env.php.

You can limit what gets dumped by passing config types:

bin/magento app:config:dump scopes themes

The available types are scopes, system, themes, and i18n. With no argument, the command dumps everything.

Two consequences catch teams off guard.

Everything you dump becomes locked. A full dump copies hundreds of system values into config.php. Every one of those fields is now read-only in the Admin on every environment that deploys that file. Merchandisers who used to change a shipping message or a footer setting will find the field greyed out. This is the right behavior for a strict pipeline, but it surprises store teams who were never told.

Modules decide what counts as sensitive. A module marks a path as sensitive or system-specific in its di.xml through Magento\Config\Model\Config\TypePool. Core payment credentials are marked correctly. A third-party extension that forgot to do this can have its API key dumped straight into config.php and then committed. Before you commit a dump, diff config.php and search it for anything that looks like a key, secret, password, or token.

For that reason, many teams dump only scopes and themes, and manage individual system values deliberately with config:set. That keeps config.php small enough to review and avoids freezing the whole Admin.

config:set –lock-env vs –lock-config

bin/magento config:set writes a single configuration value. Without a lock option it writes to the database, just like saving in the Admin. With a lock option it writes to one of the two files instead. Adobe’s config:set reference gives the syntax:

bin/magento config:set [--scope="..."] [--scope-code="..."] [-le | --lock-env] [-lc | --lock-config] path value
Option Writes to Admin field Use it for
none core_config_data Editable Values merchants should own
–lock-env app/etc/env.php Locked Per-environment values: base URLs, search host, payment sandbox flags
–lock-config app/etc/config.php Locked Values that must be identical everywhere and reviewed in git
both app/etc/config.php Locked Nothing: –lock-config wins when both are given

A few details worth knowing:

  • The lock options replaced the older --lock flag in Magento 2.2.4. Old runbooks that use --lock need updating.
  • If a path is already locked in a file, a plain config:set without a lock option will refuse to write it to the database. Re-run it with the matching lock option to change the file value.
  • Lock options work even before Commerce is installed, but only for the default scope. That is handy in container builds where you want config in place before setup:install.
  • Adobe recommends leaving the value off the command line and entering it at the prompt, so it does not end up in your shell history.

A typical per-environment command on staging looks like this:

bin/magento config:set --lock-env --scope=default web/secure/base_url https://staging.example.com/

Followed by:

bin/magento app:config:import

Adobe’s docs are explicit that after setting a value with either lock option you must run app:config:import before you access the Admin or the storefront.

Sensitive values: config:sensitive:set

Payment gateway passwords, API keys, and similar values should never pass through config.php. The dedicated command writes them to env.php only:

bin/magento config:sensitive:set payment/some_gateway/api_key

There is no value argument and no lock flag. The command prompts for the value. Because it lands in env.php, each environment can carry its own sandbox or live credential without anything sensitive reaching your repository.

Environment variables: the override layer

Environment variables sit above both files, which makes them the cleanest way to inject values from a secrets manager, a container orchestrator, or a hosting control panel. The naming format, from Adobe’s override reference, is:

  • CONFIG__DEFAULT__<PATH> for global scope
  • CONFIG__WEBSITES__<WEBSITE_CODE>__<PATH> for a website
  • CONFIG__STORES__<STORE_VIEW_CODE>__<PATH> for a store view

Each / in the configuration path becomes two underscores. Underscores already in the path stay as single underscores. The entire name is uppercase, and you use the scope code, not its display name. So catalog/search/elasticsearch_server_hostname at global scope becomes:

CONFIG__DEFAULT__CATALOG__SEARCH__ELASTICSEARCH_SERVER_HOSTNAME

For PHP to see these through $_ENV, php.ini needs variables_order = "EGPCS". On Adobe Commerce on cloud infrastructure, variables entered through the Project Web Interface take an env: prefix.

The tradeoff is visibility. A value set only by an environment variable does not appear in either file and is easy to forget. Use them for secrets and for values that differ per environment, and document the list somewhere your team will actually look.

A pipeline that uses both files correctly

Adobe’s pipeline model splits work across three systems. The details below follow the order in the technical details guide, with the checks we would add around each step.

System Needs a database? What happens there
Development Yes Change settings in the Admin, run app:config:dump, review and commit config.php
Build No Pull code and config.php, run setup:di:compile and setup:static-content:deploy
Production Yes Maintenance on, pull the build, app:config:import, setup:upgrade if schema changed, cache flush, maintenance off

On development:

  1. Make the change in the Admin of a local or integration environment.
  2. Run bin/magento app:config:dump scopes themes, or the narrower set your team agreed on.
  3. Run git diff app/etc/config.php. Read every changed line. Look for secrets and for unrelated settings that slipped in.
  4. Commit config.php. Never commit env.php.

On the build system:

The build server does not need a database, and that is the main reason config.php matters. Because scopes and themes are in the file, setup:static-content:deploy knows which themes and locales to compile without querying the database. Our guide to Magento 2 static content deploy strategies covers how to make that step fast on Hyva themes. The compile step is explained in Magento 2 deploy modes and setup:di:compile.

On production:

  1. Enable maintenance mode and stop queue consumers.
  2. Pull the built code and the committed config.php.
  3. Run bin/magento app:config:import. This writes changed file values into the database so that the files and core_config_data agree.
  4. Run bin/magento setup:upgrade --keep-generated only if schema or data patches changed.
  5. Set any system-specific or sensitive values with config:set, config:sensitive:set, or environment variables.
  6. Flush the cache and turn maintenance mode off.

If you use atomic releases with shared paths, env.php should be a shared file that persists between releases, not something rebuilt on every deploy. Our walkthrough of zero-downtime Magento deploys with Deployer shows where that fits.

Adobe Commerce Cloud: ece-tools config:dump

On cloud infrastructure, the recommended command is ./vendor/bin/ece-tools config:dump. Adobe’s cloud store settings guide explains the main difference: it writes only the settings you actually configured, so default values are not locked, while bin/magento app:config:dump is more comprehensive and locks everything it exports. Two cloud-specific warnings from the same page are worth repeating:

  • Never delete config.php to regenerate it. Build and deploy rely on settings inside it.
  • After you enable configuration management, move SCD_* variables such as SCD_STRATEGY and SCD_MATRIX from the deploy stage to the build stage so static content compiles during build.

Common mistakes and how to fix them

The Admin field is greyed out and nobody knows why. Search both files for the path. grep -n "path/fragment" app/etc/config.php app/etc/env.php usually finds it in seconds. To make it editable again, remove the entry from the file, commit or redeploy, and run app:config:import.

A full dump froze the whole Admin. Revert config.php to the last good version, then dump only scopes and themes. Move the handful of system values you truly want locked into explicit config:set commands.

Staging emails customers because it has production base URLs. Base URLs belong in env.php with –lock-env, or in environment variables, never in config.php. When you copy a production database to staging, the database values come along, so anything not locked per environment follows them. Pair this with a masked database copy so real customer addresses never reach staging.

A module is enabled locally but disabled in production. The modules array in config.php is the source of truth. If someone ran module:enable on a server instead of committing the change, the next deploy reverts it. Enable modules locally, commit config.php, and deploy.

Secrets in git history. If a dump pushed an API key into config.php and it was committed, removing it in a new commit is not enough. Rotate the credential, then move it to config:sensitive:set or an environment variable.

How this fits a clean Hyva or Adobe Commerce project

None of this is specific to one theme, but Hyva projects make the build step lighter, which makes a disciplined config.php even more valuable: the faster your static content compile, the more you notice when a missing scope in config.php forces a database lookup or a failed build. If your team is planning a Hyva theme build, settle the config.php policy before the first sprint so every environment starts from the same file.

The same discipline applies if you also run storefronts on Shopify, Shopware, or BigCommerce: keep shared configuration in version control, keep secrets per environment, and make the precedence order something your whole team can explain. You can read more about Bemeir, see the technology partners we work with, or start at the Bemeir home page if you want help reviewing your deployment configuration.

FAQ

Should env.php be committed to git?

No. env.php contains database credentials, the crypt key, cache and queue hosts, and sensitive configuration values. Adobe’s guidance is to keep it out of source control. Commit config.php instead, and manage env.php per server, through a shared path in your deploy tool, or by generating it from environment variables.

What is the difference between –lock-env and –lock-config?

Both lock the Admin field. –lock-env writes the value to app/etc/env.php, so it applies only to that server. –lock-config writes it to app/etc/config.php, so it travels through git to every environment. If you pass both, –lock-config wins. After either one, run bin/magento app:config:import.

Do environment variables override env.php?

Yes. Adobe documents environment variables as the highest priority source. They override env.php, which overrides config.php, which overrides values in the database. Use the CONFIG__DEFAULT__, CONFIG__WEBSITES__, or CONFIG__STORES__ prefix with the configuration path in uppercase and slashes replaced by double underscores.

Why can’t I change a setting in the Magento Admin?

The path is almost certainly present in config.php or env.php, which locks the field. Search both files for the path. To make it editable again, remove the entry, deploy the change, and run app:config:import. If the value is set by an environment variable, the Admin may save a new value that never takes effect.

Does the build server need a database for app:config:dump to work?

The dump itself runs on development, where a database exists. The build server does not need a database at all, as long as config.php contains the scopes and themes. That is what lets setup:di:compile and setup:static-content:deploy run in a CI container with no database connection.

Let us help you get started on a project with Magento 2 config.php vs env.php: app:config:dump, config:set –lock-env, and Pipeline Deployment and leverage our partnership to your fullest advantage. Fill out the contact form below to get started.

more articles about ecommerce

Read on the latest with Shopify, Magento, eCommerce topics and more.