Laravel Options Laravel Package

Product Decisions This Supports

• Build vs. buy for a runtime settings store. This package covers the undifferentiated plumbing behind app-level options: persistence schema, cached reads, typed get/set, JSON-valued updates, selected-key reads, null/default handling, deletion, a console command, and a provider abstraction with events. A PM can use it to justify not spending roadmap capacity on an in-house settings table plus cache-invalidation layer, and instead spend that capacity on customer-facing work.
• Platform modernization sequencing. 4.0.0 requires PHP 8.3+ and Laravel 13.x, with Laravel 9–11 explicitly directed to stay on 3.x. That converts "when do we move the platform forward?" from an abstract infrastructure wish into a concrete dependency decision with a known fallback (pin 3.x). It is a useful forcing function for the PHP/Laravel upgrade roadmap.
• Where dynamic configuration lives. The provider abstraction (including custom providers and provider reuse) and change events support a decision about which settings belong in env/config files (deploy-time, immutable) versus a database-backed option store (runtime-editable, tenant-overridable). This is a recurring architectural debate that the package lets you settle cheaply.
• Correctness exposure on documented read paths. 4.0.0 fixes TypeErrors in the documented no-argument Option::get() read and in Option::get('0'). Both were reproduced before fixing and are now covered by regression tests. Any product surface relying on default fallbacks or zero-valued settings (0 as a legitimate value — quotas, limits, toggles, prices, counters) was exposed; this release closes that hole.
• Runtime upgrade hygiene. Making provider(?string $name = null) explicitly nullable removes a reproduced PHP 8.4 deprecation without changing accepted inputs — a maintenance-cost reduction that matters when weighing an early move to newer PHP minors.
• Confidence for edge-case-heavy features. Expanded integration coverage for selected keys, JSON updates, null/default behavior, deletion, the console command, and provider reuse/custom providers directly de-risks features like per-tenant overrides, nullable settings, and admin-editable structured config.
• Upgrade cost assessment. Because the persistence schema and the provider/event APIs are preserved, the 4.0.0 break is environmental (runtime and framework versions), not a data migration or API rewrite. That makes the upgrade estimable and reversible.

When to Consider This Package

Consider it when:

• You need application settings or options editable at runtime without a deploy, read frequently enough that caching matters.
• You are on, or actively planning, Laravel 13 with PHP 8.3+ (or are willing to pin 3.x in the interim).
• You need custom providers — for example tenant-scoped options — and want events on change so caches or downstream state can react.
• Your team is small and you would rather adopt a focused package than own schema design, cache invalidation, and console tooling for settings.
• You want typed/JSON values and explicit null/default semantics rather than a stringly-typed key-value table.

Look elsewhere, or scope carefully, when:

• You are on Laravel 9–11 or PHP below 8.3: stay on 3.x, pin the constraint, and schedule the platform move. Do not attempt 4.0.0 on an unsupported runtime.
• You need a full feature-flag platform: targeting rules, percentage rollouts, experiment assignment, audit trails, approval workflows, or a settings admin UI. This is a settings store, not a flagging or experimentation system.
• You need versioned or signed configuration, secret management, or a multi-backend config strategy — that is a different (and heavier) concern.
• A static config file genuinely suffices; a database-backed option store adds an operational dependency you may not need.
• Single-maintainer / release-cadence risk is unacceptable for a critical path. Assess bus factor and your ability to vendor or fork; the package's stability here is good (schema and public APIs preserved across a major), but treat it as a dependency to monitor.

How to Pitch It (Stakeholders)

For executives (one paragraph): We are adopting a small, focused Laravel package for runtime-editable application settings instead of building and maintaining that plumbing ourselves. Version 4.0.0 is primarily a maintenance and correctness release: it fixes two reproducible read bugs on documented code paths, removes a PHP 8.4 deprecation, and materially expands integration tests — while preserving the database schema and the provider/event APIs, so there is no data migration. The breaking change is environmental only: it requires PHP 8.3+ and Laravel 13, and teams on older Laravel stay on 3.x. Net effect: lower build cost, fewer latent setting-read defects, and a clean alignment point with our platform upgrade plan.

For engineering: Treat this as a dependency bump gated on the PHP 8.3 / Laravel 13 upgrade; read UPGRADE.md before moving off 3.x. No schema or provider/event API changes, so rollout risk is low and rollback is a version pin. The Option::get() no-argument and Option::get('0') fixes plus their regression tests mean any code relying on defaults or zero values should be re-verified rather than assumed broken — this release makes those paths correct. Validation is credible: 19 tests / 53 assertions passing on PHP 8.3, 8.4 and 8.5 with highest dependencies, and on 8.3 with lowest secure dependencies, with Pint, Composer validation, platform checks, dependency audits, and security-advisory blocking all enabled.

Ask: approve the version bump as part of the platform-upgrade workstream, and confirm the 3.x pin for any service that cannot move to Laravel 13 yet.