Scopable Laravel Package

Getting Started

• Install with composer require atannex/scopable; confirm PHP 8.2+ and Laravel 11/12 before adopting.
• Start with the README for the trait/model setup, expected state/date columns, default-state configuration, and transition-event wiring.
• First practical use case: a content model with draft, published, and scheduled states plus publish/expiry dates. Add the package trait, configure the relevant columns, then use published() for public listings, scheduled() for editorial queues, and draft() for admin views.
• Use the matching PHP checks in policies, controllers, and Blade views so query logic and in-PHP decisions stay aligned.

Implementation Patterns

• Keep lifecycle state declarative on the model: configure state and date columns once, then use package scopes as the shared query vocabulary instead of scattering raw where clauses.
• Compose scopes for common screens: published + highlighted for homepages, active + within schedule window for feature flags, scheduled + ordered by publish date for admin queues, and limit/composite scopes for curated lists.
• Mirror SQL scopes with PHP checks in authorization and presentation code. For example, use the package’s published/scheduled/draft and active/expired/highlighted checks rather than reimplementing date comparisons manually.
• Use package mutators in controllers, form requests, or action classes for transitions such as publish, schedule, and expire. Wrap them in transactions when the transition also updates content or related records.
• Use period scopes such as createdThisWeek() and publishedWithin(...) for dashboards, RSS/sitemaps, reporting, and analytics endpoints; pass explicit date ranges and keep timezone handling consistent.
• Set sensible default states in model configuration so newly created records do not require every caller to specify a state.
• Listen for transition events to invalidate caches, send notifications, write audit logs, or trigger search indexing. Keep those listeners idempotent.
• Add composite indexes for the state/date columns used by common scopes, especially published/scheduled/expiry and active-flag combinations.

Gotchas and Tips

• Scheduled vs published boundaries need explicit tests around “now.” Confirm whether published scopes exclude future-dated records and whether expiry is inclusive or exclusive.
• Null publish/expiry dates can change scope behavior. Decide whether null means “always active,” “never active,” or “no window,” and test those cases.
• Default states can hide missing data during imports and seeders. Be explicit in bulk imports and verify defaults do not publish content unintentionally.
• Transition events may fire only through package mutators, not raw attribute updates. If listeners matter, use the provided transition methods rather than mass-assigning state fields.
• Composite scopes can obscure SQL precedence. Inspect generated SQL with toSql() or query logging when combining published, active, highlighted, and window scopes.
• Confirm exact column names, custom state values, and event names in the README before rolling out broadly; v1.0.0 is the first stable release, so pin the version and cover transitions with feature tests.
• Keep package-specific lifecycle logic centralized in the model/trait and action classes. Avoid mixing package scopes with hand-written date logic in controllers, or the SQL and PHP checks will drift.