Download the PHP package atannex/scopable without Composer

atannex/scopable

Declarative state and date scopes for Laravel Eloquent. Declare a model's states once, then use them on queries and on loaded models.

Every state is a rule that does four things, so Post::published() and $post->inState('published') can never disagree:

1. constrain a query to rows in the state;
2. constrain a query to the inverse, NULLs included, so a state and its inverse always split the table in two;
3. check a loaded model in PHP, with no query;
4. change the model so it enters or leaves the state.

What you get:

• States: published / scheduled / draft, boolean flags (is_active, is_featured, is_global…), schedule windows (starts_at / ends_at), expiry, "highlights" (a flag that only counts inside its window, e.g. breaking news), enum and status values, counters under a cap, "within the last N", "older than N", relations, references to other states, and all / any / not composites.
• Inverses and aliases: every state gets not{State}(), plus any names you add (unpublished, inactive, nonGlobal).
• Moments: every state takes an optional moment, e.g. Post::published($tomorrow), $post->inState('published', '2026-12-25').
• Period scopes for every date column: createdToday(), updatedWithin('7 days'), publishedLastMonth(), expiresInNext('3 days'), createdBetween('2026-01-01', '2026-03-31'), createdIn('last quarter')… They compare the raw column against bounds (col >= ? AND col < ?), so indexes are used and no DATE() function runs per row. Calendar periods are cut in your newsroom's timezone.
• Filters and sorts: ->flagged('a', 'b'), ->notFlagged('a'), ->ordered(), ->ordered('desc').
• Default states: hide unpublished rows from every query, like soft deletes, and lift that per query.
• Events: StateEntered / StateLeft when a save moves a tracked state, and when the clock does (scopable:sweep). They are dispatched after commit.
• Real named scopes: states work statically, on relations, inside whereHas, in ->scopes([...]), and anywhere Eloquent checks hasNamedScope() (atannex/retrive's Retriever, for example).
• Safe names: a state that would shadow an Eloquent, query builder or model method (count, latest, fresh, created…), or an existing scopeX method, is refused when the model boots.
• Tooling: scopable:show (states, rules and SQL), scopable:sweep, and a Filament StateFilter.

Install

Declare

Shortcuts

created, updated and deleted date aliases are added automatically when the model has those columns (see scopable.dates).

States from traits

A trait can bring its own states, like Laravel's boot{Trait}: a static defineScopes{TraitName}(Scopes $scopes) runs before the model's defineScopes(). That is how a package concern (matrix's IsModerated) gives every model using it the same states, while the model adds its own:

Every state can be chained with:

Rules

Query

Periods

For every date alias (created, updated, deleted, published, and any you register):

lastDays(7) / In('last 7 calendar days') is today plus the six days before, for day-based stats. A column cast to date (a rollup's day) is compared with dates, not datetimes. Period::constrain($query, 'created_at', 'today') works on any model, HasScopes or not, and $period->applyOverlap($query, 'starts_at', 'ends_at') keeps rows whose own window overlaps the period.

You can also use ->wherePeriod('created', 'last month'), ->wherePeriod('starts_at', Period::nextWeek()) or $post->inPeriod('published', 'today').

Period works on its own too: Period::thisWeek()->apply($query, 'column'), Period::parse('older than 1 year')->contains($date).

Models

How rules change a model:

• toggle: sets the flag on or off.
• reached: sets the date to now (or $from), but keeps an earlier date that has already passed. Leaving clears the date.
• window: starts now unless already started, sets until, and reopens an ended window. Leaving ends it now.
• equals: writes the first value. Leaving writes otherwise.
• all: enters every part. Leaving goes through the first part that can be left.
• any: enters the first part that can be entered. Leaving leaves every part.

Rules that cannot be set directly (under, within, callback…) throw CannotChangeState with the reason.

Default states

Events

->tracked() states fire Atannex\Scopable\Events\StateEntered / StateLeft with $model, $state, $cause (saved or time) and $at. They are dispatched after the transaction commits, so a rollback never announces anything. A row created already in a tracked state fires StateEntered.

The clock moves states without a save (a scheduled post goes live; a campaign ends). List the models in scopable.models and schedule the sweep:

The sweep looks only at rows with a date that crossed "now" since the last run (an indexed range per boundary column), compares each tracked state then and now, and fires the difference. Use --since= to replay a window and --model= to limit the models.

Set scopable.events to false to turn off save events.

Filament

Needs filament/filament.

count: true runs one count per tab; pass numbers from countStates() to count every tab in one query.

Tooling

Config

Testing

The suite runs every state of the fixtures against a grid of rows (NULLs, past, now, future) at many moments, and asserts that the query matches the PHP check and that the state and its inverse partition the table.