Basic Configuration (.env)
Relevant source files
The following files were used as context for generating this wiki page:
CodeIgniter 4 utilizes a .env file, also known as a "dot env" file, to handle environment-specific configurations. This approach allows developers to define variables that change between different server environments (like development, testing, and production) without modifying the core application code. It is a simple text file located in the project's root directory that stores key-value pairs for settings such as database credentials, API keys, and the application environment itself.
The primary benefit of using a .env file is the separation of configuration from code. This enhances security by keeping sensitive credentials out of version control systems. The framework ships with a template file named env which should be copied and renamed to .env to get started. The .env file is then loaded automatically by the framework on startup.
Sources: source/general/configuration.rst:1-21
How .env Works
When a CodeIgniter 4 application starts, it automatically looks for a .env file in the project root. If found, it parses the file and injects the defined variables into the environment using putenv(), making them available through $_ENV and $_SERVER. These variables can then be accessed throughout the application using the env() function.
The intended workflow is to copy the provided env template file to .env and customize it for the specific server environment. Crucially, the .env file should be added to your version control system's ignore list (e.g., .gitignore) to prevent sensitive information from being committed.
Sources: source/general/configuration.rst:23-35
The following diagram illustrates the loading process of environment variables from the .env file.
This diagram shows that the application first checks for the .env file. If it exists, its values are loaded; otherwise, the application falls back to default values defined in the configuration classes.
Sources: source/general/configuration.rst:23-28
Key Configuration Variables
While any custom variable can be placed in the .env file, several are fundamental to the framework's operation.
Setting the Application Environment
The single most important variable is CI_ENVIRONMENT. This setting controls framework behavior in different contexts, such as error reporting and which configuration values to use.
# .env
CI_ENVIRONMENT = development
The valid environments are:
development: The default mode, intended for use while building the application. It enables maximum error reporting.production: Intended for live servers. It disables detailed error output for security and provides a better user experience.testing: Used during automated testing. It has its own set of configuration values and disables error reporting that could interfere with tests.
Sources: source/concepts/environments.rst:1-26, source/installation/running.rst:54-58
The following table summarizes the characteristics of each environment.
| Environment | Description | Key Features |
|---|---|---|
development | For use during local development and debugging. | Shows all errors; enables debug toolbar. |
production | For live, public-facing applications. | Suppresses errors; focuses on performance. |
testing | For running automated tests. | Bypasses standard error handling. |
Sources: source/concepts/environments.rst:14-26
Database Configuration
Storing database credentials in the .env file is a standard practice. This prevents sensitive data from being hard-coded in the app/Config/Database.php file. The keys in the .env file should be prefixed with database.group., where group is the connection group (e.g., default or tests).
Example .env configuration for a default database connection:
# .env
database.default.hostname = localhost
database.default.database = ci4_db
database.default.username = root
database.default.password =
database.default.DBDriver = MySQLi
These values will override the corresponding properties in the $default array within app/Config/Database.php.
Sources: source/database/configuration.rst:12-29
Base URL
The app.baseURL variable should be set to the root URL of your application. If left empty, the framework will attempt to auto-detect it, but explicitly setting it is recommended for reliability, especially for command-line usage.
# .env
app.baseURL = 'http://example.com/'
Sources: source/general/configuration.rst:104-110
Accessing .env Variables
The primary method for retrieving variables from the .env file is the global env() function. This function searches for the variable in the environment and returns its value. It is commonly used within configuration files to fetch environment-specific settings.
The following sequence diagram shows how a configuration class retrieves a database setting.
This diagram illustrates the env() function acting as an intermediary to securely fetch configuration from the environment superglobals.
Sources: source/general/configuration.rst:37-44
Environment-Specific Logic
You can execute code conditionally based on the current environment by checking the ENVIRONMENT constant. This is useful for loading development-only tools or applying different settings.
if (ENVIRONMENT === 'development') {
// Do something specific for the development environment,
// like loading a debugging tool.
}
This practice allows for clean separation of environment-specific logic within your application code.
Sources: source/concepts/environments.rst:41-46
Testing Configuration
When running automated tests, the environment should be set to testing. This is typically done in the phpunit.xml file, which takes precedence over the .env file for test runs. This ensures that tests run with a consistent and isolated configuration, often using a separate in-memory or dedicated test database.
Example configuration in phpunit.xml:
<phpunit>
<!-- ... -->
<php>
<env name="CI_ENVIRONMENT" value="testing"/>
<env name="database.tests.hostname" value="localhost"/>
<env name="database.tests.database" value=":memory:"/>
<!-- ... -->
</php>
</phpunit>
This setup ensures that when you run your test suite, the application operates in testing mode and connects to the specified test database, preventing interference with development or production data.
Sources: source/testing/overview.rst:54-70, source/database/configuration.rst:111-118
Summary
The .env file is a cornerstone of CodeIgniter 4's configuration management. It provides a flexible and secure way to manage application settings across different environments like development, testing, and production. By externalizing environment-specific variables such as database credentials and the CI_ENVIRONMENT flag, developers can maintain a clean codebase, enhance security by excluding sensitive data from version control, and streamline the deployment process. Proper use of the .env file is essential for building robust and maintainable applications with CodeIgniter 4.
Sources: source/general/configuration.rst, source/concepts/environments.rst