Operation System Enum Laravel Package

Getting Started

This package provides a PHP enum (and likely small helper methods) for representing operating systems, so you don't hand-roll string constants like 'windows', 'linux', 'macos' across jobs, migrations, and API payloads.

Minimal steps:

1. Install it: composer require tourze/operation-system-enum. It is almost certainly a pure-PHP enum with no service provider, config file, or migrations to publish — confirm by checking composer.json for extra.laravel before running vendor:publish.
2. Look first at the enum class itself (src/ — typically one file, e.g. OperationSystem or OperatingSystem). Read the case names and, if backed, the backing values. Those values are the contract you'll persist in the database and expose over the API, so decide early whether you accept them verbatim.
3. First use case: type-hint it in a job or DTO that targets a host. For example, a deployment or agent job that needs to branch on the target OS:

use Tourze\OperationSystemEnum\OperationSystem;

final class DeployAgent
{
    public function __construct(public readonly OperationSystem $os) {}

    public function command(): string
    {
        return match ($this->os) {
            OperationSystem::WINDOWS => 'agent.exe',
            OperationSystem::LINUX, OperationSystem::MACOS => './agent',
        };
    }
}

The 1.0.0 bump from 0.0.2 is most likely an API-stability declaration rather than a feature drop — the release notes only link a diff. Before adopting, skim that changelog for renamed cases or changed backing values, since those are the only breaking changes a package like this can realistically ship.

Implementation Patterns

Eloquent casts. If the enum is backed, cast the column directly:

protected function casts(): array
{
    return ['os' => OperationSystem::class];
}

Store the backing value in a string column (nullable if the OS is discovered asynchronously, which it usually is — agents report in after the record exists). Add a OperationSystem::cases()-driven migration comment or a check constraint if you need DB-level safety.

Validation. In Laravel 9+, prefer Rule::enum(OperationSystem::class) over in: lists so adding a case doesn't require touching every FormRequest:

'os' => ['required', Rule::enum(OperationSystem::class)],

Detection at the boundary. The enum should be constructed in exactly one place — a small resolver that maps php_uname('s'), a User-Agent header, or an agent's self-reported string onto a case. Everything downstream receives the enum, never a string. This keeps the mapping (including unmapped/unknown OS handling) in one file and makes the package easy to swap out.

Branching. Use match on the enum rather than if chains; it's exhaustive-checked at the type level once the enum is fully covered. For per-OS lookup tables (install paths, shell flavors, package managers), key a config array by $os->value and resolve lazily — this keeps the logic out of the enum and out of your models.

API surface. Return the enum directly from resources when you want the backing value in JSON (BackedEnum serializes to its value automatically); if your public API must stay decoupled from the package's naming, map explicitly to your own DTO strings instead of relying on implicit serialization.

Gotchas and Tips

• Backing values are a database and API contract. Renaming a case or changing a backing value is a silent data migration. If the 1.0.0 release touched any values, write an explicit UPDATE migration rather than trusting casts to handle old rows — an unmapped backing value throws ValueError on hydration, not a null.
• null vs unknown. Check whether the package has an explicit UNKNOWN/OTHER case. If it doesn't, don't invent one by casting — keep the column nullable and treat null as "not yet detected," so you can distinguish "we don't know yet" from "it's something we don't support."
• Enums aren't arrays or strings. in_array($os, ['linux']) is always false, and == comparisons across enum instances behave unexpectedly if you mix cases from this enum with another OS enum. Use === against cases, or $os->value when crossing a string boundary.
• No Rule::enum() on older Laravel. If you're below 9.x, fall back to Rule::in(array_column(OperationSystem::cases(), 'value')) — build it from cases() so it can't drift.
• Queue payloads. Enums serialize cleanly through Laravel's queue serialization, but if you ever hand-craft payloads or use a non-Laravel queue consumer, send ->value and rehydrate with OperationSystem::from() (or tryFrom() at untrusted boundaries). from() throws on unknown input — that's what you want for internal calls, not for user input.
• Extension points are limited by design. An enum can't be extended, so if you need per-tenant or per-platform OS labels, wrap it in your own class or map it to a config array rather than trying to subclass. Treat the package as a value vocabulary, not a behavior layer — no methods on the enum should reach for the container.
• Version pinning. With a 1.0.0 tag and a prior 0.0.x line, pin to ^1.0 in composer.json and read the full changelog diff once; the release notes here are just a link, so the actual scope of change is unverified from the notes alone.