Product Decisions This Supports
- Native PostgreSQL range types in Eloquent, without a schema workaround. The package supplies cast classes and
Range/MultiRange value objects so columns like int4range, tsrange, tstzrange, and daterange hydrate into typed PHP objects instead of raw strings or paired start/end columns. This is the decision point for any feature whose core entity is an interval, not two dates.
- Availability and booking models. A single range column plus a GiST index and an exclusion constraint lets the database — not application code — enforce "no double-booking." That is a genuine correctness win and removes a class of race conditions that two-column designs push into transactions and
SELECT ... FOR UPDATE.
- Pricing tiers, quantity bands, and eligibility windows.
numrange/int8range cover "price applies from 100–499 units," "discount active for this period," and similar rules where the range is the business rule. This shifts those rules from application branching into queryable, indexable data.
- Roadmap sequencing: interval-heavy features are cheaper than they look. Because range containment, overlap, and adjacency queries are expressible in SQL, a scheduling/availability epic can ship as a schema plus a cast rather than a bespoke service. Useful when arguing to pull availability work forward instead of deferring it behind a service rewrite.
- Build vs buy: buy, and treat it as a thin dependency. It is a small, single-purpose adapter over a database feature, not a domain framework. The real investment is the Postgres schema decision; the package is the glue. Building this in-house means reimplementing casts and query helpers for a well-understood feature — low differentiation, nonzero maintenance.
- What it explicitly does not decide for you. It is not a scheduling engine: no recurrence/generation rules, no timezone policy, no conflict-resolution UX. Those remain product decisions you own.
When to Consider This Package
Adopt when:
- PostgreSQL is the primary datastore and will remain so for the life of the feature. The package is a Postgres-specific capability, not an abstraction layer.
- The entity truly is an interval — bookings, subscriptions, rate windows, validity periods, numeric bands — and you want overlap/containment queries to be index-supported.
- You want database-enforced integrity (exclusion constraints on overlapping ranges) rather than application-level checks.
- You are on a supported Laravel version and can run integration tests against a real Postgres instance. Note the 1.3.1 line declares Laravel 13.x compatibility ahead of general availability, which is a positive responsiveness signal but also means your CI — not the maintainer's — is your safety net until you upgrade.
Look elsewhere or defer when:
- Portability is a requirement. MySQL/SQLite support in the test matrix is not the package's purpose; if tests run on SQLite and production on Postgres, range behavior will diverge in the one place it matters most.
- Multi-database or vendor-neutral product. A range column becomes a hard Postgres dependency in your schema and query layer.
- You need recurrence semantics. iCal-style RRULE expansion, calendar generation, timezone-aware scheduling logic — this package gives you the storage primitive, not the engine.
- Multirange types are needed on older Postgres. Multirange support requires a recent server version; confirm the version floor against your managed-database constraints before committing.
- Bus-factor sensitivity. This is a small, effectively single-maintainer package. If your organization requires a maintained-by-vendor or multi-maintainer dependency for core schema, weigh that explicitly — the cost of replacing it later is schema migration plus query rewrites, so the decision is stickier than the package's size suggests.
- You would be its only user of the feature. If one low-traffic screen needs it, a pair of columns may be the cheaper answer; ranges pay off when queries need overlap/containment and when the database should enforce exclusivity.
On this release specifically: 1.3.1 is maintenance-only. PHPUnit 12 and StyleCI are dev-tooling changes; the Laravel 13.x compatibility work is forward-looking framework support. There are no breaking changes, no new features, no deprecations, and no migration or API changes. It is a low-risk drop-in and does not alter the adoption calculus above — it modestly improves the forward-compatibility story, which is the main maintenance risk for a package this size. Upgrade at your normal cadence and confirm your Postgres-backed test suite still passes.
How to Pitch It (Stakeholders)
To executives: For interval-shaped features — bookings, availability, pricing bands, validity windows — we can use a database capability we already pay for instead of a new service. That means less infrastructure, fewer bespoke conflict-checking code paths, and overlap rules enforced by the database itself, which is where correctness bugs in scheduling logic usually hide. The dependency is small and single-purpose; the commitment is to PostgreSQL, which we have already made. Recommendation: adopt for interval-shaped features, do not treat it as a scheduling engine.
To engineering: This is a thin Eloquent adapter over native Postgres range and multirange types — casts, value objects, and query helpers for containment, overlap, and adjacency. The architectural win is a GiST index plus exclusion constraints, which converts double-booking prevention from an application-level transaction dance into a database invariant. The costs are explicit: Postgres-only schema, real-database integration tests (SQLite in CI will not exercise range semantics), a minimum server version for multirange, and a single-maintainer dependency worth pinning. Release 1.3.1 is maintenance-only — dev-tooling updates plus Laravel 13.x forward compatibility — with no breaking changes, so there is no upgrade work beyond a normal version bump and a green Postgres test run. Keep the range columns isolated behind casts so a future replacement is a schema migration rather than a rewrite.