Osbundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add to composer.json:

   "require": {
       "fi/osbundle": "2.0.*"
   },
   "autoload": {
       "psr-4": {
           "Fi\\OsBundle\\": "vendor/fi/osbundle/"
       }
   }
   

   Run composer update.

2. First Use Case Detect the OS in a controller or service:

   use Fi\OsBundle\OsBundle;
   
   $osDetector = new OsBundle();
   $osName = $osDetector->getOsName(); // e.g., "Windows", "Linux", "MacOS"
   $osVersion = $osDetector->getOsVersion(); // e.g., "10.0", "5.4"
   

3. Where to Look First

   • src/OsBundle.php: Core logic for OS detection.
   • tests/: Example use cases and edge-case handling.
   • README.md: Quick reference for methods.

Implementation Patterns

Common Workflows

1. Conditional Logic Based on OS Use OS detection to tailor behavior (e.g., file paths, CLI commands):

   if ($osDetector->isWindows()) {
       $command = 'dir';
   } elseif ($osDetector->isLinux()) {
       $command = 'ls';
   }
   

2. Service Integration Register the bundle in config/services.php:

   return [
       'os_detector' => Fi\OsBundle\OsBundle::class,
   ];
   

   Inject via constructor:

   public function __construct(private OsBundle $osDetector) {}
   

3. Environment-Specific Config Load OS-dependent configs in config/os.php:

   return [
       'windows' => ['path_separator' => '\\'],
       'linux' => ['path_separator' => '/'],
   ];
   

   Access via:

   $config = config('os.' . $osDetector->getOsName());
   

Integration Tips

• Symfony Kernel Events: Trigger OS-specific logic on kernel.request:

  $event->setResponse(new Response("Optimized for {$osDetector->getOsName()}"));
  

• Twig Extensions: Expose OS data to templates:

  // src/Twig/AppExtension.php
  public function getFunctions()
  {
      return [
          new \Twig\TwigFunction('os_name', [$this->osDetector, 'getOsName']),
      ];
  }
  

  Usage in template:

  {{ os_name() }} is detected.
  

Gotchas and Tips

Pitfalls

1. False Positives in Detection

   • Issue: Some Linux distros (e.g., Alpine) may return unexpected versions.
   • Fix: Extend OsBundle or override detection logic:

     $osDetector->setCustomOsName('Alpine'); // Force override
     

2. Case Sensitivity

   • Issue: getOsName() returns lowercase (e.g., "windows"), but isWindows() is case-insensitive.
   • Tip: Normalize comparisons:

     if (strtolower($osDetector->getOsName()) === 'windows') { ... }
     

3. Version Parsing Quirks

   • Issue: getOsVersion() may return raw output (e.g., "5.4.0-42-generic").
   • Tip: Sanitize with regex:

     preg_match('/\d+\.\d+/', $osDetector->getOsVersion(), $matches);
     $version = $matches[0] ?? 'unknown';
     

Debugging

• Log OS Data Dump OS info for debugging:

  \Log::debug('OS:', [
      'name' => $osDetector->getOsName(),
      'version' => $osDetector->getOsVersion(),
      'raw' => $osDetector->getRawOsInfo(),
  ]);
  

• Test Edge Cases Mock OS detection in tests:

  $osDetector = $this->createMock(OsBundle::class);
  $osDetector->method('getOsName')->willReturn('Linux');
  

Extension Points

1. Custom OS Detection Extend the base class:

   class CustomOsBundle extends OsBundle {
       public function isCustomOs(): bool {
           return $this->getOsName() === 'custom';
       }
   }
   

2. Add New Methods Dynamically attach OS-specific helpers:

   $osDetector->addMethod('isDocker', function() {
       return file_exists('/.dockerenv');
   });
   

3. Configuration Overrides Override default behavior via config/os.php:

   'detection' => [
       'windows' => ['regex' => '/Windows NT 10.0/'],
   ],