Eloquent Publishing Laravel Package

Product Decisions This Supports

• Build vs. buy for content lifecycle plumbing. The package's entire surface area — a published_at nullable timestamp, publish()/unpublish() state transitions with publishing/published/unpublishing/unpublished events, ~12 query scopes, and migration blueprint helpers — is roughly a half-day of engineering work to replicate. The decision it informs is therefore not "can we afford it" but "do we want every team to hand-roll a slightly different naming convention and status-check semantic across Posts, Pages, Announcements, Job Listings, and Docs?" Adopting one convention buys consistency cheaply.
• Scoping a scheduled/embargoed publishing feature without a queue. publish(Carbon::parse('tomorrow')) plus isPlanned() / onlyPlanned() gives you a forward-dated release capability in an afternoon. This directly supports roadmap items like "announcements go live at a set time," "press releases embargoed until X," or "seasonal promos activate on date."
• A critical caveat for that roadmap item: scheduling here is passive. Nothing fires at the scheduled moment — the record simply starts matching onlyPublished() on the next read. Any requirement phrased as "notify subscribers / send a push / trigger a webhook at publish time" is not satisfied by this package and still requires a scheduled job or observer outside it. Do not let a stakeholder hear "it supports scheduled publishing" and infer "it supports publish-time automation."
• Whether to invest in editorial workflow as a product surface. This package models publishing as a binary (published_at set vs. null). It cannot distinguish "draft in progress," "in review," "approved," or "previously live, now retracted." If the roadmap includes editorial roles, approval gates, or retraction with history, that is a meaningfully larger product decision this package neither makes for you nor blocks.
• MVP acceleration for read-heavy public features. Blog, changelog, docs, marketing pages, event listings, knowledge base — anything where "hide until date" is the entire requirement. The migration helper ($table->publishes(), publishesTz(), dropPublishes()) plus the PUBLISHED_AT constant for custom column names means no schema debate per team.
• Use cases worth flagging as non-fits: multi-locale publish timing (one date column, one schedule), per-audience/segmented release, content versioning, and CMS-grade authoring. Those are product investments, not package choices.

When to Consider This Package

Adopt when all of the following hold:

• You are on Laravel 11+ / PHP 8.2+ (v4.0.0 explicitly dropped Laravel 10 and PHP 8.1 — verify compatibility before assuming it works on your stack).
• "Published" genuinely means nothing more than a timestamp in the past for that model. No draft/review states, no per-locale schedules.
• You have several models that need this, or you expect to — the payoff is convention, not code volume.
• Your team is comfortable with the single-maintainer risk: 20 stars, 0 dependents, one author. Mitigating factor: MIT license and a genuinely tiny surface area, so a fork or inline copy is a low-cost exit. That is the main reason this is a defensible tactical dependency rather than a strategic one.
• You accept that unpublish semantics are lossy — as documented, unpublish() clears the date. If you need to know when something was live and who took it down, that is your own audit table. Confirm this behavior in the source before committing.

Look elsewhere when:

• You need a real editorial workflow (draft → review → scheduled → published → archived) with roles and approvals. This package is a column plus scopes; it will not grow into a CMS.
• You need publish-time side effects (emails, webhooks, cache warming, search indexing). You can hook the published/unpublished events, but scheduled items will not emit them unless you add a cron that calls publish() — plan for that work explicitly.
• You need multi-timezone correctness at scale. publishesTz() exists for timestampTz columns, but store-and-compare discipline is still on you; a globally distributed audience reading "goes live at midnight" is a real spec, not a column type.
• You are already using a package that owns model lifecycle (a full CMS, a headless content platform, or an existing internal Publishable trait). Adding a second convention is a net negative.
• Query performance on large tables matters. The scopes compile to where published_at <= now()-style predicates; the package does not add an index. On a table you expect to filter this way at scale, budget the migration for an index on published_at yourself.

How to Pitch It (Stakeholders)

For executives (30 seconds): This is a small, free, MIT-licensed Laravel add-on that standardizes one thing we would otherwise build slightly differently on every content type: a "publish date" for database records, with the handful of queries we need to show only live content or only upcoming content. It costs essentially nothing to try and nothing to remove — the code is small enough to copy into our own repository if the maintainer ever walks away. It shortens time-to-market for any date-gated content feature by days, not months. It is not a content management system and should not be presented as one: it will not give us editorial approvals, and "scheduled" content becomes visible on the scheduled date but does not trigger anything (no emails, no notifications) without additional engineering we would scope separately.

For engineering (the honest version): ~50–150 lines of trait plus scopes you could write yourself, so evaluate it as a convention dependency rather than a capability dependency. Requires Laravel 11+/PHP 8.2+ on v4. Gives us publish() / unpublish() / isPublished() / isPlanned() and composable scopes (onlyPublished(), onlyPlanned(), latestPublished(), etc.), plus $table->publishes() migration helpers and publishing/published/unpublishing/unpublished events to hook. Three things to settle before merging: (1) unpublish() clears published_at, so decide where historical publish timestamps live; (2) published_at needs an index on any table we will actually filter at volume; (3) "planned" is passive, so anything requiring action at publish time needs a dedicated scheduled command. Single maintainer, low download count, no downstream dependents — treat it as vendorable: MIT, small, and worth pinning a major version (^4.0) with a note that forking is our fallback, not a rewrite.