Operating System Laravel Package

Product Decisions This Supports

• Cross-platform support commitments. This package answers a roadmap question we currently answer ad hoc: do we officially support Windows/macOS for our CLI tooling and Artisan commands, or declare Linux-only? An OS abstraction layer makes "we support N platforms" a bounded engineering cost instead of an open-ended bug category.
• Build vs. buy for platform detection. The competing option is a ~15-line internal helper around PHP_OS_FAMILY, php_uname(), and DIRECTORY_SEPARATOR. Buying gets us tested edge cases (non-POSIX Windows paths, shell invocation differences); building gets us zero dependency surface. This decision should be made per-surface, not company-wide.
• Testability of platform-conditional code. The real product value is not OS detection itself — it's the seam. If OS is an injected dependency rather than a static call, we can test the Windows code path on Linux CI. That converts "cannot reproduce on our machines" bugs into unit tests. This is the strongest argument for adoption.
• Distributed-package strategy. If we ever publish a Composer package, consumers on mixed OSes become our problem. Adopting an abstraction early avoids a retrofit.
• Roadmap deferral. It makes "not yet" a cheap answer for OS-specific features (native notifications, per-OS file watching, platform-specific binaries). We can defer without accumulating a mess of scattered if (PHP_OS_FAMILY === 'Windows') branches.
• Use cases where it earns its keep: Laravel Zero / NativePHP-style desktop or CLI apps, installers and scaffolding commands, dev-tooling that shells out to git/rsync/ffmpeg with per-OS flags, path and temp-directory handling across environments.
• Use cases where it does not: our standard containerized web app. Homogeneous Linux, one target, no branching. Adoption there is pure overhead.

When to Consider This Package

Adopt when most of the following hold:

• We ship or plan to ship software that runs on more than one OS family — including the realistic case of Windows developer laptops versus Linux production.
• We shell out to external binaries or touch the filesystem in ways whose semantics differ per platform.
• We publish a package to third parties who control their own runtime.
• We need a mockable seam for OS in tests, or we've already been bitten by untestable platform branches.
• The team is comfortable with Innmind's conventions (immutable value objects, explicit dependency injection, functional-leaning APIs) — or we intend to wrap it behind our own one-method adapter regardless.
• We're already inside the Innmind ecosystem for filesystem/immutable collections, so the marginal dependency cost is ~zero.

Look elsewhere — or write the helper in-house — when:

• There is a single deployment target (Linux containers) and no credible near-term plan to change that.
• The requirement is genuinely a three-line check. PHP_OS_FAMILY is a language primitive; a package that abstracts the entire system is disproportionate to "am I on Windows?"
• Supply-chain and bus-factor risk are weighted heavily in our dependency policy. Nine stars, zero dependents, and a single maintainer is a thin support story for infrastructure-adjacent code. If it is load-bearing, it must be vendored or wrapped.
• Our dependency budget is tight. The abstraction likely pulls transitive Innmind packages (immutable collections, filesystem) whose weight exceeds the problem being solved.
• We need hardware/inventory-level detail (CPU, memory, distro) — that's a different tool, and better served by dedicated detectors or symfony/process probes.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a small, MIT-licensed utility that lets our code ask "what system am I running on?" in a clean, testable way instead of scattering platform checks throughout the codebase. It has near-zero acquisition cost and no licensing friction. Its strategic value is narrow: it matters only if we commit to supporting more than one operating system for our command-line tooling or any package we distribute. It is not a feature, not a differentiator, and not something to fund as an initiative — it's a low-cost option we should permit engineering to take if and when a cross-platform commitment is made. I'd flag one governance point: it is maintained by a single author with minimal adoption, so if it becomes load-bearing we should isolate it behind our own interface rather than let it spread.

For engineering (the actual argument): The deliverable isn't OS detection — you can do that with PHP_OS_FAMILY. The deliverable is an injectable OS boundary, which makes platform-conditional branches unit-testable on a single CI runner. That directly reduces a class of bugs we cannot reproduce locally. The trade-offs are real and should be stated plainly: the composite opportunity score is low (~17, opportunity ~33), driven by adoption rather than code quality; there are zero dependent packages in the wild and nine stars, so we are effectively the only consumer and must own the risk; the maintainer's design vocabulary (immutable value objects, explicit DI, functional style) is idiomatic to Innmind and unidiomatic to a typical Laravel team, which is a real onboarding cost. Recommendation: do not adopt directly into application code. Wrap it behind a two-method internal SystemEnvironment contract, keep the third-party package as the only implementation, and preserve the option to replace it with ~50 lines of our own code in a single PR. That gives us the testing seam and the swap-out guarantee, and caps the downside at an afternoon of work.