Download the PHP package wp-spaghetti/wp-env without Composer

WP Env

A comprehensive WordPress environment management utility with typed getters, system detection and secure configuration handling.

Features

• Multi-Source Configuration: WordPress constants, .env files, and getenv() with intelligent priority
• Typed Getters: Type-safe methods for bool, int, float, and array values
• Environment Detection: Automatic development, staging, and production environment detection
• Container Detection: Docker, Kubernetes, Podman, and other containerization detection
• Performance Caching: Smart caching system with sensitive data protection
• Security-Focused: Built-in protection for sensitive configuration values
• WordPress Integration: Native WordPress hooks and filters for customization
• Zero Dependencies: Works with or without external environment libraries
• Bedrock Compatible: Seamless integration with modern WordPress setups

Installation

Install via Composer:

Quick Start

1. Basic Usage

2. Configuration Priority

WP Env uses the following priority order:

1. WordPress Constants (define() in wp-config.php)
2. .env files (via oscarotero/env if available)
3. System environment (getenv())
4. Default values

3. WordPress Integration

API Reference

Core Methods

Environment::get(string $key, mixed $default = null): mixed

Get environment variable with fallback to default value.

Environment::getBool(string $key, bool $default = false): bool

Get environment variable as boolean. Recognizes: 1, true, on, yes, enabled.

Environment::getInt(string $key, int $default = 0): int

Get environment variable as integer with type conversion.

Environment::getFloat(string $key, float $default = 0.0): float

Get environment variable as float with type conversion.

Environment::getArray(string $key, array $default = []): array

Get environment variable as array (comma-separated values).

Environment::getRequired(string $key): mixed

Get required environment variable (throws exception if missing).

Validation Methods

Environment::validateRequired(array $keys): void

Validate that all required environment variables are set.

Environment::load(array $keys): array

Load multiple environment variables at once.

Environment Detection

Environment::getEnvironment(): string

Get current environment type: development, staging, or production.

Environment::isDevelopment(): bool

Check if running in development environment.

Environment::isStaging(): bool

Check if running in staging environment.

Environment::isProduction(): bool

Check if running in production environment.

Container Detection

Environment::isDocker(): bool

Check if running inside a Docker container.

Environment::isContainer(): bool

Check if running in any containerized environment (Docker, Podman, etc.).

WordPress-Specific Methods

Environment::isDebug(): bool

Check if WordPress debug mode is enabled (WP_DEBUG).

Environment::isMultisite(): bool

Check if WordPress is running in multisite mode.

Environment::isCli(): bool

Check if running via CLI (WP-CLI or PHP CLI).

Environment::isWeb(): bool

Check if running via web request.

System Information

Environment::getServerSoftware(): string

Get server software (nginx, apache, litespeed, iis).

Environment::getPhpSapi(): string

Get PHP SAPI information.

Utility Methods

Environment::getDebugInfo(): array

Get comprehensive environment information for debugging.

Environment::clearCache(): void

Clear internal caches (useful for testing).

Environment::addSensitiveKey(string $key): void

Add key to sensitive list (prevents caching/logging).

Configuration Examples

WordPress Constants (wp-config.php)

Environment File (.env)

Docker Compose Integration

Hook System

WP Env provides several WordPress hooks for customization:

Filter Environment Values

Custom Environment Detection

Container Detection Override

Sensitive Key Protection

Cache Events

Advanced Usage Examples

Plugin Configuration Management

Environment-Specific Service Registration

Multi-Environment Configuration

Troubleshooting

Debug Information

Common Issues

Environment not detected correctly:

• Set WP_ENVIRONMENT_TYPE constant in wp-config.php
• Use .env file with WP_ENV=development
• Check domain-based detection logic

Values not loading:

• Verify constant names (WordPress constants take priority)
• Check if oscarotero/env is installed for .env support
• Clear cache with Environment::clearCache()

Container detection issues:

• Ensure Docker environment variables are set
• Check if .dockerenv file exists
• Use custom detection with hooks

Requirements

• PHP 8.0 or higher
• WordPress 5.0 or higher (for WordPress-specific features)
• Optional: oscarotero/env for .env file support

Changelog

Please see CHANGELOG for a detailed list of changes for each release.

We follow Semantic Versioning and use Conventional Commits to automatically generate our changelog.

Release Process

• Major versions (1.0.0 → 2.0.0): Breaking changes
• Minor versions (1.0.0 → 1.1.0): New features, backward compatible
• Patch versions (1.0.0 → 1.0.1): Bug fixes, backward compatible

All releases are automatically created when changes are pushed to the main branch, based on commit message conventions.

Contributing

For your contributions please use:

• Conventional Commits
• git-flow workflow
• Pull request workflow

See CONTRIBUTING for detailed guidelines.

Sponsor

License

(ɔ) Copyleft 2026 Frugan.
GNU GPLv3, see LICENSE file.