Common Configuration
Learn how to configure and fine-tune October CMS.
All of the configuration files for October CMS are stored in the config
directory. Each configuration parameter has inline documentation.
# Environment Configuration
Many of October CMS parameters can be configured using environment variables. Environment variables can be set on the server level, or defined for the web application's virtual host (opens new window).
October CMS uses the DotEnv library (opens new window) to make it easy to manage environment variables.
Environment variables can also be defined in the .env
file that the installation script automatically creates in the project root directory. In a fresh installation of October CMS, the base directory contains a .env.example
file that provides typical values for a local environment.
For example, the database connection can be specified with these variables:
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=database
DB_USERNAME=root
DB_PASSWORD=
Any variable in the .env
file can be overridden by external environment variables defined on the server or virtual host level.
Configuration values are loaded in this order:
- system environment variables
- variables in the .env file
- values in the configuration PHP files.
Never add the .env
file to source control. It would be a security risk in the event an intruder gains access to the repository.
# Environment-Specific Configuration Files
If a configuration file must be loaded based on the current application environment, e.g. staging or production, you can use the server-level APP_ENV
variable. Example Apache configuration:
SetEnv APP_ENV "staging"
When the APP_ENV
variable is defined, the platform attempts to load a .env file with the suffix matching the environment name. e.g. .env.staging. If the file does not exist, there will be no error. If both .env.staging and .env files exist, the .env file is completely ignored.
# Common Configuration Parameters
There are several important commonly used configuration parameters.
# Debug Mode
The debug
parameter can be found in the config/app.php
file. By default, the value is loaded from the APP_DEBUG
environment variable. After the installation, the debug mode is enabled in the .env
file:
APP_DEBUG=true
When enabled, the debug mode shows detailed error messages when they occur, along with other debugging features. While useful during development, the debug mode must be disabled on a live production site. It prevents potentially sensitive information from being displayed to website visitors.
Features provided by the debug mode:
- detailed error messages
- failed user authentication provides a specific reason
- combined assets are not minified by default
- safe mode is disabled by default.
# Safe Mode
The safe_mode
parameter can be found in the config/cms.php
file. By default, the value is loaded from the CMS_SAFE_MODE
environment variable. Safe mode disables the PHP code section in CMS templates.
The parameter can take one of the following values:
true
- safe mode is enabledfalse
- safe mode is disablednull
- safe mode is active if debug mode is disabled.
# CSRF protection
October CMS provides a built-in Cross-Site Request Forgery (opens new window) prevention mechanism. When CSRF protection is enabled, October CMS stores a random token in the user's session. The form opening tag and the form token tag add a hidden field with the token value to the form. For all POST, PUT or DELETE requests, the platform checks whether the submitted token value matches the one stored in the user session.
CSRF protection is enabled by default. The enable_csrf_protection
parameter can be found in the config/system.php
file. By default, the value is loaded from the ENABLE_CSRF
environment variable.
# Production Configuration
The following configuration is recommended for production environments:
- CSRF protection is enabled
- debug mode is disabled
- use the public folder for additional security