Product Decisions This Supports
- Multi-Runtime Feature Flags: Implement runtime-specific feature toggles (e.g., enable HHVM optimizations or PHP-specific APIs) without hardcoding version checks. Example: Use
Runtime::isHhvm() to conditionally load HHVM-compatible service providers in Laravel.
- Legacy System Migration: Gradually phase out HHVM support by detecting runtime and triggering deprecation warnings or redirecting users to PHP-based alternatives. Integrate with Laravel’s logging system to notify admins when HHVM is detected.
- CI/CD Pipeline Enforcement: Enforce PHP/HHVM version constraints in CI pipelines (e.g., fail builds if PHP < 8.1 or HHVM is used in a PHP-only branch). Example: Add a pre-commit hook or GitHub Action using
Environment::isPhp81().
- Cross-Platform Compatibility: Build a single Laravel codebase for PHP/HHVM deployments by abstracting runtime-specific logic. Replace manual
if (defined('HHVM_VERSION')) blocks with Runtime::isHhvm() for cleaner, maintainable code.
- Performance Optimization: Enable runtime-specific optimizations (e.g., OPcache tweaks for HHVM or PHP). Use
Runtime::isOpcacheActive() to conditionally apply performance settings in Laravel’s config/app.php.
- Build vs. Buy: Avoid reinventing environment detection logic when this package is maintained by the PHP ecosystem’s core contributors (Sebastian Bergmann) and used in PHPUnit. Reduces technical debt and ensures consistency.
- Testing Isolation: Standardize environment checks in Laravel’s test suite to skip HHVM-specific tests on PHP-only CI or enforce runtime constraints. Example: Use
Runtime::canCollectCodeCoverage() to skip Xdebug-dependent tests on HHVM.
When to Consider This Package
-
Adopt if:
- Your Laravel application supports both PHP and HHVM (e.g., shared hosting with HHVM clusters or legacy systems migrating to modern PHP).
- You need runtime-aware conditional logic (e.g., feature flags, performance tweaks, or deprecation warnings) without manual version checks.
- Your team uses PHPUnit or Sebastian Bergmann’s tools and wants consistency across the ecosystem.
- You’re building CI/CD pipelines that require environment validation (e.g., enforce minimum PHP versions or skip HHVM tests on PHP-only runners).
- You need granular environment detection beyond Laravel’s built-in
app()->environment() (e.g., OS-specific paths, PHP extension checks, or HHVM-specific behaviors).
-
Look elsewhere if:
- You only support PHP (the package is overkill; use Laravel’s native helpers or raw PHP functions).
- Your use case is environment variable management (use
vlucas/phpdotenv or symfony/dotenv instead).
- You need user-agent or OS feature detection (e.g., mobile/desktop) → use
jenssegers/agent or mobiledetectlib/mobile-detect.
- Your primary need is container orchestration (e.g., Kubernetes labels) → consider
symfony/process or custom solutions.
- You’re not using Laravel and prefer framework-agnostic alternatives (e.g.,
phpversion(), PHP_SAPI).
How to Pitch It (Stakeholders)
For Executives:
*"This package enables us to write cleaner, more maintainable Laravel code by handling PHP/HHVM differences automatically. It reduces bugs in mixed environments and future-proofs our stack with minimal effort. Key benefits:
- Enable HHVM-specific optimizations in high-traffic APIs without duplicating logic.
- Fail fast in CI if a pull request targets an unsupported PHP version, catching issues early.
- Gracefully deprecate HHVM by detecting runtime and redirecting users to PHP-based alternatives.
The cost? Zero runtime overhead—it’s a dev dependency that pays for itself in reduced maintenance and fewer environment-related bugs. It’s also used by PHPUnit, so it’s battle-tested and won’t add technical debt."*
For Engineers:
*"The sebastian/environment package provides a clean abstraction for runtime checks in Laravel, replacing spaghetti if (version_compare(PHP_VERSION, '8.0.0') >= 0) with if (Environment::isPhp80()). It’s perfect for:
- Conditional logic: Replace manual checks with methods like
Runtime::isHhvm(), Environment::detect(), or Runtime::isOpcacheActive().
- Test isolation: Skip HHVM tests on PHP-only CI with
Runtime::isHhvm().
- Legacy support: Detect HHVM and log deprecation warnings for users still on it.
- CI/CD validation: Enforce PHP version requirements dynamically (e.g.,
if (!Environment::isPhp81()) exit(1)).
Why not use Laravel’s built-ins?
Laravel’s app()->environment() is great for high-level checks (e.g., local vs. production), but this package offers granular, low-level control (e.g., detecting PHP extensions, OS-specific paths, or HHVM-specific behaviors).
Example use cases in Laravel:
- Custom Artisan commands:
if (Runtime::isLinux()) { ... }
- Service providers: Bind HHVM-specific services conditionally.
- Dynamic config: Load environment-aware settings (e.g.,
config(['app.php_version' => Environment::getPhpVersion()])).
Integration tips:
- Add as a dev dependency (
composer require --dev sebastian/environment).
- Pilot in test suites or CI (low-risk).
- Gradually replace manual environment checks with the package’s API.
- (Optional) Build a Laravel facade for team consistency (e.g.,
Environment::isPhp80()).
Trade-offs:
- Minimal overhead: ~10KB, zero runtime cost.
- Dev-only dependency: Safe to use in tests or CI without affecting production.
- Future-proof: Works with Laravel’s service container if needed (e.g.,
app()->make(Runtime::class))."*
For Test/QA:
*"This package helps us standardize environment checks across Laravel tests and CI, reducing flaky tests due to runtime mismatches. For example:
- Skip HHVM-specific tests on PHP-only CI with
Runtime::isHhvm().
- Enforce PHP version requirements (e.g.,
Environment::isPhp81()) to catch incompatible code early.
- Detect missing extensions (e.g.,
Runtime::hasExtension('intl')) before tests run.
It’s a drop-in replacement for manual checks, so adoption is seamless."*