Environment Laravel Package

Product Decisions This Supports

• Multi-Runtime Feature Flags: Enable/disable features based on PHP/HHVM runtime (e.g., experimental APIs, legacy compatibility layers) without hardcoding version checks. Example: "This feature requires HHVM 4.0+" → if (Runtime::isHhvm() && Runtime::getHhvmVersion() >= '4.0').
• Legacy System Migration: Gradually phase out HHVM support by detecting runtime and logging deprecation warnings or redirecting users to PHP-based alternatives.
• CI/CD Pipeline Enforcement: Fail builds or skip tests on unsupported PHP/HHVM versions (e.g., "This project requires PHP 8.1+"). Integrates with Laravel’s testing tools for seamless validation.
• Cross-Platform Compatibility: Build a single codebase for PHP/HHVM deployments (e.g., shared hosting + HHVM clusters) by abstracting runtime-specific logic. Reduces duplication of if (defined('HHVM_VERSION')) blocks.
• Performance Optimization: Enable HHVM-specific optimizations (e.g., opcache tweaks) or fallbacks for PHP (e.g., Runtime::isOpcacheActive()).
• Build vs. Buy: Avoid reinventing environment detection logic (e.g., PHP_SAPI, HHVM_VERSION) when this package is maintained by the PHP ecosystem’s core contributors (Sebastian Bergmann) and used in PHPUnit.
• Testing Isolation: Standardize environment checks in test suites to skip HHVM-specific tests on PHP-only CI or enforce runtime constraints (e.g., "This test requires Xdebug" → if (!Runtime::canCollectCodeCoverage()) $this->markTestSkipped()).

When to Consider This Package

• Adopt if:

  • Your product or service supports both PHP and HHVM (e.g., legacy systems migrating to modern PHP, or multi-runtime deployments like shared hosting + HHVM clusters).
  • You need runtime-aware conditional logic (e.g., feature flags, performance tweaks, or deprecation warnings) without manual version_compare() or defined() 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 for single-runtime projects; 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, browser capabilities) → 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 lets us write cleaner, more maintainable code by handling PHP/HHVM differences automatically—reducing bugs in mixed environments and future-proofing our stack. It’s a drop-in solution used by PHPUnit, so it’s battle-tested and won’t add technical debt. For example:

• Enable HHVM-specific optimizations in our high-traffic APIs without duplicating logic.
• Fail fast in CI if a pull request targets an unsupported PHP version.
• 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."*

For Engineers: *"The sebastian/environment package provides a clean abstraction for runtime checks (e.g., Environment::detect(), Runtime::isHhvm()). It’s perfect for:

• Conditional logic: Replace spaghetti if (version_compare(PHP_VERSION, '8.0.0') >= 0) with if (Environment::isPhp80()).
• 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, production), but this package offers granular, low-level control (e.g., detecting PHP extensions, OS-specific paths, or HHVM-specific behaviors).
• Example use cases:
  • 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()])).

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)).

Next steps:

1. Add as a dev dependency (composer require --dev sebastian/environment).
2. Pilot in test suites or CI (low-risk).
3. Gradually replace manual environment checks with the package’s API.
4. (Optional) Build a Laravel facade for team consistency (e.g., Environment::isPhp80())."*

For Test/QA: *"This package helps us standardize environment checks across 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."*