Os Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require php-standard-library/os
   

   Add to compser.json under require:

   "php-standard-library/os": "^1.0"
   

2. First Usage Detect the current OS family in a Laravel service or controller:

   use PhpStandardLibrary\Os\OperatingSystemFamily;
   
   $osFamily = OperatingSystemFamily::current();
   $isLinux = $osFamily->is(OperatingSystemFamily::LINUX);
   

3. Key Entry Points

   • OperatingSystemFamily::current() → Returns the detected OperatingSystemFamily enum.
   • $family->is($target) → Type-safe comparison (e.g., is(OperatingSystemFamily::WINDOWS)).
   • $family->value → Raw string (e.g., "linux", "darwin").

Implementation Patterns

1. Conditional Logic for OS-Specific Features

Use the enum to gate functionality in Laravel services:

public function handle()
{
    $os = OperatingSystemFamily::current();

    if ($os->is(OperatingSystemFamily::WINDOWS)) {
        $this->configureWindowsSpecificSettings();
    } elseif ($os->is(OperatingSystemFamily::LINUX)) {
        $this->configureLinuxSpecificSettings();
    }
}

2. Dependency Injection

Bind the enum to Laravel’s container for reusable access:

// In a service provider
$this->app->singleton(OperatingSystemFamily::class, function () {
    return OperatingSystemFamily::current();
});

// Inject anywhere
public function __construct(private OperatingSystemFamily $os) {}

3. Configuration Overrides

Use the enum to load OS-specific configs (e.g., config/os.php):

$configPath = match ($os->value) {
    'windows' => 'config/windows.php',
    'linux'   => 'config/linux.php',
    default   => 'config/default.php',
};
config([$configPath => require $configPath]);

4. Artisan Commands

Detect OS in CLI tools:

use PhpStandardLibrary\Os\OperatingSystemFamily;

protected function handle()
{
    if (OperatingSystemFamily::current()->is(OperatingSystemFamily::DARWIN)) {
        $this->info('Running on macOS. Skipping Windows-specific tasks.');
    }
}

5. Testing

Mock OS detection in tests:

use PhpStandardLibrary\Os\OperatingSystemFamily;

public function testLinuxBehavior()
{
    $this->app->instance(OperatingSystemFamily::class, OperatingSystemFamily::LINUX);
    $this->assertTrue(app(OperatingSystemFamily::class)->is(OperatingSystemFamily::LINUX));
}

Gotchas and Tips

Pitfalls

1. Case Sensitivity The enum uses lowercase values ("linux", "windows"), but some systems (e.g., uname on macOS) return "Darwin". The package normalizes this, but verify edge cases like:

   // Avoid hardcoding strings; always use the enum.
   if ($os->value === 'darwin') { ... } // ❌ Fragile
   if ($os->is(OperatingSystemFamily::DARWIN)) { ... } // ✅ Safe
   

2. Container Binding Conflicts If you bind OperatingSystemFamily::class to the container, ensure it’s not overridden by Laravel’s service providers. Use when() or unless() in bindings:

   $this->app->when(OperatingSystemFamily::class)
             ->needs('$os')
             ->give(fn () => OperatingSystemFamily::current());
   

3. Dynamic Environments The package detects OS at runtime. For Docker/Kubernetes, test in isolated environments:

   # Test in a Linux container
   docker run --rm -it ubuntu bash -c "composer require php-standard-library/os && php -r 'var_dump(\PhpStandardLibrary\Os\OperatingSystemFamily::current()->value);'"
   

Debugging

• Unexpected Values? Log the raw detection:

  $detector = new \PhpStandardLibrary\Os\OperatingSystemDetector();
  logger()->debug('Raw OS detection:', ['value' => $detector->detect()]);
  

  Common culprits: Docker containers reporting "linux" even on macOS hosts.

• Enum Extensions The enum is final, but you can extend detection logic:

  class CustomDetector extends \PhpStandardLibrary\Os\OperatingSystemDetector
  {
      public function detect(): string
      {
          $os = parent::detect();
          return $os === 'linux' && $this->isDocker() ? 'docker' : $os;
      }
  
      private function isDocker(): bool { ... }
  }
  

Tips

1. Laravel Facades Create a facade for cleaner syntax:

   // app/Facades/Os.php
   public static function family(): OperatingSystemFamily { return OperatingSystemFamily::current(); }
   

   Usage:

   if (Os::family()->is(OperatingSystemFamily::WINDOWS)) { ... }
   

2. Performance Cache the detection in a singleton if called frequently:

   $this->app->singleton(OperatingSystemFamily::class, fn () => OperatingSystemFamily::current());
   

3. CI/CD Integration Use the enum to skip OS-specific tests in GitHub Actions:

   jobs:
     test:
       runs-on: ubuntu-latest
       steps:
         - run: php -r "if (\PhpStandardLibrary\Os\OperatingSystemFamily::current()->is(\PhpStandardLibrary\Os\OperatingSystemFamily::WINDOWS)) exit(1);"
   

4. Local Development Override OS detection for testing:

   // config/os.php
   'override' => env('APP_OS_OVERRIDE', null), // e.g., "windows"
   

   Then extend the detector to respect this env var.