Environment Configuration

This page documents the env() and environment() helper functions for accessing environment variables and determining the current application environment. These helpers provide a convenient interface for reading configuration from environment files and detecting runtime environments (e.g., production, staging, local).

For data manipulation helpers like data_get() and data_set(), see Data Manipulation. For other control flow utilities, see Control Flow Helpers.

Overview

The support package provides two global helper functions for environment configuration:

Helper	Purpose	Return Type
env()	Read environment variable values with optional defaults	mixed
environment()	Get current environment or check if environment matches	bool|Environment

Both helpers are defined in src/helpers.php25-52 and provide a clean API for environment-aware application behavior.

Sources: src/helpers.php25-52

Environment Variable Access

The env() Helper

The env() function retrieves the value of an environment variable. If the variable is not set, it returns the provided default value.

Function Signature:

• $key: The environment variable name (e.g., 'APP_DEBUG', 'DATABASE_HOST')
• $default: The value to return if the variable is not set (defaults to null)
• Returns: The environment variable value or the default

Implementation:

The helper delegates to the underlying \Hypervel\Support\env() function, which handles type conversion and value parsing. This allows environment variables stored as strings to be automatically converted to appropriate PHP types.

Sources: src/helpers.php25-33

Environment Variable Resolution

Resolution Flow

Sources: src/helpers.php25-33

Environment Detection

The environment() Helper

The environment() function serves two purposes:

1. Retrieve the current Environment instance
2. Check if the current environment matches one or more environment names

Function Behavior:

Call Pattern	Return Type	Description
environment()	Environment	Returns the Environment instance
environment('production')	bool	Checks if environment is "production"
environment('local', 'staging')	bool	Checks if environment is any of the given names

Implementation:

The function attempts to resolve the Environment instance from the ApplicationContext container src/helpers.php41-44 If the container is not available, it creates a new instance. When called with arguments, it delegates to the Environment::is() method.

Sources: src/helpers.php35-52

Environment Instance Resolution

Container Resolution Diagram

Sources: src/helpers.php35-52

Code Entity Mapping

Helper Functions and Dependencies

Sources: src/helpers.php1-52

Usage Patterns

Reading Configuration

Environment variables are typically read during application bootstrap or service initialization:

Environment-Specific Behavior

Use the environment() helper to conditionally execute code based on the current environment:

Type Conversion

The env() helper automatically converts string values to appropriate PHP types:

Environment Value	PHP Type	Example
"true" or "(true)"	bool	true
"false" or "(false)"	bool	false
"null" or "(null)"	null	null
"empty" or "(empty)"	string	""
Numeric strings	int or float	123, 3.14
Other strings	string	"value"

Sources: src/helpers.php25-33

Integration with Service Container

Container Resolution Strategy

The environment() helper uses a two-tier resolution strategy:

1. Container Resolution (Preferred): If the ApplicationContext has a container, it retrieves the Environment instance from the container src/helpers.php41-43 This ensures the singleton instance is used throughout the application.

2. Fallback Creation: If no container is available, a new Environment instance is created src/helpers.php44 This allows the helper to work even during early bootstrap before the container is initialized.

Sources: src/helpers.php35-52

Best Practices

When to Use env()

Use Case	Recommended	Reason
Configuration files	✓ Yes	Read environment-specific settings
Service providers	✓ Yes	Configure services during bootstrap
Controllers/Services	✗ No	Use config values instead for better caching
Runtime logic	✗ No	Config values are cached; env() may return null

When to Use environment()

Use Case	Recommended	Reason
Conditional service registration	✓ Yes	Register debug tools only in development
Error handling behavior	✓ Yes	Show detailed errors in non-production
Feature availability	✓ Yes	Enable experimental features per environment
Logging verbosity	✓ Yes	Adjust log levels by environment

Configuration Caching Considerations

In production environments, configuration values are typically cached for performance. Since cached config does not re-read environment variables, follow these guidelines:

1. Always read env() in configuration files, not in application code
2. Use config values (config('app.debug')) in services and controllers
3. Clear config cache after changing environment variables in production
4. Use environment() for runtime checks that should not be cached

Sources: src/helpers.php25-52

Summary

The environment configuration helpers provide essential functionality for:

• Variable Access: Read environment variables with type conversion via env()
• Environment Detection: Check current environment via environment()
• Container Integration: Seamlessly integrate with the PSR-11 container
• Fallback Support: Work correctly even before container initialization

These helpers form the foundation for environment-aware configuration throughout the Hypervel framework.

Sources: src/helpers.php25-52