Download the PHP package byrcsc/laravel-hold without Composer

Laravel Hold

Temporary resource holds for Eloquent models: any model can be held, any model can hold, with capacity-aware atomic acquisition, expiring or indefinite claims, and lifecycle events.

The package provides the hold engine. Your application keeps ownership of its UI, users, checkout flow, and what being held actually means.

Installation

Install the package and publish its migration:

Publish the configuration before the migration when you need a custom table name or non-integer model keys:

The published config/hold.php has three keys:

Set HOLD_HOLDABLE_KEY_TYPE and HOLD_HOLDER_KEY_TYPE to uuid, ulid, or string when the models on either side of a hold do not use integer keys. Both shape the identity columns, so set them before you migrate.

What a hold is

A hold is a temporary claim by one holder (any model: a user, a cart, a session) on one holdable (any model: a seat, a domain name, a rental unit). The rules are small and strict:

• Every holdable has a capacity, default 1. A capacity of 1 means the resource is exclusive: at most one active hold at a time. A capacity of N suits slot-style resources such as event tickets or stock units.
• One hold consumes exactly one slot. There is no quantity on a hold. Holding three seats means three holds.
• A hold is active when it has not been released and its expiry, if it has one, is in the future. The timestamps are authoritative: the instant expires_at passes, the slot is free for the next acquirer. No scheduler or worker is required for correctness.
• A hold with no expires_at is indefinite and blocks its slot until it is explicitly released.
• Acquisition is atomic. Two concurrent acquirers racing for the last slot cannot both win, on MySQL, PostgreSQL, and SQLite.

The package controls hold state and nothing else. It does not decide what a held resource means for your application: it does not hide it, price it, reserve payment for it, or queue the next person in line. Your application reads hold state and decides.

Quick start

Add Holdable to the model that can be held:

Acquire, extend, and release a hold:

That is the whole core loop. Everything below is detail.

Capacity

Capacity is a fact about the resource, declared on the model:

The default implementation returns 1. Capacity is deliberately not an argument to acquireHold(): every concurrent acquirer must agree on the same limit for atomic acquisition to mean anything.

Acquiring

acquireHold() returns the new Hold, or null when no slot is free:

acquireHoldOrFail() does the same but throws ByRcsc\LaravelHold\Exceptions\NoAvailableSlotsException instead of returning null. The exception carries the resource it refused as $exception->holdable.

Both parameters are optional. Omit expiresAt for an indefinite hold; omit metadata when you have no context to attach.

acquireHold() is always an attempt to create a new hold. It never silently returns an existing one, and the same holder may hold the same resource more than once when capacity allows (that is how you hold three seats). For double-submit safety, check first:

Acquisition takes a row lock on the holdable and counts inside a transaction, so concurrent acquirers are serialized per resource, and never against unrelated ones. SQLite has no row locks and serializes writers itself, which is correct but can surface a "database is locked" error instead of a clean null. Concurrency and databases covers the connection settings that avoid it.

Expiration

Expiry is lazy. Every check the package performs, availableSlots(), isFullyHeld(), the active() scope, the acquisition count, reads the clock, never a stored status. An expired hold stops blocking its slot at the moment expires_at passes, whether or not any command has run.

The hold:expire command exists only to tell you about it. It stamps holds that have passed their expiry and fires a HoldExpired event for each, exactly once, including across overlapping runs. A hold released after its expiry passed but before the command reached it is left alone: the release is what happened to it. Schedule it if you listen for that event:

If you do not listen for HoldExpired, you do not need the scheduler at all.

Note that HoldExpired fires when the command notices, not at the expiry instant. A hold can expire and its slot be re-acquired by someone else before the event fires. Availability is exact; the event is best effort.

Extending and releasing

extend() pushes expires_at further out from its current value, not from now:

It throws ByRcsc\LaravelHold\Exceptions\CannotExtendHoldException when the hold is released, already expired, or indefinite. The message says which of the three it was, and $exception->hold carries the hold itself. An expired hold cannot be revived by extension: the slot may already belong to someone else. Re-acquire instead.

Releasing stamps released_at, optionally records who released it (released_by, polymorphic, any model), and merges any metadata you pass into the hold's metadata. Released holds stay in the table as history until you prune them.

Releasing twice is a no-op. The first stamp, the first releaser, and the one HoldReleased event all stand, so a double-submitted cancel button cannot rewrite who released a hold or when. Releasing and extending covers the merge depth and the expired-then-released case.

Reading holds

Add HasHolds to holder models to read from the other direction:

A model can be both. Each trait names its relations holds and activeHolds for its own side of the table, so composing them needs one resolution block telling PHP which side keeps the plain names, after which holdsAsHolder and activeHoldsAsHolder reach the other side. Holdables and holders carries that block verbatim.

The whole read surface:

Status is computed from the timestamps at read time. There is no stored status column to drift out of date between scheduler runs.

Events

Each event exposes the Hold as a public readonly property. Events are the extension point for anything user-facing. Holders are polymorphic and may not be notifiable, so the package ships no notifications; a listener reads $event->hold->holder and decides who to tell. Events and listeners has a worked listener.

Pruning

Released and expired holds accumulate as history. Delete old ones on your schedule:

This removes holds that were released, or passed their expiry, more than the given number of days ago. Active and indefinite holds are never pruned.

--days must be a whole number, zero or more; anything else exits non-zero without deleting a row.

Documentation

Full documentation is at docs.rcsc.dev/laravel-hold.

Out of scope

These are decisions, not omissions. The default answer to a feature request in this list is this section:

• Quantity per hold. One hold is one slot, always.
• Waitlists and queues. Who gets a freed slot next is application policy.
• Hold approval. A hold either succeeds atomically or fails. If claims need review, see laravel-approval.
• Notifications. The events carry everything a listener needs.
• Transition-log audit trail. The hold row records who released it and when; a full actor-attributed history table is application territory.
• UI, pricing, and payments. The package has no opinion on what a hold costs or looks like.

Versioning

The package follows semantic versioning.

• Upgrading within 1.x is safe. Nothing you use will break.
• Only a new major version, like 2.0.0, can break your code.
• If the README or the documentation describes it, it is safe to build on. If they don't, treat it as internal and expect it to change.

Bug fixes go into the newest version only. To get a fix, upgrade to it.

Questions and issues

• Stuck, or have an idea? Start a discussion. Usage questions and feature ideas both live there.
• Found a bug you can reproduce? Open an issue. A failing test is the fastest way to a fix, and a short reproduction is the next best thing.
• Found a security problem? Please don't open a public issue. See SECURITY.md for how to report it privately.
• Planning a pull request? CONTRIBUTING.md covers the setup and the three checks it needs to pass.

This package is maintained by one person, so replies can take a while. Everything gets read.

License

MIT. See CHANGELOG.md.