Managing Environments
The Raydium Framework offers a sophisticated way to handle different environments, such as development, staging, and production. This guide will help you understand how to effectively manage these environments within your Raydium-powered application.
Understanding Environments
Environments represent different states your application can be in, each tailored with specific configurations and behaviors to match its purpose. Common environments include:
- Production (
'production'
,'prod'
): The live environment where the application is optimized for performance and security, with debugging tools disabled. - Staging (
'staging'
): A near-replica of production, used for final testing before updates are made live. - Development (
'development'
,'dev'
): Used during the development phase, enabling logging, error reporting, and debugging tools. - Debug (
'deb'
,'debug'
,'local'
): Similar to development but with extra debugging capabilities for in-depth troubleshooting. - Secure (
'secure'
,'sec'
): Emphasizes heightened security, typically for sensitive applications.
Best Practices
- Keep the
.env
File Secure: The.env
environment file contains sensitive information. Ensure it's excluded from version control (e.g., using.gitignore
). - Maintain Environment Consistency: Strive for consistency between development, staging, and production environments to minimize "it works on my machine" problems.
- Leverage Environment-Specific Configurations: Utilize environment-specific settings for database connections, API keys, and other configurations to streamline development and deployment.
Configuring Environments
Using the .env
File
The Raydium Framework uses a .env
environment file located at the root of your project to define environment variables. The key variable for setting the environment is WP_ENVIRONMENT_TYPE
.
Example .env
file configuration:
WP_ENVIRONMENT_TYPE='prod'
IMPORTANT
Optionally, You can override the .env
setup of WP_ENVIRONMENT_TYPE
by defining the RAYDIUM_ENVIRONMENT_TYPE
constant in the bootstrap file or in wp-config.php
. Note that the .env
file takes precedence, so ensure WP_ENVIRONMENT_TYPE='prod'
is removed from the file if you plan to override it.
Depending on this setting, the Raydium Framework adjusts its behavior for performance, security, or debugging.
Supported Environment Values
prod
orproduction
: Sets the environment to production.dev
ordevelopment
: Sets the environment to development.staging
: Sets the environment to staging.debug
ordeb
: Activates the debug environment.secure
orsec
: Activates the secure environment.
Switching Environments
To switch environments, simply modify the WP_ENVIRONMENT_TYPE
value in your .env
file. Afterward, redeploy your application if necessary. The Raydium Framework will automatically detect and apply the corresponding configuration settings.
Environment-Specific Behaviors
Depending on the WP_ENVIRONMENT_TYPE
value, the Raydium Framework configures the application accordingly:
- Production: Optimized for maximum performance and security. Disables debugging tools and hides errors.
- Staging: Similar to production but with some logging enabled for testing purposes.
- Development: Enables extensive error reporting and debugging tools while turning off performance optimizations.
- Debug: Builds upon the development environment by enabling additional debugging features such as script debugging, query logging, and disabling script concatenation.
- Secure: Similar to production, but with additional security features, like file modification restrictions and tighter error handling.
- Cache Settings: The production and secure environments also enable caching to improve performance, unless explicitly disabled by defining the
SWITCH_OFF_CACHE
constant astrue
.
Environment Constants Documentation
The Raydium Framework offers several constants to tailor the application for different environments, ensuring the best balance between performance, security, and debugging.
Production Environment
Environment Identifiers: 'production'
, 'prod'
The production environment is optimized for performance and security.
Defined Constants
DISALLOW_FILE_EDIT
:true
Prevents file editing via the WordPress admin panel to enhance security.WP_DEBUG_DISPLAY
:false
Hides debug messages on the frontend.SCRIPT_DEBUG
:false
Uses minified JavaScript and CSS files for faster load times.WP_CRON_LOCK_TIMEOUT
:60
Defines the time (in seconds) before a cron job is marked as failed and can be retried.EMPTY_TRASH_DAYS
:15
Automatically deletes trashed items after 15 days.WP_DEBUG
:true
if$error_logs_dir
is provided; otherwisefalse
.
Enables or disables WordPress debugging.WP_DEBUG_LOG
: Path specified by$error_logs_dir
if provided; otherwisefalse
.
Defines where to log debug messages.WP_CACHE
:true
Enables caching for improved performance.COMPRESS_SCRIPTS
:true
Enables compression of JavaScript files for improved performance.COMPRESS_CSS
:true
Enables compression of CSS files for improved performance.CONCATENATE_SCRIPTS
:true
Enables concatenation of scripts to reduce HTTP requests.
PHP Settings
display_errors
:'0'
Prevents PHP errors from being displayed to users.
Staging Environment
Environment Identifier: 'staging'
The staging environment mirrors production, with additional error visibility for testing.
Defined Constants
DISALLOW_FILE_EDIT
:false
Allows editing plugin and theme files in the admin panel.WP_DEBUG_DISPLAY
:true
Shows debug messages on the frontend.SCRIPT_DEBUG
:false
Uses minified scripts.SAVEQUERIES
:true
Saves database queries for analysis.WP_DEBUG
:true
Enables WordPress debugging.WP_DEBUG_LOG
: Path specified by$error_logs_dir
if provided; otherwisetrue
.
Logs debug messages to the specified file.
PHP Settings
display_errors
:'0'
Keeps PHP errors hidden from users.
Development Environment
Environment Identifiers: 'development'
, 'dev'
Configured for building and testing features.
Defined Constants
WP_DEBUG
:true
Enables WordPress debugging.SAVEQUERIES
:true
Saves database queries for analysis.WP_DEBUG_DISPLAY
:true
Shows debug messages on the frontend.WP_DISABLE_FATAL_ERROR_HANDLER
:true
Disables the fatal error handler to display errors.SCRIPT_DEBUG
:true
Uses unminified scripts for easier debugging.WP_DEBUG_LOG
: Path specified by$error_logs_dir
if provided; otherwisetrue
.
Logs debug messages.
PHP Settings
display_errors
:'1'
Displays PHP errors on the frontend.
Debug Environment
Environment Identifiers: 'deb'
, 'debug'
, 'local'
Extensive debugging capabilities for detailed troubleshooting.
Defined Constants
WP_DEBUG
:true
Enables WordPress debugging.WP_DEBUG_DISPLAY
:true
Displays debug messages.CONCATENATE_SCRIPTS
:false
Prevents concatenation of scripts for easier debugging.SAVEQUERIES
:true
Saves database queries.WP_CRON_LOCK_TIMEOUT
:120
Sets a longer cron lock timeout for debugging.EMPTY_TRASH_DAYS
:50
Extends trash retention period for easier recovery during debugging.WP_DEBUG_LOG
: Path specified by$error_logs_dir
if provided; otherwisetrue
.
Logs debug messages.
PHP Settings
error_reporting
:E_ALL
Reports all errors.log_errors
:'1'
Enables error logging.log_errors_max_len
:'0'
Removes the limit on the length of logged errors.display_errors
:'1'
Displays PHP errors on the frontend.display_startup_errors
:'1'
Displays startup sequence errors.
Secure Environment
Environment Identifiers: 'secure'
, 'sec'
Optimized for maximum security.
Defined Constants
DISALLOW_FILE_EDIT
:true
Disables editing files through the admin panel.DISALLOW_FILE_MODS
:true
Prevents updates and installations of plugins and themes.WP_DEBUG_DISPLAY
:false
Hides debug messages.SCRIPT_DEBUG
:false
Uses minified scripts.WP_CRON_LOCK_TIMEOUT
:120
Sets a longer cron lock timeout.EMPTY_TRASH_DAYS
:10
Reduces trash retention period.WP_DEBUG
:true
if$error_logs_dir
is provided; otherwisefalse
.
Enables or disables debugging.WP_CACHE
:true
Enables caching for improved performance.COMPRESS_SCRIPTS
:true
Enables compression of JavaScript files.COMPRESS_CSS
:true
Enables compression of CSS files.CONCATENATE_SCRIPTS
:true
Enables concatenation of scripts.
PHP Settings
display_errors
:'0'
Ensures errors are not displayed to users.
Commonly Used Constants Explained
DISALLOW_FILE_EDIT
: Prevents file editing via the admin panel.DISALLOW_FILE_MODS
: Disables all file modifications, including updates.WP_DEBUG
: Activates WordPress debugging mode.WP_DEBUG_DISPLAY
: Controls whether debug messages are shown.WP_DEBUG_LOG
: Specifies whether debug messages are logged.SCRIPT_DEBUG
: Uses unminified versions of scripts and styles.SAVEQUERIES
: Saves database queries for debugging.CONCATENATE_SCRIPTS
: Disables or enables script concatenation.WP_DISABLE_FATAL_ERROR_HANDLER
: Disables the fatal error handler during development.WP_CRON_LOCK_TIMEOUT
: Adjusts the retry timeout for cron jobs.EMPTY_TRASH_DAYS
: Sets auto-delete period for trashed items.WP_CACHE
: Enables caching for improved performance, especially in production and secure environments.COMPRESS_SCRIPTS
: Enables compression of JavaScript for faster loading.COMPRESS_CSS
: Enables compression of CSS for faster loading.
Overriding Constants
Constants can be overridden in the wp-config.php
file. The Raydium Framework only defines these if they haven't been set, allowing custom configurations.
For more on WordPress constants:
PHP Settings Explained
error_reporting
: Specifies which PHP errors are reported.display_errors
: Controls whether errors are displayed to users.display_startup_errors
: Shows errors that occur during PHP's startup sequence.log_errors
: Enables or disables error logging.log_errors_max_len
: Defines the maximum length of log messages.
Notes
- Error Logs Directory (
$error_logs_dir
): If specified, this path is used for logging debug messages. ini_set
Function: Used to modify runtime settings like error display and logging.- Error Handling: The production and secure environments hide errors, while development and debug environments display them for easier troubleshooting.
- Caching: Caching is enabled in production and secure environments by default to improve performance, unless explicitly disabled by the
SWITCH_OFF_CACHE
constant.
By understanding and properly configuring each environment, developers and administrators can optimize their application for security, performance, and ease of debugging.