https://github.com/wp-spaghetti/wp-env
A comprehensive WordPress environment management utility with typed getters, system detection and secure configuration handling
https://github.com/wp-spaghetti/wp-env
environment wordpress wordpress-development
Last synced: 4 months ago
JSON representation
A comprehensive WordPress environment management utility with typed getters, system detection and secure configuration handling
- Host: GitHub
- URL: https://github.com/wp-spaghetti/wp-env
- Owner: wp-spaghetti
- License: gpl-3.0
- Created: 2025-08-30T10:13:51.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-14T17:47:16.000Z (9 months ago)
- Last Synced: 2025-09-14T19:30:16.998Z (9 months ago)
- Topics: environment, wordpress, wordpress-development
- Language: PHP
- Homepage:
- Size: 121 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
- Support: .github/SUPPORT.md
Awesome Lists containing this project
README
# 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:
```bash
composer require wp-spaghetti/wp-env
```
## Quick Start
### 1. Basic Usage
```php
30,
'MY_PLUGIN_RETRIES' => 3,
'MY_PLUGIN_ENABLED' => true
]);
// Environment-specific behavior
if (Environment::isProduction()) {
$this->enableCaching();
}
if (Environment::isDebug()) {
$this->enableDetailedLogging();
}
}
}
```
## 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.
```php
Environment::validateRequired([
'DB_HOST',
'DB_NAME',
'API_KEY'
]);
```
#### `Environment::load(array $keys): array`
Load multiple environment variables at once.
```php
// Simple array
$vars = Environment::load(['KEY1', 'KEY2', 'KEY3']);
// With defaults
$vars = Environment::load([
'API_URL' => 'https://api.example.com',
'TIMEOUT' => 30,
'ENABLED' => true
]);
```
### 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)
```php
loadConfiguration();
}
private function loadConfiguration(): void
{
// Load all plugin settings at once
$this->config = Environment::load([
'MYPLUGIN_API_URL' => 'https://api.example.com',
'MYPLUGIN_TIMEOUT' => 30,
'MYPLUGIN_RETRIES' => 3,
'MYPLUGIN_CACHE_TTL' => 3600,
'MYPLUGIN_FEATURES' => [],
'MYPLUGIN_DEBUG' => false
]);
// Environment-specific overrides
if (Environment::isDevelopment()) {
$this->config['MYPLUGIN_DEBUG'] = true;
$this->config['MYPLUGIN_TIMEOUT'] = 5; // Shorter timeout for dev
}
if (Environment::isDocker()) {
$this->config['MYPLUGIN_API_URL'] = 'http://api:8080'; // Container URL
}
// Validate critical configuration
if (Environment::isProduction()) {
Environment::validateRequired([
'MYPLUGIN_API_KEY',
'MYPLUGIN_SECRET_KEY'
]);
}
}
public function get(string $key, $default = null)
{
return $this->config[$key] ?? $default;
}
}
```
### Environment-Specific Service Registration
```php
registerDevelopmentServices();
break;
case Environment::ENV_STAGING:
$this->registerStagingServices();
break;
case Environment::ENV_PRODUCTION:
$this->registerProductionServices();
break;
}
// Container-specific services
if (Environment::isContainer()) {
$this->registerContainerServices();
}
}
private function registerDevelopmentServices(): void
{
// Development-only services
add_action('wp_footer', [$this, 'addDebugInfo']);
// Use different API endpoints
$apiUrl = 'http://localhost:3000/api';
}
private function registerProductionServices(): void
{
// Production optimizations
add_action('init', [$this, 'enableCaching']);
// Production API endpoints
$apiUrl = Environment::get('PROD_API_URL', 'https://api.example.com');
}
private function registerContainerServices(): void
{
// Container-specific networking
$redisHost = Environment::get('REDIS_HOST', 'redis');
$dbHost = Environment::get('DB_HOST', 'db');
}
}
```
### Multi-Environment Configuration
```php
[
'debug' => true,
'cache_ttl' => 0,
'api_url' => 'http://localhost:3000',
'log_level' => 'debug'
],
Environment::ENV_STAGING => [
'debug' => true,
'cache_ttl' => 300,
'api_url' => 'https://staging-api.example.com',
'log_level' => 'info'
],
Environment::ENV_PRODUCTION => [
'debug' => false,
'cache_ttl' => 3600,
'api_url' => 'https://api.example.com',
'log_level' => 'error'
]
];
public function get(string $key, $default = null)
{
$currentEnv = Environment::getEnvironment();
$envConfig = $this->environments[$currentEnv] ?? [];
// Try environment-specific config first
if (isset($envConfig[$key])) {
return $envConfig[$key];
}
// Fall back to environment variable
return Environment::get(strtoupper($key), $default);
}
public function getApiUrl(): string
{
return $this->get('api_url');
}
public function getCacheTtl(): int
{
return (int) $this->get('cache_ttl');
}
public function shouldEnableDebug(): bool
{
return (bool) $this->get('debug');
}
}
```
## Troubleshooting
### Debug Information
```php
// Get comprehensive environment info
$info = Environment::getDebugInfo();
print_r($info);
// Check specific values
echo "Environment: " . Environment::getEnvironment() . "\n";
echo "Is Docker: " . (Environment::isDocker() ? 'yes' : 'no') . "\n";
echo "Debug Mode: " . (Environment::isDebug() ? 'enabled' : 'disabled') . "\n";
```
### 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](https://packagist.org/packages/oscarotero/env) for .env file support
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for a detailed list of changes for each release.
We follow [Semantic Versioning](https://semver.org/) and use [Conventional Commits](https://www.conventionalcommits.org/) 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](https://www.conventionalcommits.org)
- [git-flow workflow](https://danielkummer.github.io/git-flow-cheatsheet/)
- [Pull request workflow](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project)
See [CONTRIBUTING](.github/CONTRIBUTING.md) for detailed guidelines.
## Sponsor
[
](https://buymeacoff.ee/frugan)
## License
(ɔ) Copyleft 2025 [Frugan](https://frugan.it).
[GNU GPLv3](https://choosealicense.com/licenses/gpl-3.0/), see [LICENSE](LICENSE) file.