Mantle provides a configuration interface to allow easy control over the
application and how it differs on each environment. The application ships with a
few configuration files in the
Configuration is possible through the
config() helper function, the
Mantle\Facade\Config facade. Each method supports a "dot"
syntax which includes the name of the file and the option you wish to access.
config( 'app.providers' );
Config::get( 'app.providers' );
Mantle\Facade\Config::get( 'app.providers' );
It is often helpful to have different configuration values based on the environment where the application is running. For example, you may wish to use a different cache driver locally than you do on your production server.
To make this a simple, Mantle utilizes the
DotEnv PHP library. In a fresh Mantle
installation, the root directory of your application will contain a
.env.example file that defines many common environment variables. This file
should be copied to
.env for use.
See Environment File Location for where the
.env should be placed.
.env file contains some common configuration values that may
differ based on whether your application is running locally or on a production
web server. These values are then retrieved from various Mantle configuration
files within the config directory using Mantle's
If you are developing with a team, you may wish to continue including a
.env.example file with your application. By putting placeholder values in the
example configuration file, other developers on your team can clearly see which
environment variables are needed to run your application.
Any variable in your .env file can be overridden by external environment variables such as server-level or system-level environment variables.
Environment File Location
For most WordPress installations, all files static files will be exposed to the
web server and accessible by the end user. Placing a
.env file in your
plugin's folder is not secure since that file can be accessed by anybody on the
internet with a unique interest in your site.
Mantle supports placing the
.env file in more secure locations in your
WordPress application. For WordPress VIP users, the
.env file can be placed
inside your private
/wp-content/private). Mantle will also check in the
WPCOM_VIP_PRIVATE_DIR folder for
For WordPress VIP Users, Mantle will also read the Environmental Variables set by the platform.
Environment File Security
.env file should not be committed to your application's source control,
since each developer / server using your application could require a different
environment configuration. Furthermore, this would be a security risk in the
event an intruder gains access to your source control repository, since any
sensitive credentials would get exposed. See Environment File
Location for more information.
Environment Variable Types
All variables in your .env files are typically parsed as strings, so some reserved values have been created to allow you to return a wider range of types from the env() function:
If you need to define an environment variable with a value that contains spaces, you may do so by enclosing the value in double quotes:
Retrieving Environment Configuration
All of the variables listed in this file will be loaded into the
super-global when your application receives a request. However, you may use the
env helper to retrieve values from these variables in your configuration files.
In fact, if you review the Mantle configuration files, you will notice many of
the options are already using this helper:
'debug' => environment( 'APP_DEBUG', defined( 'WP_DEBUG' ) && WP_DEBUG ),
The second value passed to the env function is the "default value". This value will be returned if no environment variable exists for the given key.
File-based Environment-specific Configuration
For situations when environment variables aren't supported, environment-specific configuration is possible by including a configuration file in a child folder named after the respective environment to apply the configuration for.
.env-based configuration is preferred for simplicity versus file-based PHP files.
The following is an example of a configuration value that is
only loaded on the
│ ├── app.php
│ ├── local
│ │ └── app.php
// Located in config/local/app.php.
'providers' => App\Providers\Local_Service_Provider::class,