Os Laravel Package

Product Decisions This Supports

• Build vs. buy (and "buy" is a stretch here): This is a very small, single-purpose utility — an OperatingSystemFamily enum plus detection. The real decision isn't "which package," it's "do we accept a third-party dependency to avoid writing ~20 lines of php_uname()/PHP_OS_FAMILY parsing." Frame it that way in the ticket; it changes the answer.
• Cross-platform roadmap scoping: Any feature that behaves differently on Windows vs. macOS vs. Linux (CLI tooling, file permissions, process management, shell invocation, path handling) needs a single source of truth for "what OS am I on." This package is one candidate for that seam.
• Support matrix as a product commitment: Choosing this enum forces you to write down which families you support (Linux, Windows, macOS, etc.) and what happens on anything else — WSL, FreeBSD, Alpine-in-Docker, AWS Lambda's environment. That artifact is more valuable than the code.
• Feature gating and UX: Enables decisions like "hide this menu item on Windows," "disable this Artisan command on non-Linux," or "show platform-specific onboarding." Cheap to implement, visible to users, low blast radius.
• Technical-debt paydown as a roadmap item: Replacing scattered str_contains(PHP_OS, 'WIN') checks with typed comparisons is a small, schedulable refactor with a clean definition of done. Good candidate for a maintenance sprint rather than a feature sprint.
• Not a moat: This is commodity logic. Don't let it consume roadmap attention beyond the initial decision.

When to Consider This Package

Adopt if all of these hold:

• You ship to two or more OS families and already have (or foresee) more than a handful of OS-conditional branches.
• You're on PHP 8.1+ and comfortable making enums part of your public/internal API surface.
• You want type-safe comparisons and IDE autocompletion so invalid OS strings can't reach production.
• Your dependency-review process is lightweight enough that adding a micro-package isn't a multi-week security/SBOM exercise.

Look elsewhere — or just write it yourself — if:

• Your app is single-platform (a Linux-only SaaS backend). The dependency buys you nothing; PHP_OS_FAMILY is already in core PHP.
• You need version-level granularity (macOS 13 vs. 14, Windows 10 vs. 11) or distro detection. Family-level only.
• Supply-chain risk tolerance is low. Zero stars, zero dependents, and releases that just point at the parent monorepo's changelog mean you are effectively adopting php-standard-library/php-standard-library — evaluate that repo, not this one. If that's too much surface area for the benefit, write an internal helper class and own it.
• Windows/WSL behavior matters. WSL reports as Linux to PHP; if your product must distinguish "Linux server" from "developer on WSL," this enum won't do it and you'll need a deliberate fallback design.
• You need a stable public API contract. A micro-package split out of a monorepo can be reabsorbed or deprecated; pin the version and keep usage behind your own thin abstraction so swapping it out is a one-file change.

Recommendation as written: treat it as a convenience, not an architecture decision. Wrap it behind a single internal Platform service/facade rather than referencing the enum throughout the codebase. That keeps the exit cost near zero and gets you the type safety today.

How to Pitch It (Stakeholders)

To executives (one paragraph): "We have platform-specific behavior sprinkled through the code as string checks, which is where 'works on my machine' bugs come from. This is a tiny, MIT-licensed, zero-dependency PHP enum that makes 'which OS is this?' a typed value instead of a guess. It's not a strategic investment — it's a small consistency fix that makes cross-platform releases cheaper to support. Cost: one dependency and a short refactor. I'd approve it only if we're actually shipping to more than one platform."

To engineering (the actual argument): "It replaces str_contains(PHP_OS, 'WIN')-style checks with OperatingSystemFamily::current()->is(OperatingSystemFamily::WINDOWS) — typed, autocompleted, greppable, and testable by mocking one enum. It's additive, PHP 8.1+, no runtime cost. Two caveats we should own: (1) it's a micro-package with no community traction, so pin it and keep it behind our own Platform wrapper so we can drop it in an afternoon; (2) it detects family, not distro or WSL — if we need that, we design it ourselves on top. Suggested first step: land it in one CLI command, not a repo-wide refactor."

To the sceptical engineer in the room: "Yes, you could write this in twenty lines. That's a legitimate answer and I'd accept it. The case for the package is consistency and not re-litigating the edge cases in five places — not capability."