https://github.com/drevops/environment-detector
🔬 Zero-config environment type detection
https://github.com/drevops/environment-detector
acquia ci ddev environment lagoon pantheon php platform skpr tugboat
Last synced: 3 months ago
JSON representation
🔬 Zero-config environment type detection
- Host: GitHub
- URL: https://github.com/drevops/environment-detector
- Owner: drevops
- License: gpl-3.0
- Created: 2025-03-29T06:18:04.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-02-27T00:42:37.000Z (4 months ago)
- Last Synced: 2026-02-27T02:13:00.036Z (4 months ago)
- Topics: acquia, ci, ddev, environment, lagoon, pantheon, php, platform, skpr, tugboat
- Language: PHP
- Homepage:
- Size: 195 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
Zero-config environment type detection
[](https://github.com/drevops/environment-detector/issues)
[](https://github.com/drevops/environment-detector/pulls)
[](https://github.com/drevops/environment-detector/actions/workflows/test-php.yml)
[](https://codecov.io/gh/drevops/environment-detector)
---
## Features
- Detects environment type: `local`, `ci`, `dev`, `preview`, `stage`, `prod`, or user-defined
- Supports many popular providers out-of-the-box: [Acquia](src/Providers/Acquia.php), [CircleCI](src/Providers/CircleCi.php), [DDEV](src/Providers/Ddev.php), [Docker](src/Providers/Docker.php), [GitHub Actions](src/Providers/GitHubActions.php), [GitLab CI](src/Providers/GitLabCi.php), [Lagoon](src/Providers/Lagoon.php), [Lando](src/Providers/Lando.php), [Pantheon](src/Providers/Pantheon.php), [Platform.sh](src/Providers/PlatformSh.php), [Skpr](src/Providers/Skpr.php), [Tugboat](src/Providers/Tugboat.php)
- Detects custom contexts: [Drupal](src/Contexts/Drupal.php) (more to come)
- Simple API for checking current environment
- Extendable via custom providers and contexts
- Override and fallback support for precise control
- Optimised for performance with static caching
## Installation
```bash
composer require drevops/environment-detector
```
## Quick Start
```php
use DrevOps\EnvironmentDetector\Environment;
Environment::init();
if (getenv('ENVIRONMENT_TYPE') === Environment::LOCAL) {
// Apply local settings.
}
```
Alternatively, use the convenience methods:
```php
use DrevOps\EnvironmentDetector\Environment;
// No need to init() - a first call to is*() will auto-initialize.
if (Environment::isLocal()) {
// Apply local settings.
}
if (Environment::isProd()) {
// Apply production settings.
}
```
## How It Works
1. **Provider detection:** Each provider checks for environment-specific variables
or files to identify itself.
2. **Type mapping:** Once identified, the provider maps its internal state to a
type like `dev`, `prod`, or a custom type.
3. **Context detection**: Optionally applies provider- or framework-specific
changes (e.g., modify Drupal `$settings` global variable to add `$settings['environment']` value).
The resolved type is stored in the `ENVIRONMENT_TYPE` env var. If already set,
this value takes precedence over the provider detection. The `contextualize`
still applies context changes even if the type is pre-set via environment
variable.
## Advanced Usage
### Advanced initialization with customization
```php
Environment::init(
contextualize: TRUE, // Whether to apply the context automatically
fallback: Environment::DEVELOPMENT, // The fallback environment type
override: function($provider, $type) { // The override callback to change the environment type
if ($type === Environment::DEVELOPMENT && $provider->id() === 'tugboat') {
return 'qa';
}
return $type;
},
providers: [new MyCustomProvider()], // Additional provider instances
contexts: [new MyCustomContext()], // Additional context instances
);
```
### Fallback Type
If an environment type is not detected, a fallback `Environment::DEVELOPMENT` will be
returned by default. This is to ensure that, in case of misconfiguration, the application
does not apply local settings in production or production settings in local - 'development'
type is the safest default.
You can set a different fallback type during initialization:
```php
Environment::init(fallback: Environment::PRODUCTION);
```
## Providers
Only one provider can be active. If multiple match, or none match, an exception
is thrown. Register custom providers using `init(providers:[MyCustomProvider::class])`.
Supported built-ins:
- [Acquia](src/Providers/Acquia.php)
- [CircleCI](src/Providers/CircleCi.php)
- [DDEV](src/Providers/Ddev.php)
- [Docker](src/Providers/Docker.php)
- [GitHub Actions](src/Providers/GitHubActions.php)
- [GitLab CI](src/Providers/GitLabCi.php)
- [Lagoon](src/Providers/Lagoon.php)
- [Lando](src/Providers/Lando.php)
- [Pantheon](src/Providers/Pantheon.php)
- [Platform.sh](src/Providers/PlatformSh.php)
- [Skpr](src/Providers/Skpr.php)
- [Tugboat](src/Providers/Tugboat.php)
### Accessing Provider Data
```php
// Initialize first to detect the active provider
Environment::init();
$provider = Environment::getActiveProvider();
if ($provider && $provider->id() === 'acquia') {
// Acquia-specific logic
$data = $provider->data();
if (isset($data['AH_SITE_GROUP'])) {
// Use Acquia-specific environment data
}
}
```
### Adding a Custom Provider
```php
use DrevOps\EnvironmentDetector\Providers\ProviderInterface;
use DrevOps\EnvironmentDetector\Environment;
class CustomHosting implements ProviderInterface {
public function active(): bool {
return isset($_SERVER['CUSTOM_ENV']);
}
public function data(): array {
return ['CUSTOM_ENV' => $_SERVER['CUSTOM_ENV'] ?? null];
}
public function type(): ?string {
return match ($_SERVER['CUSTOM_ENV_TYPE'] ?? null) {
'dev' => Environment::DEVELOPMENT,
'qa' => 'qa',
'live' => Environment::PRODUCTION,
default => null,
};
}
public function id(): string {
return 'customhosting';
}
public function label(): string {
return 'Custom Hosting';
}
public function contextualize(\DrevOps\EnvironmentDetector\Contexts\ContextInterface $context): void {
// Optional: Apply provider-specific context changes
}
}
// Register the custom provider during initialization
Environment::init(providers: [new CustomHosting()]);
```
### Contexts
Contexts apply environment-specific changes to frameworks or applications. A context may
provide generic changes that are applied to the application. A provider may also provide
provider-specific context changes.
For example, a **Drupal** context applies changes to the global `$settings` array, while a
**Lagoon** provider's `contextualize()` method adds Lagoon-specific changes to the `$settings` array.
The goal is to have enough context changes to cover the most common use cases, but also
to allow adding custom contexts to cover specific use cases within the application.
#### Adding a custom context
```php
use DrevOps\EnvironmentDetector\Contexts\ContextInterface;
class CustomContext implements ContextInterface {
public function active(): bool {
return class_exists('MyFramework');
}
public function contextualize(): void {
// Apply generic context changes
global $configuration;
$configuration['custom_value'] = $_SERVER['custom_value'] ?? 'default';
}
public function id(): string {
return 'myframework';
}
public function label(): string {
return 'My Framework';
}
}
// Register the custom context during initialization
Environment::init(contexts: [new CustomContext()]);
```
## Maintenance
```bash
composer install
composer lint
composer test
```
---
*This repository was created using the *[*Scaffold*](https://getscaffold.dev/)*
project template.*