Service Library Laravel Package

Technical Evaluation

Architecture fit win32service/service-library is a thin, framework-agnostic PHP abstraction over the win32service extension — it is not a Laravel package in the conventional sense (no service provider, no config publishing, no artisan surface). Its value to a TPM is as a low-level dependency beneath an internal Laravel console-command wrapper that registers and controls a Windows service running php artisan <command>. v1.1.0 adds a pre-shutdown behavior hook, which fits naturally into that wrapper: it gives us a place to drain queues, flush buffers, and release locks before the SCM terminates the process. That is a meaningful reliability primitive, not a cosmetic change.

Integration feasibility Feasible but gated on environment, not on the library. Hard requirements are Windows, the win32service PECL extension at a compatible version, and elevated privileges to install/remove services. None of that can be satisfied in typical Linux CI, so integration testing must run on a Windows runner or a Windows host. The documentation rewrite in this release measurably lowers the cost of the first integration, since the prior docs were the largest unknown.

Technical risk

• Signature change under a minor version. "add new function signature" is the single highest-risk line item. Semver says minor releases are non-breaking, but PHP signature changes are breaking for anyone implementing interfaces, extending classes, or type-hinting against the old shape. Must be verified against our own code before adopting.
• New behavior with SCM semantics. Pre-shutdown is triggered on system shutdown, not on a normal service stop. Teams routinely conflate the two and assume a handler registered for stop will fire at shutdown. Verify the library's documented contract and test an actual OS restart, not just net stop.
• Windows-only blast radius. A defect here manifests as a stuck or un-startable service, which is an availability incident rather than a page error — higher severity per occurrence than typical library bugs.
• Ambiguous changelog entry. "quic add new function signature" reads like an internal branch name; it is not self-describing and cannot be assessed from the notes alone.

Key questions

1. Does the "new function signature" change any method our wrapper overrides or calls? Diff v1.0.2...v1.1.0 at the source level.
2. Is pre-shutdown opt-in (new interface/handler) or default-on? Opt-in is acceptable; default-on requires a behavior regression test.
3. What is the minimum PHP and win32service extension version for v1.1.0, and does the tests upgrade imply a raised floor?
4. Does the rewritten documentation state an explicit support matrix for Windows Server versions?

Integration Approach

Stack fit Assumes a Laravel app running on Windows (IIS + PHP FastCGI, or a service-managed artisan command). The library sits below our code; we should wrap it rather than call it directly from application code so the SCM-facing surface stays in one place. If the team is Linux-first, this package is out of scope entirely — flag that early, because it is a common misread of the package name.

Migration path Coming from v1.0.2 (or greenfield at v1.1.0) this is a minor bump and should be a lockfile change plus a smoke test, not a refactor. Pin to ^1.0.2 until the signature question is resolved, then widen to ^1.1.0. If a signature change is confirmed to touch our wrappers, treat that single adapter file as the migration surface — the blast radius should be one class, not the application.

Compatibility Confirm PHP version, win32service extension version, and Windows Server SKU against the rewritten docs. Pre-shutdown support depends on SCM behavior; older Windows versions handle the pre-shutdown notification differently, so version the feature behind a config flag and enable per target host rather than globally.

Sequencing

1. Source-level diff v1.0.2...v1.1.0; answer the signature question. Blocks everything else.
2. Stand up a Windows test host with the extension and a throwaway service.
3. Adopt v1.1.0 with pre-shutdown disabled; confirm parity with current behavior.
4. Enable pre-shutdown on the test host; validate with an actual OS restart, plus a normal stop, plus a kill.
5. Roll to one production host, then fleet-wide.

Operational Impact

Maintenance Low ongoing surface, but the maintainer appears to be effectively a single person (@macintoshplus authored all four PRs). Bus factor is the dominant long-term risk, and it is not mitigated by this release. Budget for the possibility of vendoring or forking.

Support No commercial support; reliance is on GitHub issues and the rewritten documentation. The docs rewrite is the most operationally valuable item in this release because it converts tribal knowledge into a runbook input. Internal support still requires someone who understands SCM semantics — that expertise, not the library, is the constraint.

Scaling Scales horizontally by host count, not by request volume. Each Windows host runs its own service instance; there is no clustering concern. The practical scaling limit is operational: every host needs the extension, matching PHP builds, and correct service registration, so provisioning must be automated (image-baked or config-managed) before going past a handful of hosts.

Failure modes

• Service fails to start (extension mismatch, wrong PHP binary path, permissions) — detectable, loud.
• Service starts but pre-shutdown handler throws or hangs — SCM applies a timeout and force-terminates; silent data loss risk if we put cleanup logic there without a timeout guard.
• Handler registered for stop but expected at shutdown (or vice versa) — subtle, only surfaces during an incident.
• Upgrade to v1.1.0 breaks a subclass due to signature change — presents as a fatal error at service start, i.e. an outage on restart rather than at deploy.
• Windows Update forced reboot bypasses normal stop path — pre-shutdown is exactly the mitigation, which is the strongest argument for adopting this release.

Ramp-up Modest for a PHP developer familiar with console commands; the conceptual load is Windows service lifecycle, not PHP. Estimate one engineer-day to first working service with the new docs, plus a half-day for the pre-shutdown validation cycle including a real reboot. Plan for at least one person to own Windows service lifecycle knowledge explicitly — it does not diffuse across a team naturally.